Clarity Exports API

openapi: 3.2.0
info:
  title: Fast Exports API
  version: 0.1.0
tags:
- name: Exports
paths:
  /api/v1/exports:
    post:
      tags:
      - Exports
      summary: Create Export Job
      description: 'Create a new widget export job and schedule it to run.


        The response returns the job id immediately. The client polls

        `GET /api/v1/exports/{job_id}` until status is `succeeded` or `failed`.'
      operationId: create_export_job_api_v1_exports_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateExportRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportJobResponse'
        '401':
          description: Not authenticated
        '404':
          description: Dashboard or widget not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v1/exports/upload:
    post:
      tags:
      - Exports
      summary: Upload Export Artifact
      description: 'Host a client-rendered export artifact and return a presigned download URL.


        Complements the server-side render pipeline: when an artifact is produced

        elsewhere (e.g. the managed agent''s dashboard-export skill builds a branded

        PDF), it is POSTed here so the bytes land in the export bucket and the caller

        gets back a time-boxed `download_url` to embed in an outbound message. The

        link is a presigned GET (not single-use): an emailed link is clicked later

        and is often pre-fetched by mail scanners, which would burn a single-use

        token.


        Args:

        request: Incoming request (its headers carry the project context).

        token: Bearer token (project scope); optional only so DEV_BYPASS_AUTH works.

        db: Async database session.

        file: The artifact to store.


        Returns:

        Metadata plus a presigned `download_url` valid for

        EXPORT_UPLOAD_URL_EXPIRY_SECONDS.


        Raises:

        HTTPException: 400 empty file, 401 missing auth, 413 too large,

        500 storage unconfigured, 502 upload failed.'
      operationId: upload_export_artifact_api_v1_exports_upload_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_upload_export_artifact_api_v1_exports_upload_post'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactUploadResponse'
        '400':
          description: Empty file
        '401':
          description: Not authenticated
        '413':
          description: File exceeds the size limit
        '500':
          description: Artifact storage is not configured
        '502':
          description: Upload to storage failed
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v1/exports/{job_id}:
    get:
      tags:
      - Exports
      summary: Get Export Job
      description: Fetch job status and (once ready) a single use download URL.
      operationId: get_export_job_api_v1_exports__job_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportJobResponse'
        '401':
          description: Not authenticated
        '403':
          description: Job does not belong to the requesting user
        '404':
          description: Job not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/exports/{job_id}/download:
    get:
      tags:
      - Exports
      summary: Download Export Artifact
      description: 'Download the artifact bytes.


        Authentication: requires both a valid bearer token (matching the job''s

        user and project) AND the download token. The bearer is optional only

        when DEV_BYPASS_AUTH is on.


        Token lifecycle: the token is verified up front in constant time but

        invalidated as a background task that runs AFTER the response body is

        sent. This handles browsers that issue a duplicate request inside the

        same window (probe + actual download); both arrive while the token is

        still live and both succeed. The next sequential request after the

        response completes sees the token cleared and gets 403, preserving

        the single-use semantic across user actions.'
      operationId: download_export_artifact_api_v1_exports__job_id__download_get
      security:
      - HTTPBearer: []
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: token
        in: query
        required: true
        schema:
          type: string
          description: Download token returned in the job's download_url. Invalidated after the response is sent.
          title: Token
        description: Download token returned in the job's download_url. Invalidated after the response is sent.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description: Not authenticated
        '403':
          description: Invalid or already consumed download token
        '404':
          description: Job not found
        '409':
          description: Artifact is not ready yet
        '410':
          description: Artifact is no longer available
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/exports/{job_id}/render:
    get:
      tags:
      - Exports
      summary: Get Export Render Descriptor
      description: 'Return the descriptor the render page needs to draw the widget.


        Authentication: export token minted at job create time. The token is

        high-entropy (24 bytes URL-safe) and authorizes the render pass only

        while the job is still in progress; once the job is terminal the

        descriptor is refused, bounding the replay window to the active render.

        Supply it in the `X-Export-Token` header. The legacy `?token=` query

        parameter is still accepted for backwards compatibility and will be

        removed in a follow up.'
      operationId: get_export_render_descriptor_api_v1_exports__job_id__render_get
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: token
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Legacy query parameter for the export token. Prefer the X-Export-Token header.
          title: Token
        description: Legacy query parameter for the export token. Prefer the X-Export-Token header.
      - name: X-Export-Token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Export-Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportRenderDescriptor'
        '403':
          description: Invalid export token
        '404':
          description: Job not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ExportJobResponse:
      properties:
        job_id:
          type: string
          title: Job Id
          description: Unique job identifier (`exp_<12 hex chars>`).
        status:
          type: string
          title: Status
          description: One of queued, running, succeeded, failed.
        status_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Status Reason
          description: Human readable failure reason when status is failed.
        format:
          type: string
          title: Format
          description: 'Export format: pdf or pptx.'
        download_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Download Url
          description: Single use download URL. Present only when status is succeeded.
        is_fallback:
          type: boolean
          title: Is Fallback
          description: True when the artifact was produced by the local fallback rather than the renderer.
          default: false
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Job creation timestamp (UTC).
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: Job last update timestamp (UTC).
      type: object
      required:
      - job_id
      - status
      - format
      - created_at
      - updated_at
      title: ExportJobResponse
      description: Returned by POST / and GET /{id}.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    ArtifactUploadResponse:
      properties:
        key:
          type: string
          title: Key
          description: S3 object key the artifact was stored under.
        filename:
          type: string
          title: Filename
          description: Sanitised filename used for the download.
        content_type:
          type: string
          title: Content Type
          description: MIME type stored on the object.
        size_bytes:
          type: integer
          title: Size Bytes
          description: Size of the stored artifact in bytes.
        download_url:
          type: string
          title: Download Url
          description: Time-boxed presigned GET URL.
        expires_at:
          type: string
          format: date-time
          title: Expires At
          description: When download_url stops working (UTC).
        artifact_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Artifact Id
          description: Recorded session file-artifact id, if attached to a session.
        session_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Session Id
          description: Managed-agent session id the artifact was filed under, if any.
      type: object
      required:
      - key
      - filename
      - content_type
      - size_bytes
      - download_url
      - expires_at
      title: ArtifactUploadResponse
      description: 'Returned by the artifact-upload endpoints — a hosted artifact plus a

        presigned download URL.'
    ExportRenderDescriptor:
      properties:
        job_id:
          type: string
          title: Job Id
        kind:
          type: string
          title: Kind
        dashboard_id:
          type: integer
          title: Dashboard Id
        target_id:
          type: string
          title: Target Id
        widget:
          additionalProperties: true
          type: object
          title: Widget
        ready_hook:
          type: string
          title: Ready Hook
          description: Name of the window hook the page sets to true once every widget is rendered.
          default: __exportComplete
        data_hook:
          type: string
          title: Data Hook
          description: Name of the function the page exposes to return per widget data tables.
          default: __exportWidgetData
      type: object
      required:
      - job_id
      - kind
      - dashboard_id
      - target_id
      - widget
      title: ExportRenderDescriptor
      description: Returned by GET /{id}/render. Consumed by the Next.js render page.
    Body_upload_export_artifact_api_v1_exports_upload_post:
      properties:
        file:
          type: string
          contentMediaType: application/octet-stream
          title: File
      type: object
      required:
      - file
      title: Body_upload_export_artifact_api_v1_exports_upload_post
    CreateExportRequest:
      properties:
        kind:
          type: string
          const: widget
          title: Kind
          description: Kind of export. POC supports widget only; dashboard and AI brief are a follow up.
          default: widget
        target_id:
          type: string
          maxLength: 200
          title: Target Id
          description: Stable identifier of the widget being exported (the widget's `key`).
        dashboard_id:
          type: integer
          title: Dashboard Id
          description: Id of the dashboard the widget belongs to. Used for access control.
        format:
          type: string
          enum:
          - pdf
          - pptx
          title: Format
          description: Export format. PDF is the default; PPTX produces an editable deck.
          default: pdf
        filters_snapshot:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Filters Snapshot
          description: Filter state as applied at export trigger time. Stored on the job for audit.
        widget_data:
          additionalProperties: true
          type: object
          title: Widget Data
          description: Optional widget payload (chart data table). Used by the local fallback when Playwright is unavailable.
      type: object
      required:
      - target_id
      - dashboard_id
      title: CreateExportRequest
      description: Body of POST /api/v1/exports.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    HTTPBasic:
      type: http
      scheme: basic