Cogram Data Exports API

openapi: 3.2.0
info:
  title: Cogram Data Exports API
  description: 'API for integrating with Cogram. Every key is scoped to one organization.


    - **Auth**: `Authorization: Bearer `. Admins mint keys in Organization

    Settings → Integrations → API Keys.

    - **Pagination**: `page` (1-indexed) + `page_size` (default 50, max 100); returns

    `{"data": [...], "total": N, "page": N, "page_size": N}`. `total` = all matches.

    - **Errors**: `{"error": "", "message": ""}`. Branch on `error`; `message`

    wording may change.

    - **Rate limit**: per key, 1000 req/min by default. `429` carries `Retry-After`,

    `X-RateLimit-Limit`, `X-RateLimit-Remaining`.

    - **Attribution**: optional `X-Forwarded-User` header (≤200 chars) names the end user

    behind the call in Cogram''s audit trail.


    See API documentation for guides and examples.'
  version: v1
servers:
- url: /v1
tags:
- name: data-exports
  description: 'Zip exports of org data: request, poll, download.'
paths:
  /data-exports:
    post:
      tags:
      - data-exports
      summary: Create data_export
      description: 'Create a new data_export in PENDING and enqueue the build worker.


        Pass ``project_ids`` to scope the export to those projects (list

        candidates via ``GET /v1/projects``); omit it for an org-wide export,

        which is capped at a 6-month range. Any project the API key''s org

        doesn''t own returns 404 — same as an unknown one, and the whole

        request is rejected rather than exporting the subset that resolved.


        The build is asynchronous — poll ``GET /v1/data-exports/{id}`` for status

        and (once ``status == "completed"``) freshly-signed download URLs

        for each part.'
      operationId: external_create_data_export_route_data_exports_post
      security:
      - HTTPBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataExportCreateRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataExportResponse'
        '400':
          description: Bad request
          content:
            application/json:
              example:
                error: bad_request
                message: Invalid request
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                error: api_key_invalid
                message: Invalid API key
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '404':
          description: Not found
          content:
            application/json:
              example:
                error: not_found
                message: Resource not found
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '409':
          description: Conflict
          content:
            application/json:
              example:
                error: conflict
                message: Resource already exists
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '422':
          description: Validation error
          content:
            application/json:
              example:
                error: validation_error
                message: 'body -> name: Field required'
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              example:
                error: rate_limit_exceeded
                message: Rate limit exceeded. Please try again later.
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '500':
          description: Internal server error
          content:
            application/json:
              example:
                error: internal_error
                message: An internal error occurred
              schema:
                $ref: '#/components/schemas/ErrorV1'
    get:
      tags:
      - data-exports
      summary: List data_exports
      description: 'List every data_export for the org, newest first.


        Paginated per the external-API contract ``{data, total, page,

        page_size}``. Defaults: page=1, page_size=50, max page_size=100.


        Includes terminal rows (``completed``, ``failed``, ``cancelled``,

        ``expired``) — they''re the audit trail. ``parts`` (with signed URLs)

        is populated only on rows in ``completed`` status; signed URLs

        expire one hour after generation and are regenerated on every read.'
      operationId: external_list_data_exports_route_data_exports_get
      security:
      - HTTPBearer: []
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number (1-indexed).
          default: 1
          title: Page
        description: Page number (1-indexed).
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 50
          title: Page Size
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataExportListV1'
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                error: api_key_invalid
                message: Invalid API key
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '422':
          description: Validation error
          content:
            application/json:
              example:
                error: validation_error
                message: 'body -> name: Field required'
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              example:
                error: rate_limit_exceeded
                message: Rate limit exceeded. Please try again later.
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '500':
          description: Internal server error
          content:
            application/json:
              example:
                error: internal_error
                message: An internal error occurred
              schema:
                $ref: '#/components/schemas/ErrorV1'
  /data-exports/{data_export_id}:
    get:
      tags:
      - data-exports
      summary: Get data_export
      description: 'Get one data_export''s status and (when ``status == "completed"``)

        freshly-signed download URLs for each part.


        URLs are regenerated on every read so clients never accumulate stale

        ones. Cross-org data_export ids return 404 — the API key only sees its

        own org''s data_exports.'
      operationId: external_get_data_export_route_data_exports__data_export_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: data_export_id
        in: path
        required: true
        schema:
          type: string
          title: Data Export Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataExportResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                error: api_key_invalid
                message: Invalid API key
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '404':
          description: Not found
          content:
            application/json:
              example:
                error: not_found
                message: Resource not found
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '422':
          description: Validation error
          content:
            application/json:
              example:
                error: validation_error
                message: 'body -> name: Field required'
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              example:
                error: rate_limit_exceeded
                message: Rate limit exceeded. Please try again later.
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '500':
          description: Internal server error
          content:
            application/json:
              example:
                error: internal_error
                message: An internal error occurred
              schema:
                $ref: '#/components/schemas/ErrorV1'
  /data-exports/{data_export_id}/cancel:
    post:
      tags:
      - data-exports
      summary: Cancel data_export
      description: 'Cancel a ``pending`` or ``running`` data_export.


        ``pending`` short-circuits straight to ``cancelled`` — no in-flight

        build work to interrupt. ``running`` transitions to ``cancelling``;

        the worker (E-1454) picks up the signal between zip parts and the

        next status read will reflect the terminal state. Terminal statuses

        return 409 — there''s no in-flight work to stop.'
      operationId: external_cancel_data_export_route_data_exports__data_export_id__cancel_post
      security:
      - HTTPBearer: []
      parameters:
      - name: data_export_id
        in: path
        required: true
        schema:
          type: string
          title: Data Export Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataExportResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                error: api_key_invalid
                message: Invalid API key
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '404':
          description: Not found
          content:
            application/json:
              example:
                error: not_found
                message: Resource not found
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '409':
          description: Conflict
          content:
            application/json:
              example:
                error: conflict
                message: Resource already exists
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '422':
          description: Validation error
          content:
            application/json:
              example:
                error: validation_error
                message: 'body -> name: Field required'
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              example:
                error: rate_limit_exceeded
                message: Rate limit exceeded. Please try again later.
              schema:
                $ref: '#/components/schemas/ErrorV1'
        '500':
          description: Internal server error
          content:
            application/json:
              example:
                error: internal_error
                message: An internal error occurred
              schema:
                $ref: '#/components/schemas/ErrorV1'
components:
  schemas:
    DataExportPartResponse:
      properties:
        id:
          type: string
          title: Id
        part_index:
          type: integer
          title: Part Index
          description: Zero-indexed.
        size_bytes:
          type: integer
          title: Size Bytes
          description: Compressed size.
        signed_url:
          type: string
          title: Signed Url
          description: Pre-signed, valid 1 hour. Re-fetch on each read, never cache.
      type: object
      required:
      - id
      - part_index
      - size_bytes
      - signed_url
      title: DataExportPartResponse
      description: 'One zip part within a completed data_export, with a freshly-signed download URL.


        ``signed_url`` is regenerated by the service on every status read (signing

        is local math, no S3 round-trip) — clients should never cache it past the

        1-hour validity window stamped on the URL itself.'
    DataExportResponse:
      properties:
        id:
          type: string
          title: Id
        organization_id:
          type: string
          title: Organization Id
        source:
          type: string
          enum:
          - ui
          - api
          title: Source
        requester_user_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Requester User Id
          description: '`ui` source only.'
        requester_api_key_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Requester Api Key Id
          description: '`api` source only.'
        requester_api_key_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Requester Api Key Name
          description: '`api` source only. Prefer this over parsing `requester_display`.'
        requester_forwarded_user:
          anyOf:
          - type: string
          - type: 'null'
          title: Requester Forwarded User
          description: '`X-Forwarded-User` header value at create time.'
        requester_display:
          type: string
          title: Requester Display
          description: 'Human-readable attribution: the user''s name (their email if the name is empty), `API key ''<name>''`, or `<forwarded_user> (via API key ''<name>'')`. Degrades to `<forwarded_user> (via deleted API key)` or `unknown` when the linked user or key row was deleted after the export was created.'
        project_ids:
          items:
            type: string
          type: array
          title: Project Ids
          description: Scope as requested — empty for org-wide exports. Retains ids of projects deleted after the export was created, so `projects` may be shorter.
        projects:
          items:
            $ref: '#/components/schemas/DataExportProjectRef'
          type: array
          title: Projects
          description: Scope projects that still exist, in `project_ids` order.
        project_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Project Id
          description: Set only for single-project exports; null otherwise.
          deprecated: true
        project_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Project Name
          description: Set only when `project_id` is set.
          deprecated: true
        project_customer_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Project Customer Id
          description: Customer's own project label. Not unique — use `project_id` for identity.
          deprecated: true
        time_filter:
          $ref: '#/components/schemas/TimeFilter'
          description: Echo of the request.
        document_formats:
          items:
            type: string
          type: array
          title: Document Formats
          description: Echo of the request. Typed loosely so a row written by a newer deployment, carrying a format this one does not know, still serializes instead of failing the whole listing.
        status:
          type: string
          enum:
          - pending
          - running
          - cancelling
          - cancelled
          - completed
          - failed
          - expired
          title: Status
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Set when `status` is `failed`.
        requested_at:
          type: string
          format: date-time
          title: Requested At
        started_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Started At
        completed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Completed At
          description: Also set on failure and cancellation.
        expires_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Expires At
          description: Parts are deleted at this time, 7 days after completion.
        parts:
          items:
            $ref: '#/components/schemas/DataExportPartResponse'
          type: array
          title: Parts
          description: Zip parts with signed URLs. Empty until `status` is `completed`.
      type: object
      required:
      - id
      - organization_id
      - source
      - requester_user_id
      - requester_api_key_id
      - requester_api_key_name
      - requester_forwarded_user
      - requester_display
      - project_ids
      - project_id
      - time_filter
      - document_formats
      - status
      - error
      - requested_at
      - started_at
      - completed_at
      - expires_at
      title: DataExportResponse
      description: 'Full read shape returned by ``GET /data_exports`` and ``GET /data_exports/{id}``.


        ``parts`` is empty until the data_export reaches ``COMPLETED``. Even after

        ``EXPIRED``, the row remains as an audit record — clients distinguish

        "downloadable" from "audit-only" via the ``status`` field.'
    DataExportProjectRef:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        customer_project_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Customer Project Id
          description: Customer's own project label. Not unique — use `id` for identity.
      type: object
      required:
      - id
      - name
      - customer_project_id
      title: DataExportProjectRef
      description: 'One project in a data_export''s scope, with the labels a human needs to

        recognize it. Only projects that still exist are represented — see

        ``DataExportResponse.project_ids`` for the scope as requested.'
    TimeRangeFilter:
      properties:
        mode:
          type: string
          const: range
          title: Mode
          default: range
        start:
          type: string
          format: date-time
          title: Start
          description: Inclusive. Must be timezone-aware.
        end:
          type: string
          format: date-time
          title: End
          description: Inclusive. Must be timezone-aware.
      type: object
      required:
      - start
      - end
      title: TimeRangeFilter
      description: Closed time range. Both bounds timezone-aware; ``end`` must be >= ``start``.
    TimeFilter:
      oneOf:
      - $ref: '#/components/schemas/TimeRangeFilter'
      - $ref: '#/components/schemas/AllTimeFilter'
      title: TimeFilter
      description: 'Discriminated-union wrapper so the JSONB column can use ``PydanticJsonbType``.


        Stored shape mirrors ``root`` directly (``RootModel`` serializes without

        a wrapping field), e.g. ``{"mode": "range", "start": ..., "end": ...}``.'
      discriminator:
        propertyName: mode
        mapping:
          all_time: '#/components/schemas/AllTimeFilter'
          range: '#/components/schemas/TimeRangeFilter'
    ErrorCode:
      type: string
      enum:
      - api_key_missing
      - api_key_invalid_format
      - api_key_invalid
      - api_key_expired
      - bad_request
      - forbidden
      - not_found
      - method_not_allowed
      - conflict
      - validation_error
      - rate_limit_exceeded
      - internal_error
      - range_too_large
      - data_export_in_progress
      title: ErrorCode
      description: Error codes for external API v1.
    AllTimeFilter:
      properties:
        mode:
          type: string
          const: all_time
          title: Mode
          default: all_time
      type: object
      title: AllTimeFilter
      description: 'All available data, no time bound. Only valid for project-scoped

        data_exports (one or more ``project_ids``).'
    ErrorV1:
      properties:
        error:
          $ref: '#/components/schemas/ErrorCode'
          description: Stable machine-readable code. Branch on this.
        message:
          type: string
          title: Message
          description: Human-readable detail. Wording may change.
      type: object
      required:
      - error
      - message
      title: ErrorV1
      description: 'JSON body format for all API v1 error responses.


        This model controls the actual serialization of error responses:

        {"error": "not_found", "message": "Project ''xyz'' not found"}'
    DataExportCreateRequest:
      properties:
        project_ids:
          anyOf:
          - items:
              type: string
            type: array
            minItems: 1
          - type: 'null'
          title: Project Ids
          description: Project KSUIDs to scope the data_export to. Omit for an org-wide data_export, which carries the 6-month cap. Duplicates are collapsed.
        project_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Project Id
          description: Deprecated single-project form of `project_ids`.
          deprecated: true
        time_filter:
          $ref: '#/components/schemas/TimeFilter'
          description: '`{mode: range, start, end}` or `{mode: all_time}`. `all_time` is project-scoped only.'
        document_formats:
          items:
            type: string
            const: docx
          type: array
          title: Document Formats
          description: Rendered document formats to emit per field report and observation, alongside the JSON. Empty (the default) ships metadata and raw blobs only. Does not affect `meeting.docx`, which every export includes. Rendering makes a build slower and its zip larger.
      type: object
      required:
      - time_filter
      title: DataExportCreateRequest
      description: 'Body for ``POST /data_exports`` (both UI and external API).


        Cap rule is **not** enforced by Pydantic — call ``validate_cap_rule()``

        explicitly from the service so the structured ``CapRuleViolation`` can

        propagate cleanly to the router (Pydantic would otherwise wrap it in a

        ``ValidationError`` and surface a 422 with the wrong shape).'
    DataExportListV1:
      properties:
        data:
          items:
            $ref: '#/components/schemas/DataExportResponse'
          type: array
          title: Data
          description: Newest first.
        total:
          type: integer
          title: Total
          description: Total matches across all pages, not just this page.
        page:
          type: integer
          title: Page
        page_size:
          type: integer
          title: Page Size
      type: object
      required:
      - data
      - total
      - page
      - page_size
      title: DataExportListV1
      description: 'Paginated data export list response — matches the standard

        ``{data, total, page, page_size}`` envelope used across the

        external API.'
  securitySchemes:
    HTTPBearer:
      type: http
      description: Organization API key. Minted by admins in Organization Settings → Integrations → API Keys; shown once, may carry an expiry.
      scheme: bearer
      bearerFormat: Cogram organization API key