openapi: 3.0.3
info:
  title: Lytics REST Accounts Segments API
  description: The Lytics REST API provides programmatic access to user profile management, behavioral segment queries, content affinity scores, audience activations, data stream ingestion, Cloud Connect warehouse integrations, and job orchestration for the Lytics customer data platform (CDP).
  version: 2.1.0
  contact:
    name: Lytics Support
    url: https://support.lytics.com/hc/en-us
  license:
    name: Proprietary
    url: https://www.lytics.com/
servers:
- url: https://api.lytics.io
  description: Lytics Production API
security:
- ApiKeyQuery: []
- ApiKeyHeader: []
tags:
- name: Segments
  description: Query and scan behavioral audience segments
paths:
  /api/segment:
    get:
      operationId: listSegments
      summary: List segments
      description: Returns all audience segments defined for the account.
      tags:
      - Segments
      parameters:
      - $ref: '#/components/parameters/ApiKeyParam'
      responses:
        '200':
          description: Successful response with segment list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/segment/{slug_or_id}:
    get:
      operationId: getSegment
      summary: Get segment by slug or ID
      description: Returns details for a specific audience segment.
      tags:
      - Segments
      parameters:
      - name: slug_or_id
        in: path
        required: true
        description: The segment slug or unique identifier
        schema:
          type: string
      - $ref: '#/components/parameters/ApiKeyParam'
      responses:
        '200':
          description: Successful response with segment details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/segment/scan:
    post:
      operationId: scanSegment
      summary: Scan segment members
      description: Scans and returns user profile records that match a given segment filter query. Supports cursor-based pagination via the `_next` token.
      tags:
      - Segments
      parameters:
      - $ref: '#/components/parameters/ApiKeyParam'
      - name: limit
        in: query
        description: Maximum number of records to return per page (default 100)
        schema:
          type: integer
          default: 100
          minimum: 1
          maximum: 5000
      - name: next
        in: query
        description: Pagination cursor token from a previous scan response
        schema:
          type: string
      - name: generation
        in: query
        description: Segment generation/version to scan
        schema:
          type: integer
      requestBody:
        required: true
        description: Segment filter query in Lytics Query Language (LQL)
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SegmentScanRequest'
            example:
              filter: in_segment("all_users")
      responses:
        '200':
          description: Successful response with matching user profiles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentScanResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    Segment:
      type: object
      description: A Lytics audience segment
      properties:
        id:
          type: string
          description: Unique segment identifier
        slug_name:
          type: string
          description: URL-safe segment slug
          example: high_value_users
        name:
          type: string
          description: Human-readable segment name
          example: High Value Users
        kind:
          type: string
          description: Segment type (audience, content, etc.)
          enum:
          - audience
          - content
          - behavioral
        filter_ql:
          type: string
          description: LQL filter expression defining segment membership
          example: in_segment("all_users") AND behaviors.score > 50
        size:
          type: integer
          description: Number of users currently in the segment
        created:
          type: string
          format: date-time
        modified:
          type: string
          format: date-time
    SegmentListResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        message:
          type: string
          example: ok
        data:
          type: array
          items:
            $ref: '#/components/schemas/Segment'
    UserProfile:
      type: object
      description: A unified Lytics user profile
      properties:
        _uid:
          type: string
          description: Lytics unique user identifier
        email:
          type: string
          format: email
          description: User email address
        first_name:
          type: string
        last_name:
          type: string
        segments:
          type: array
          description: List of segment slugs the user belongs to
          items:
            type: string
        scores:
          type: object
          description: Behavioral and content affinity scores
          additionalProperties:
            type: number
        created:
          type: string
          format: date-time
        last_active_ts:
          type: string
          format: date-time
      additionalProperties: true
    SegmentScanRequest:
      type: object
      description: Segment scan filter request
      properties:
        filter:
          type: string
          description: LQL segment filter expression
          example: in_segment("all_users")
        id:
          type: string
          description: Segment ID to scan
      oneOf:
      - required:
        - filter
      - required:
        - id
    ErrorResponse:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code
          example: 400
        message:
          type: string
          description: Human-readable error message
          example: invalid API key
    SegmentResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        message:
          type: string
          example: ok
        data:
          $ref: '#/components/schemas/Segment'
    SegmentScanResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        message:
          type: string
          example: ok
        total:
          type: integer
          description: Total number of matching records
        _next:
          type: string
          description: Cursor token for the next page of results (empty string if no more pages)
        data:
          type: array
          items:
            $ref: '#/components/schemas/UserProfile'
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized — missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request — invalid parameters or request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  parameters:
    ApiKeyParam:
      name: key
      in: query
      required: false
      description: Lytics API key (required unless passed via Authorization header)
      schema:
        type: string
  securitySchemes:
    ApiKeyQuery:
      type: apiKey
      in: query
      name: key
      description: Lytics API key passed as a query parameter. Obtain your API key from the Lytics account settings.
    ApiKeyHeader:
      type: apiKey
      in: header
      name: Authorization
      description: Lytics API key passed as an Authorization header value.
externalDocs:
  description: Lytics API Reference Documentation
  url: https://docs.lytics.com/reference