openapi: 3.1.0
info:
  title: Contentsquare Data Export API
  description: |
    The Contentsquare Data Export API lets you programmatically create export
    jobs and retrieve exported files for pageview-level or session-level raw
    data. Authentication uses server-to-server OAuth 2.0 (client_credentials)
    and the access token (Bearer) returned at authentication time must be sent
    on every subsequent request.
  version: "1.0.0"
  contact:
    name: Contentsquare Developer Documentation
    url: https://docs.contentsquare.com/en/api/export/
servers:
  - url: https://api.contentsquare.com
    description: Contentsquare API (regional base URL returned at authentication)
security:
  - bearerAuth: []
tags:
  - name: Authentication
  - name: Exports
  - name: Runs
  - name: Fields
paths:
  /v1/oauth/token:
    post:
      tags: [Authentication]
      summary: Obtain an OAuth 2.0 access token
      description: |
        Exchange client credentials for a short-lived (1 hour) bearer token used
        on all subsequent API calls. The response also includes the regional
        base URL to use for subsequent requests.
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [client_id, client_secret, grant_type]
              properties:
                client_id:
                  type: string
                client_secret:
                  type: string
                grant_type:
                  type: string
                  enum: [client_credentials]
                scope:
                  type: string
                  example: data-export
                project_id:
                  type: string
                  description: Required only for account-level credentials
      responses:
        "200":
          description: Token issued
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token: { type: string }
                  token_type: { type: string, example: Bearer }
                  expires_in: { type: integer, example: 3600 }
                  scope: { type: string }
                  project_id: { type: string }
                  api_base_url: { type: string, format: uri }
  /v1/exports:
    get:
      tags: [Exports]
      summary: List export jobs
      parameters:
        - { in: query, name: format, schema: { type: string, enum: [JSONL, CSV] } }
        - { in: query, name: frequency, schema: { type: string } }
        - { in: query, name: scope, schema: { type: string } }
        - { in: query, name: state, schema: { type: string } }
        - { in: query, name: limit, schema: { type: integer, default: 20 } }
        - { in: query, name: page, schema: { type: integer, default: 1 } }
        - { in: query, name: order, schema: { type: string } }
      responses:
        "200":
          description: A page of export jobs
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ExportJobList" }
    post:
      tags: [Exports]
      summary: Create an export job
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ExportJobRequest" }
      responses:
        "201":
          description: Job created
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ExportJob" }
  /v1/exports/successful-runs:
    get:
      tags: [Runs]
      summary: List successful job runs across all jobs
      parameters:
        - { in: query, name: page, schema: { type: integer } }
        - { in: query, name: limit, schema: { type: integer } }
        - { in: query, name: order, schema: { type: string } }
      responses:
        "200": { description: OK }
  /v1/exports/{jobId}:
    get:
      tags: [Exports]
      summary: Retrieve a single export job
      parameters:
        - { in: path, name: jobId, required: true, schema: { type: string } }
      responses:
        "200":
          description: Export job
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ExportJob" }
  /v1/exports/{jobId}/runs:
    get:
      tags: [Runs]
      summary: List runs for a job
      parameters:
        - { in: path, name: jobId, required: true, schema: { type: string } }
        - { in: query, name: limit, schema: { type: integer } }
        - { in: query, name: page, schema: { type: integer } }
        - { in: query, name: order, schema: { type: string } }
        - { in: query, name: state, schema: { type: string } }
      responses:
        "200": { description: OK }
  /v1/exports/{jobId}/runs/{runId}:
    get:
      tags: [Runs]
      summary: Retrieve a specific job run (with file download URLs)
      parameters:
        - { in: path, name: jobId, required: true, schema: { type: string } }
        - { in: path, name: runId, required: true, schema: { type: string } }
      responses:
        "200":
          description: Run details and signed download URLs
          content:
            application/json:
              schema:
                type: object
                properties:
                  id: { type: string }
                  state: { type: string }
                  files:
                    type: array
                    items:
                      type: object
                      properties:
                        url: { type: string, format: uri }
                        expires_at: { type: string, format: date-time }
  /v1/exportable-fields:
    get:
      tags: [Fields]
      summary: List exportable fields for a scope
      parameters:
        - in: query
          name: scope
          required: true
          schema: { type: string }
      responses:
        "200": { description: OK }
  /v1/custom-vars:
    get:
      tags: [Fields]
      summary: List custom variables defined for the project
      responses:
        "200": { description: OK }
  /v1/dynamic-var-keys:
    get:
      tags: [Fields]
      summary: List dynamic variable keys captured in a window
      parameters:
        - { in: query, name: from, schema: { type: string, format: date-time } }
        - { in: query, name: to, schema: { type: string, format: date-time } }
      responses:
        "200": { description: OK }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    ExportJob:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        format: { type: string, enum: [JSONL, CSV] }
        scope: { type: string }
        frequency: { type: string }
        state: { type: string }
        created_at: { type: string, format: date-time }
    ExportJobRequest:
      type: object
      required: [name, format, scope]
      properties:
        name: { type: string }
        format: { type: string, enum: [JSONL, CSV] }
        scope: { type: string }
        frequency: { type: string }
        fields:
          type: array
          items: { type: string }
        deviceLabel: { type: string }
        segmentId: { type: string }
    ExportJobList:
      type: object
      properties:
        data:
          type: array
          items: { $ref: "#/components/schemas/ExportJob" }
        page: { type: integer }
        limit: { type: integer }
        total: { type: integer }