openapi: 3.0.3
info:
  title: Lytics REST 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/
externalDocs:
  description: Lytics API Reference Documentation
  url: https://docs.lytics.com/reference
servers:
  - url: https://api.lytics.io
    description: Lytics Production API

security:
  - ApiKeyQuery: []
  - ApiKeyHeader: []

tags:
  - name: Accounts
    description: Manage Lytics accounts and retrieve account information
  - name: Segments
    description: Query and scan behavioral audience segments
  - name: Entity
    description: Look up unified user profiles by field value
  - name: Datamodels
    description: Manage data models and stream schemas
  - name: Connections
    description: Manage data source and destination connections
  - name: Jobs
    description: Orchestrate and monitor background data jobs
  - name: Collections
    description: Manage content collections for affinity scoring
  - name: Work
    description: Trigger background workflow operations

paths:
  /api/account:
    get:
      operationId: listAccounts
      summary: List accounts
      description: Returns a list of Lytics accounts accessible with the provided API key.
      tags:
        - Accounts
      parameters:
        - $ref: '#/components/parameters/ApiKeyParam'
      responses:
        '200':
          description: Successful response with account list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /api/account/{aid}:
    get:
      operationId: getAccount
      summary: Get account by AID
      description: Returns the account details for the specified account ID.
      tags:
        - Accounts
      parameters:
        - $ref: '#/components/parameters/AidPath'
        - $ref: '#/components/parameters/ApiKeyParam'
      responses:
        '200':
          description: Successful response with account details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /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'

  /api/entity/{table}/{field}/{value}:
    get:
      operationId: getEntity
      summary: Look up entity (user profile)
      description: >-
        Returns the unified user profile for a specific entity identified by
        a field/value lookup against the specified data table.
      tags:
        - Entity
      parameters:
        - name: table
          in: path
          required: true
          description: The data table to query (e.g., `user`)
          schema:
            type: string
            example: user
        - name: field
          in: path
          required: true
          description: The field name to look up (e.g., `email`, `_uid`)
          schema:
            type: string
            example: email
        - name: value
          in: path
          required: true
          description: The field value to match
          schema:
            type: string
            example: user@example.com
        - $ref: '#/components/parameters/ApiKeyParam'
        - name: fields
          in: query
          description: Comma-separated list of profile fields to include in the response
          schema:
            type: string
      responses:
        '200':
          description: Successful response with the user profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /api/datamodel:
    get:
      operationId: listDatamodels
      summary: List data models
      description: Returns all data models (stream schemas) configured for the account.
      tags:
        - Datamodels
      parameters:
        - $ref: '#/components/parameters/ApiKeyParam'
      responses:
        '200':
          description: Successful response with data model list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatamodelListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /api/datamodel/{name}:
    get:
      operationId: getDatamodel
      summary: Get data model by name
      description: Returns a specific data model (stream schema) by name.
      tags:
        - Datamodels
      parameters:
        - name: name
          in: path
          required: true
          description: The data model name
          schema:
            type: string
        - $ref: '#/components/parameters/ApiKeyParam'
      responses:
        '200':
          description: Successful response with data model details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatamodelResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /api/connection:
    get:
      operationId: listConnections
      summary: List connections
      description: Returns all data source and destination connections for the account.
      tags:
        - Connections
      parameters:
        - $ref: '#/components/parameters/ApiKeyParam'
      responses:
        '200':
          description: Successful response with connection list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      operationId: createConnection
      summary: Create a connection
      description: Creates a new data source or destination connection.
      tags:
        - Connections
      parameters:
        - $ref: '#/components/parameters/ApiKeyParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectionRequest'
      responses:
        '200':
          description: Connection created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /api/connection/{id}:
    get:
      operationId: getConnection
      summary: Get connection by ID
      description: Returns details for a specific connection.
      tags:
        - Connections
      parameters:
        - name: id
          in: path
          required: true
          description: The connection ID
          schema:
            type: string
        - $ref: '#/components/parameters/ApiKeyParam'
      responses:
        '200':
          description: Successful response with connection details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      operationId: updateConnection
      summary: Update a connection
      description: Updates an existing connection configuration.
      tags:
        - Connections
      parameters:
        - name: id
          in: path
          required: true
          description: The connection ID
          schema:
            type: string
        - $ref: '#/components/parameters/ApiKeyParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectionRequest'
      responses:
        '200':
          description: Connection updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      operationId: deleteConnection
      summary: Delete a connection
      description: Deletes an existing connection.
      tags:
        - Connections
      parameters:
        - name: id
          in: path
          required: true
          description: The connection ID
          schema:
            type: string
        - $ref: '#/components/parameters/ApiKeyParam'
      responses:
        '200':
          description: Connection deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /api/job:
    get:
      operationId: listJobs
      summary: List jobs
      description: Returns all data import/export jobs for the account.
      tags:
        - Jobs
      parameters:
        - $ref: '#/components/parameters/ApiKeyParam'
      responses:
        '200':
          description: Successful response with job list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      operationId: createJob
      summary: Create a job
      description: Creates and starts a new data import or export job.
      tags:
        - Jobs
      parameters:
        - $ref: '#/components/parameters/ApiKeyParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobRequest'
      responses:
        '200':
          description: Job created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /api/job/{id}:
    get:
      operationId: getJob
      summary: Get job by ID
      description: Returns the current status and details of a specific job.
      tags:
        - Jobs
      parameters:
        - name: id
          in: path
          required: true
          description: The job ID
          schema:
            type: string
        - $ref: '#/components/parameters/ApiKeyParam'
      responses:
        '200':
          description: Successful response with job details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      operationId: cancelJob
      summary: Cancel a job
      description: Cancels a running job.
      tags:
        - Jobs
      parameters:
        - name: id
          in: path
          required: true
          description: The job ID
          schema:
            type: string
        - $ref: '#/components/parameters/ApiKeyParam'
      responses:
        '200':
          description: Job cancelled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /api/work:
    post:
      operationId: createWork
      summary: Trigger a background workflow
      description: >-
        Triggers a background workflow operation identified by a workflow ID.
        Common workflows include segment evaluation, content rescoring, content
        enrichment, and GDPR deletion.
      tags:
        - Work
      parameters:
        - $ref: '#/components/parameters/ApiKeyParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkRequest'
            examples:
              segment_scan:
                summary: Evaluate a segment
                value:
                  workflow_id: e40a0ad5d0a845ca8549a7d23ede9eed
                  config:
                    filter_ql: "in_segment(\"all_users\")"
                    skip_emitting_sentinel: true
                    segment_scanner_version: v2
              content_enrich:
                summary: Enrich content collection
                value:
                  workflow_id: 23be8d80749b106513e83547e2c8bff1
                  verbose_logging: true
                  config:
                    collection_id: my_collection
                    skip_sitemaps: true
                    enrich_epoch:
                      meta: "2026-01-01T00:00:00Z"
                      google_nlp: "2026-01-01T00:00:00Z"
      responses:
        '200':
          description: Work job created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /api/collect:
    post:
      operationId: collectData
      summary: Collect (ingest) event data
      description: >-
        Ingests a stream of user behavior events or entity attributes into a
        Lytics data stream. Used for real-time data collection.
      tags:
        - Datamodels
      parameters:
        - $ref: '#/components/parameters/ApiKeyParam'
        - name: stream
          in: query
          description: The target data stream name
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CollectRequest'
      responses:
        '200':
          description: Data ingested successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

components:
  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.

  parameters:
    ApiKeyParam:
      name: key
      in: query
      required: false
      description: Lytics API key (required unless passed via Authorization header)
      schema:
        type: string
    AidPath:
      name: aid
      in: path
      required: true
      description: The Lytics account ID (AID)
      schema:
        type: string

  responses:
    BadRequest:
      description: Bad request — invalid parameters or request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized — missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

  schemas:
    Account:
      type: object
      description: A Lytics account record
      properties:
        aid:
          type: string
          description: Account ID
          example: "12345"
        name:
          type: string
          description: Account display name
          example: "ACME Corp"
        apikey:
          type: string
          description: Account-level API key
        created:
          type: string
          format: date-time
          description: Timestamp when the account was created
        modified:
          type: string
          format: date-time
          description: Timestamp when the account was last modified

    AccountListResponse:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code
          example: 200
        message:
          type: string
          example: "ok"
        data:
          type: array
          items:
            $ref: '#/components/schemas/Account'

    AccountResponse:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code
          example: 200
        message:
          type: string
          example: "ok"
        data:
          $ref: '#/components/schemas/Account'

    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'

    SegmentResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        message:
          type: string
          example: "ok"
        data:
          $ref: '#/components/schemas/Segment'

    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]

    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'

    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

    EntityResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        message:
          type: string
          example: "ok"
        data:
          $ref: '#/components/schemas/UserProfile'

    Datamodel:
      type: object
      description: A Lytics data model (stream schema)
      properties:
        id:
          type: string
          description: Unique data model identifier
        name:
          type: string
          description: Stream/data model name
        fields:
          type: array
          description: Field definitions for the data model
          items:
            $ref: '#/components/schemas/DatamodelField'
        created:
          type: string
          format: date-time
        modified:
          type: string
          format: date-time

    DatamodelField:
      type: object
      description: A field definition within a data model
      properties:
        name:
          type: string
          description: Field name
        as:
          type: string
          description: Alias for the field in the unified profile
        type:
          type: string
          description: Field data type
          enum: [string, int, float, bool, date, array, object]
        is_by:
          type: boolean
          description: Whether this field is used as a profile identity key

    DatamodelListResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        message:
          type: string
          example: "ok"
        data:
          type: array
          items:
            $ref: '#/components/schemas/Datamodel'

    DatamodelResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        message:
          type: string
          example: "ok"
        data:
          $ref: '#/components/schemas/Datamodel'

    Connection:
      type: object
      description: A Lytics data source or destination connection
      properties:
        id:
          type: string
          description: Unique connection identifier
        name:
          type: string
          description: Connection display name
        type:
          type: string
          description: Connection type (e.g., bigquery, salesforce, google_ads)
        auth_id:
          type: string
          description: Associated authentication/credential ID
        config:
          type: object
          description: Connection-specific configuration parameters
          additionalProperties: true
        created:
          type: string
          format: date-time
        modified:
          type: string
          format: date-time

    ConnectionRequest:
      type: object
      required:
        - name
        - type
      properties:
        name:
          type: string
          description: Connection display name
        type:
          type: string
          description: Connection type
        auth_id:
          type: string
          description: Authentication/credential ID to associate
        config:
          type: object
          description: Connection-specific configuration
          additionalProperties: true

    ConnectionListResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        message:
          type: string
          example: "ok"
        data:
          type: array
          items:
            $ref: '#/components/schemas/Connection'

    ConnectionResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        message:
          type: string
          example: "ok"
        data:
          $ref: '#/components/schemas/Connection'

    Job:
      type: object
      description: A Lytics data import or export job
      properties:
        id:
          type: string
          description: Unique job identifier
        type:
          type: string
          description: Job type (import, export, etc.)
        status:
          type: string
          description: Current job status
          enum: [pending, running, complete, failed, cancelled]
        connection_id:
          type: string
          description: Associated connection ID
        config:
          type: object
          description: Job-specific configuration
          additionalProperties: true
        error:
          type: string
          description: Error message if the job failed
        created:
          type: string
          format: date-time
        modified:
          type: string
          format: date-time

    JobRequest:
      type: object
      required:
        - type
        - connection_id
      properties:
        type:
          type: string
          description: Job type
        connection_id:
          type: string
          description: Connection to use for this job
        config:
          type: object
          description: Job configuration parameters
          additionalProperties: true

    JobListResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        message:
          type: string
          example: "ok"
        data:
          type: array
          items:
            $ref: '#/components/schemas/Job'

    JobResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        message:
          type: string
          example: "ok"
        data:
          $ref: '#/components/schemas/Job'

    WorkRequest:
      type: object
      required:
        - workflow_id
      description: Request to trigger a background workflow
      properties:
        workflow_id:
          type: string
          description: The ID of the workflow to execute
          example: e40a0ad5d0a845ca8549a7d23ede9eed
        verbose_logging:
          type: boolean
          description: Enable verbose logging for this workflow run
          default: false
        config:
          type: object
          description: Workflow-specific configuration parameters
          additionalProperties: true

    WorkResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        message:
          type: string
          example: "ok"
        data:
          type: object
          properties:
            id:
              type: string
              description: The work job ID

    CollectRequest:
      type: object
      description: >-
        An event or entity data payload to ingest into a Lytics data stream.
        The schema is flexible and maps to the target stream's data model.
      additionalProperties: true
      example:
        email: user@example.com
        name: Jane Doe
        _uid: abc123
        event: page_view
        url: https://example.com/products

    SuccessResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        message:
          type: string
          example: "ok"

    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"