superdocs-app Jobs API

openapi: 3.2.0
info:
  title: 'Typebar API: Universal Document AI Jobs API'
  description: 'Typebar (formerly SuperDocs): AI-powered document editing with multi-tenant organization support'
  version: 2.0.0
servers:
- url: https://api.superdocs.app
tags:
- name: Jobs
paths:
  /v1/jobs:
    get:
      tags:
      - Jobs
      summary: List your async chat jobs (in-progress, awaiting approval, completed, failed)
      description: Returns jobs sorted by most recent, optionally filtered by status. Use to monitor long-running AI edits started via chat_async, see which jobs are paused waiting for human approval, or audit completed work. Each job tracks the chat that started it, the changes made, and any HITL decisions logged.
      operationId: list_jobs
      security:
      - HTTPBearer: []
      parameters:
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by job status
          title: Status
        description: Filter by job status
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          description: Maximum number of jobs to return
          default: 50
          title: Limit
        description: Maximum number of jobs to return
      - name: compact
        in: query
        required: false
        schema:
          type: boolean
          description: When true, omit each job's heavy result body + streamed intermediate events — returns just status/progress/ids/timestamps. Recommended for agents listing many jobs.
          default: false
          title: Compact
        description: When true, omit each job's heavy result body + streamed intermediate events — returns just status/progress/ids/timestamps. Recommended for agents listing many jobs.
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/jobs/{job_id}:
    get:
      tags:
      - Jobs
      summary: Get the status, partial results, and any pending changes for an async chat job
      description: Returns the job's current state (pending, in_progress, awaiting_approval, completed, failed, or cancelled), intermediate AI responses streamed during execution, the final document HTML once complete, and any pending changes awaiting user approval (with chunk IDs and proposed HTML diffs in metadata.pending_changes). Poll this after chat_async to track progress and retrieve results. When status is awaiting_approval, call POST /v1/chat/{session_id}/approve to approve or deny each pending change. Headless/MCP clients get the same typed progress events the web SSE stream delivers via metadata.intermediate_responses (e.g. documents_changed, continue_prompt, model_fallback, proposed_change_batch); cross-session document updates from OTHER sessions are reported separately by polling GET /v1/sessions/{session_id}/doc-events.
      operationId: get_job
      security:
      - HTTPBearer: []
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: compact
        in: query
        required: false
        schema:
          type: boolean
          description: 'When true, omit the heavy result body + streamed intermediate events from the response (status/progress/ids/timestamps/pending-change ids remain). Recommended for AI agents polling a large-document job: poll compact while it runs, then fetch once non-compact when status is completed to retrieve the final HTML.'
          default: false
          title: Compact
        description: 'When true, omit the heavy result body + streamed intermediate events from the response (status/progress/ids/timestamps/pending-change ids remain). Recommended for AI agents polling a large-document job: poll compact while it runs, then fetch once non-compact when status is completed to retrieve the final HTML.'
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/jobs/{job_id}/cancel:
    post:
      tags:
      - Jobs
      summary: Cancel a pending or in-progress async chat job
      description: 'Stops a running turn, or ends a turn that is waiting for your review by discarding its staged changes. Already-applied changes are preserved in the document; anything still pending is discarded. Use to abort work that is no longer wanted (e.g. the user changed their mind, or you want to retry with different parameters or model_tier). The response tells you whether the work was stopped here and now (`stop_state: "stopped_here"`) or the stop was ACCEPTED and is being carried out by the instance running the turn (`stop_state: "accepted"`) — in the accepted case poll get_job until `metadata.stopped_unwound` is true or the job reaches a terminal status. A turn that already finished cannot be stopped and returns 409 naming its status.'
      operationId: cancel_job
      security:
      - HTTPBearer: []
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/sessions/{session_id}/jobs:
    get:
      tags:
      - Jobs
      summary: List all async chat jobs for a specific session, most recent first
      description: Returns the full job history of one document. Useful for auditing what the AI did to a document over time, or finding a specific job that's waiting for HITL approval. Same shape as list_jobs but scoped to one session.
      operationId: get_session_jobs
      security:
      - HTTPBearer: []
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          description: Maximum number of jobs to return
          default: 20
          title: Limit
        description: Maximum number of jobs to return
      - name: compact
        in: query
        required: false
        schema:
          type: boolean
          description: When true, omit each job's heavy result body + streamed intermediate events — returns just status/progress/ids/timestamps. Recommended for agents listing many jobs.
          default: false
          title: Compact
        description: When true, omit each job's heavy result body + streamed intermediate events — returns just status/progress/ids/timestamps. Recommended for agents listing many jobs.
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    PendingChange:
      properties:
        change_id:
          type: string
          title: Change Id
          description: Unique identifier for this proposed change.
        operation:
          type: string
          title: Operation
          description: 'Type of change: ''edit'', ''create'', or ''delete''.'
        chunk_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Chunk Id
          description: Target document section ID being modified or deleted.
        document_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Document Id
          description: Identifier of the document (tab) this change applies to — lets multi-document integrators attribute each section diff to the right document.
        old_html:
          anyOf:
          - type: string
          - type: 'null'
          title: Old Html
          description: Previous HTML content of the section (for updates).
        new_html:
          anyOf:
          - type: string
          - type: 'null'
          title: New Html
          description: Proposed new HTML content (for updates and creates).
        ai_explanation:
          anyOf:
          - type: string
          - type: 'null'
          title: Ai Explanation
          description: AI-generated explanation of why this change was proposed.
      additionalProperties: true
      type: object
      required:
      - change_id
      - operation
      title: PendingChange
      description: A proposed document change awaiting user approval.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    JobListResponse:
      properties:
        jobs:
          items:
            $ref: '#/components/schemas/JobResponse'
          type: array
          title: Jobs
          description: Array of job details.
        total:
          type: integer
          title: Total
          description: Total number of jobs returned.
      type: object
      required:
      - jobs
      - total
      title: JobListResponse
      description: List of async jobs.
    DocumentChanges:
      properties:
        updated_html:
          anyOf:
          - type: string
          - type: 'null'
          title: Updated Html
          description: Full updated document HTML with data-chunk-id attributes. Apply this to your editor to sync the document. Present in 'full' response mode (default); null in 'compact' mode.
        version_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Version Id
          description: Document version identifier. Changes on every modification.
        changes_summary:
          anyOf:
          - type: string
          - type: 'null'
          title: Changes Summary
          description: Human-readable summary of what was changed.
        requires_approval:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Requires Approval
          description: If true, changes need review via the approve endpoint before being applied.
        pending_changes:
          anyOf:
          - items:
              $ref: '#/components/schemas/PendingChange'
            type: array
          - type: 'null'
          title: Pending Changes
          description: Proposed changes awaiting approval. Present when requires_approval is true.
        changes:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          title: Changes
          description: History of individual changes applied during this request.
        chunk_diffs:
          anyOf:
          - items:
              $ref: '#/components/schemas/PendingChange'
            type: array
          - type: 'null'
          title: Chunk Diffs
          description: Per-section before/after content for changes that were applied this turn. Present in 'compact' response mode (when updated_html is null) so the agent can verify what was modified without paying token cost for the full document. Same shape as pending_changes.
        concurrent_merges:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          title: Concurrent Merges
          description: 'Present ONLY when this request''s edit collided with a concurrent edit: another session/chat committed a different change to the same section(s) while this request was processing, and the two were merged server-side. One entry per affected document: {document_id, durable_document_id, version, conflicting_sections}. When present, updated_html reflects the merged COMMITTED state — it may differ from the text this response describes; review the affected sections and re-apply anything that was superseded. Absent (null) on every non-conflicting request, including concurrent edits to DIFFERENT sections (those merge cleanly with no data loss and no notice).'
      additionalProperties: true
      type: object
      title: DocumentChanges
      description: Document modifications produced by the AI assistant.
    UsageInfo:
      properties:
        monthly_used:
          anyOf:
          - type: integer
          - type: 'null'
          title: Monthly Used
          description: Total operations used this billing cycle.
        monthly_limit:
          anyOf:
          - type: integer
          - type: 'null'
          title: Monthly Limit
          description: Maximum operations allowed per cycle. -1 means unlimited.
        monthly_remaining:
          anyOf:
          - type: integer
          - type: 'null'
          title: Monthly Remaining
          description: Operations remaining this cycle. -1 means unlimited.
        was_billable:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Was Billable
          description: Whether this request counted as a billable operation.
        ops_charged:
          anyOf:
          - type: integer
          - type: 'null'
          title: Ops Charged
          description: How many operations this request billed. A large multi-section edit can bill more than one (one per 25 sections edited), so monthly_used can increase by more than 1 between responses.
        quota_exhausted:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Quota Exhausted
          description: True when you have reached your plan's operation limit with no remaining balance — the current request still completes, but further billable requests pause until you upgrade or your billing cycle resets.
        subscription_tier:
          anyOf:
          - type: string
          - type: 'null'
          title: Subscription Tier
          description: 'Current subscription tier: ''free'', ''plus'', ''pro'', or ''enterprise''.'
        bucket_used:
          anyOf:
          - type: string
          - type: 'null'
          title: Bucket Used
          description: 'Which bucket this operation drew from: ''tier'' or ''promo''. Null for non-billable ops.'
        redemption_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Redemption Id
          description: Redemption grant this op drew from, when bucket_used is 'promo'.
        promotions:
          anyOf:
          - items:
              $ref: '#/components/schemas/ActivePromotionInfo'
            type: array
          - type: 'null'
          title: Promotions
          description: User's currently-active promotion grants, ordered by oldest-expiring first.
      additionalProperties: true
      type: object
      title: UsageInfo
      description: Operation usage data for the current billing cycle.
    JobMetadata:
      properties:
        filename:
          anyOf:
          - type: string
          - type: 'null'
          title: Filename
          description: Uploaded filename (attachment processing jobs).
        file_size:
          anyOf:
          - type: integer
          - type: 'null'
          title: File Size
          description: File size in bytes (attachment processing jobs).
        content_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Content Type
          description: MIME type of uploaded file (attachment processing jobs).
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
          description: Original user message (chat jobs).
        document_html_provided:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Document Html Provided
          description: Whether document HTML was included in the request (chat jobs).
        pending_changes:
          anyOf:
          - items:
              $ref: '#/components/schemas/PendingChange'
            type: array
          - type: 'null'
          title: Pending Changes
          description: Proposed changes awaiting approval. Present when job status is 'awaiting_approval'.
        intermediate_responses:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          title: Intermediate Responses
          description: 'Progress updates during processing. Each item has: type, content, sequence, timestamp.'
      additionalProperties: true
      type: object
      title: JobMetadata
      description: Job metadata. Contents vary by job type.
    JobResponse:
      properties:
        job_id:
          type: string
          title: Job Id
          description: Unique job identifier. Use this to poll for status updates.
        organization_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Organization Id
          description: Organization that owns this job (null for user jobs).
        user_id:
          anyOf:
          - type: string
          - type: 'null'
          title: User Id
          description: User that owns this job (null for organization jobs).
        session_id:
          type: string
          title: Session Id
          description: Session associated with this job.
        job_type:
          type: string
          title: Job Type
          description: 'Type of job: ''chat'' or ''attachment_processing''.'
        status:
          type: string
          title: Status
          description: 'Current status: ''pending'', ''in_progress'', ''awaiting_approval'', ''completed'', ''failed'', or ''cancelled''.'
        created_at:
          type: string
          title: Created At
          description: ISO 8601 timestamp when the job was created.
        updated_at:
          type: string
          title: Updated At
          description: ISO 8601 timestamp of the last status change.
        progress:
          type: integer
          title: Progress
          description: Progress percentage (0-100).
        result:
          anyOf:
          - $ref: '#/components/schemas/JobResult'
          - type: 'null'
          description: Job output. Present when status is 'completed'. Contains AI response and document changes for chat jobs.
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message. Present when status is 'failed'.
        metadata:
          anyOf:
          - $ref: '#/components/schemas/JobMetadata'
          - type: 'null'
          description: Job metadata and context. Contains pending_changes when status is 'awaiting_approval'.
      type: object
      required:
      - job_id
      - session_id
      - job_type
      - status
      - created_at
      - updated_at
      - progress
      title: JobResponse
      description: Status and details of an async job.
    ActivePromotionInfo:
      properties:
        redemption_id:
          type: string
          title: Redemption Id
          description: Unique identifier for this promotion grant.
        name:
          type: string
          title: Name
          description: Human-friendly promotion name (e.g., 'YC SUS India 2026 cohort').
        ops_remaining:
          type: integer
          title: Ops Remaining
          description: Operations still available in this promotion bucket.
        ops_granted:
          type: integer
          title: Ops Granted
          description: Total operations originally granted by this redemption.
        expires_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Expires At
          description: ISO 8601 expiry timestamp. Null if the credits never expire.
      additionalProperties: true
      type: object
      required:
      - redemption_id
      - name
      - ops_remaining
      - ops_granted
      title: ActivePromotionInfo
      description: A single active (drawable) promotion belonging to the authenticated user.
    JobResult:
      properties:
        response:
          anyOf:
          - type: string
          - type: 'null'
          title: Response
          description: AI response text (chat jobs).
        session_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Id
          description: Session identifier (chat jobs).
        document_changes:
          anyOf:
          - $ref: '#/components/schemas/DocumentChanges'
          - type: 'null'
          description: Document modifications (chat jobs).
        usage:
          anyOf:
          - $ref: '#/components/schemas/UsageInfo'
          - type: 'null'
          description: Usage tracking data (chat jobs).
        attachment_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Attachment Id
          description: Processed attachment identifier (attachment processing jobs).
      additionalProperties: true
      type: object
      title: JobResult
      description: Job result data. Structure depends on job type.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer