openapi: 3.0.3
info:
  title: Lytics REST Accounts Jobs 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: Jobs
  description: Orchestrate and monitor background data jobs
paths:
  /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'
components:
  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'
  schemas:
    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
    JobResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        message:
          type: string
          example: ok
        data:
          $ref: '#/components/schemas/Job'
    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
    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
    JobListResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        message:
          type: string
          example: ok
        data:
          type: array
          items:
            $ref: '#/components/schemas/Job'
    SuccessResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        message:
          type: string
          example: ok
  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