openapi: 3.0.3
info:
  title: Lytics REST Accounts Connections 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: Connections
  description: Manage data source and destination connections
paths:
  /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'
components:
  schemas:
    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
    ConnectionResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        message:
          type: string
          example: ok
        data:
          $ref: '#/components/schemas/Connection'
    ConnectionListResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        message:
          type: string
          example: ok
        data:
          type: array
          items:
            $ref: '#/components/schemas/Connection'
    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
    SuccessResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        message:
          type: string
          example: ok
  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