> ## Documentation Index > Fetch the complete documentation index at: https://docs.migma.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create Segment > Create a new segment with optional filters. Requires API key with audience:write. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/segments openapi: 3.1.0 info: title: Migma.ai API (v1) description: >- API for managing brands, contacts, email generation, sending, and integrations. license: name: MIT version: 1.0.0 servers: - url: https://api.migma.ai description: Production security: - apiKeyAuth: [] tags: - name: Projects/Brands description: Manage projects (brands) and import from websites - name: Contacts description: Manage your contacts, segments, tags, and topics - name: Segments description: Create and manage dynamic contact segments - name: Tags description: Organize contacts with tags - name: Topics description: Manage subscription topics and preferences - name: Emails description: Generate, send, and export emails - name: Email Validation description: Validate email content for compatibility and deliverability - name: Email Previews description: Preview emails across devices and email clients - name: Domains description: Manage sending domains and verification - name: Webhooks description: Manage webhook endpoints for real-time event notifications - name: Events description: Record customer events and conversions - name: Integrations description: Third-party platform integrations - name: Campaigns description: Create, schedule, send, and manage email campaigns - name: Project Editing description: Edit project assets, logos, images, and knowledge base entries paths: /v1/segments: post: tags: - Segments summary: Create Segment description: >- Create a new segment with optional filters. Requires API key with audience:write. operationId: CreateSegment requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAudienceRequest' responses: '200': description: Segment created content: application/json: schema: $ref: '#/components/schemas/ApiResponseAudience' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' x-codeSamples: - lang: javascript label: Node.js SDK source: |- import Migma from 'migma'; const migma = new Migma('YOUR_API_KEY'); const { data, error } = await migma.segments.create({ name: 'Campaign openers', description: 'Users who opened a specific campaign in the last 14 days', filters: { activity: [{ action: 'opened', channel: 'email', mode: 'within', unit: 'days', amount: 14, campaignId: 'CAMPAIGN_ID' }] }, projectId: 'PROJECT_ID' }); components: schemas: CreateAudienceRequest: type: object properties: name: type: string maxLength: 200 description: type: string maxLength: 500 filters: $ref: '#/components/schemas/AudienceFilters' projectId: type: string required: - name - projectId ApiResponseAudience: allOf: - $ref: '#/components/schemas/ApiResponse' - type: object properties: data: $ref: '#/components/schemas/Audience' AudienceFilters: type: object properties: tags: type: array items: type: string excludeTags: type: array items: type: string status: type: string enum: - subscribed - unsubscribed - non-subscribed - bounced validationStatus: type: string enum: - valid - invalid - risky - unknown customFields: type: object additionalProperties: type: array items: type: string fields: type: array maxItems: 10 items: type: object properties: key: type: string minLength: 1 maxLength: 100 mode: type: string enum: - is - is_not - starts_with - ends_with - contains - not_contains - date_after - date_before - date_on - date_between - number_gt - number_gte - number_lt - number_lte - number_between default: is values: type: array minItems: 1 maxItems: 50 items: type: string minLength: 1 maxLength: 200 required: - key - values activity: type: array items: type: object properties: action: type: string enum: - sent - opened - clicked channel: type: string enum: - email description: Email is the only supported activity channel today. mode: type: string enum: - within - before - never - between description: between is reserved and currently rejected. unit: type: string enum: - hours - days amount: type: integer minimum: 1 maximum: 8760 description: 'Required for within/before. days: 1-365, hours: 1-8760.' from: type: string format: date-time to: type: string format: date-time campaignId: type: string required: - action - mode ApiResponse: type: object properties: success: type: boolean data: nullable: true error: type: string nullable: true required: - success Audience: type: object properties: id: type: string name: type: string description: type: string filters: $ref: '#/components/schemas/AudienceFilters' count: type: integer description: Number of contacts matching the segment filters createdAt: type: string format: date-time updatedAt: type: string format: date-time ApiError: type: object properties: success: type: boolean default: false error: type: string code: type: string description: >- Machine-readable error code (e.g., IDEMPOTENCY_CONFLICT, DOMAIN_CLAIMABLE). data: type: object description: >- Additional structured context for the error, such as the affected domain. additionalProperties: true required: - success - error responses: BadRequest: description: Bad request content: application/json: schema: $ref: '#/components/schemas/ApiError' Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ApiError' securitySchemes: apiKeyAuth: type: apiKey in: header name: Authorization description: >- API key authentication. Use 'Authorization: Bearer YOUR_API_KEY' where YOUR_API_KEY is obtained from the Migma dashboard under Settings → Developers → API Keys. ````