Beatra AI Tasks API

openapi: 3.2.0
info:
  title: Beatra Ai Tasks API
  version: 0.1.0
  description: 'Operations tagged tasks across 2 of this provider''s published API definitions: beatra-ai-api-openapi.json, beatra-ai-docs-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.beatra.ai
tags:
- name: Tasks
paths:
  /v1/tasks:
    get:
      tags:
      - Tasks
      summary: List the caller's tasks
      description: Returns TaskSummary by default. Use `?expand=output,usage,billing,callback,input` or `?expand=all` to return full TaskEnvelope items.
      operationId: list_tasks_v1_tasks_get
      parameters:
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          title: Status
      - name: capability
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          title: Capability
      - name: created_after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Created After
      - name: created_before
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Created Before
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 20
          title: Limit
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Cursor
      - name: order
        in: query
        required: false
        schema:
          enum:
          - asc
          - desc
          type: string
          default: desc
          title: Order
      - name: expand
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Comma-separated fields to include: output,usage,billing,callback,input,all'
          title: Expand
        description: 'Comma-separated fields to include: output,usage,billing,callback,input,all'
      - 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/app__api__v1__schemas__tasks__TaskListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-beatra:
        visibility: public
        group: tasks
        title: Async tasks
        product_area: Async tasks
        mode: sync
        lifecycle: preview
        release_state: preview
        customer_facing: true
        docs_order: 10
  /v1/tasks/{task_id}:
    get:
      tags:
      - Tasks
      summary: Get a task by id
      operationId: get_task_v1_tasks__task_id__get
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
          title: Task Id
      - 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/TaskEnvelope'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-beatra:
        visibility: public
        group: tasks
        title: Async tasks
        product_area: Async tasks
        mode: sync
        lifecycle: preview
        release_state: preview
        customer_facing: true
        docs_order: 20
  /v1/tasks/{task_id}/cancel:
    post:
      tags:
      - Tasks
      summary: Cancel a task
      operationId: cancel_task_v1_tasks__task_id__cancel_post
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
          title: Task Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/TaskCancelRequest'
              - type: 'null'
              title: Req
      responses:
        '200':
          description: Already terminal; returns final state (idempotent)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskEnvelope'
        '409':
          description: Remote execution cannot be confirmed canceled; task continues
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-beatra:
        visibility: public
        group: tasks
        title: Async tasks
        product_area: Async tasks
        mode: sync
        lifecycle: preview
        release_state: preview
        customer_facing: true
        docs_order: 30
components:
  schemas:
    app__api__v1__schemas__common__TaskProgress:
      properties:
        percent:
          anyOf:
          - type: integer
            maximum: 100.0
            minimum: 0.0
          - type: 'null'
          title: Percent
        stage:
          anyOf:
          - type: string
          - type: 'null'
          title: Stage
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
      type: object
      title: TaskProgress
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    TaskWarning:
      properties:
        code:
          type: string
          title: Code
          description: e.g. option_clamped / auto_routed
        message:
          type: string
          title: Message
        field:
          anyOf:
          - type: string
          - type: 'null'
          title: Field
      type: object
      required:
      - code
      - message
      title: TaskWarning
    TaskEnvelope:
      properties:
        object:
          type: string
          const: task
          title: Object
          default: task
        task_id:
          type: string
          title: Task Id
        status:
          type: string
          enum:
          - queued
          - running
          - succeeded
          - failed
          - canceled
          title: Status
        capability:
          type: string
          title: Capability
        workload_type:
          type: string
          enum:
          - model
          - social_operation
          title: Workload Type
          default: model
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
          description: Caller-requested model verbatim (may be 'auto'). Null for social_operation tasks.
        resolved_model:
          anyOf:
          - type: string
          - type: 'null'
          title: Resolved Model
          description: Actual model that ran (null until execution starts; equals model for explicit-model calls)
        model_selection_reason:
          type: 'null'
          title: Model Selection Reason
          description: Deprecated. Always null.
          deprecated: true
        social:
          anyOf:
          - $ref: '#/components/schemas/SocialTaskIdentity'
          - type: 'null'
        metadata:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Metadata
        input:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Input
        progress:
          anyOf:
          - $ref: '#/components/schemas/app__api__v1__schemas__common__TaskProgress'
          - type: 'null'
        output:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Output
        warnings:
          items:
            $ref: '#/components/schemas/TaskWarning'
          type: array
          title: Warnings
        error:
          anyOf:
          - $ref: '#/components/schemas/app__api__v1__schemas__common__TaskError'
          - type: 'null'
        usage:
          anyOf:
          - $ref: '#/components/schemas/UsageObject'
          - type: 'null'
        billing:
          anyOf:
          - $ref: '#/components/schemas/TaskBilling'
          - type: 'null'
        callback:
          anyOf:
          - $ref: '#/components/schemas/TaskCallback'
          - type: 'null'
        created_at:
          type: string
          format: date-time
          title: Created At
        started_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Started At
        deadline_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Deadline At
        completed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Completed At
        cancel_requested_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Cancel Requested At
        links:
          $ref: '#/components/schemas/TaskLinks'
      type: object
      required:
      - task_id
      - status
      - capability
      - created_at
      - links
      title: TaskEnvelope
      description: 'Standard Task envelope.


        Returned by every async-creation endpoint, GET /v1/tasks/{id}, and

        the body of customer callback POSTs.'
    TaskCancelRequest:
      properties:
        reason:
          anyOf:
          - type: string
            maxLength: 512
          - type: 'null'
          title: Reason
      type: object
      title: TaskCancelRequest
    app__api__v1__schemas__common__TaskError:
      properties:
        code:
          type: string
          title: Code
          description: Stable machine-readable public error code.
        type:
          type: string
          title: Type
          description: Stable public error family.
        message:
          type: string
          title: Message
          description: Human-readable safe failure reason.
        retryable:
          type: boolean
          title: Retryable
          description: Whether the same logical request may succeed when retried unchanged.
        param:
          anyOf:
          - type: string
          - type: 'null'
          title: Param
          description: JSON Pointer to the relevant request or output field.
        details:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Details
          description: Provider-neutral expected, received, supported, or candidate failure facts.
        request_id:
          type: string
          title: Request Id
          description: Request trace identifier for support and correlation.
      type: object
      required:
      - code
      - type
      - message
      - retryable
      - request_id
      title: TaskError
    ErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      type: object
      required:
      - error
      title: ErrorResponse
    TaskBilling:
      properties:
        charged_credits:
          anyOf:
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          - type: 'null'
          title: Charged Credits
          description: Credits charged to wallet for this Task. Populated by PR-2/3.
        refunded_credits:
          anyOf:
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          - type: 'null'
          title: Refunded Credits
          description: Credits refunded for this Task. Populated by PR-3.
        granted_credits:
          anyOf:
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          - type: 'null'
          title: Granted Credits
          description: Credits on this Task covered by a directed grant rather than by the wallet, net of any revocation. Absent when no grant applied.
        grant_source:
          anyOf:
          - type: string
          - type: 'null'
          title: Grant Source
          description: Which grant covered it. Present exactly when granted_credits is.
        net_charged_credits:
          anyOf:
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          - type: 'null'
          title: Net Charged Credits
          description: 'Final customer charge: charged_credits minus refunded_credits minus granted_credits. This is the number to report as what the Task cost.'
      type: object
      title: TaskBilling
    app__api__v1__schemas__tasks__TaskListResponse:
      properties:
        object:
          type: string
          const: list
          title: Object
          default: list
        data:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Data
          description: TaskSummary[] by default; TaskEnvelope[] with expand
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
        has_more:
          type: boolean
          title: Has More
          default: false
      type: object
      required:
      - data
      title: TaskListResponse
      description: 'List response wrapper. Uses TaskSummary by default.


        Clients can opt-in to richer detail via `?expand=output,usage,billing,callback,input`

        or `?expand=all`. When expand is in effect, items become full TaskEnvelope.'
    UsageLine:
      properties:
        meter:
          type: string
          title: Meter
          description: e.g. input_token / output_token / image_count / input_video_second / output_video_second
        quantity:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Quantity
          description: Decimal — number of meter units consumed
        unit:
          type: string
          title: Unit
          description: Display unit, e.g. 'token' / 'image' / 'second'
        billed_amount_credits:
          anyOf:
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          - type: 'null'
          title: Billed Amount Credits
          description: Credits charged for this usage line. Populated by PR-2/3.
      type: object
      required:
      - meter
      - quantity
      - unit
      title: UsageLine
    TaskLinks:
      properties:
        self:
          type: string
          title: Self
        cancel:
          anyOf:
          - type: string
          - type: 'null'
          title: Cancel
        assets:
          anyOf:
          - type: string
          - type: 'null'
          title: Assets
          description: Absolute customer-console URL for viewing and managing the generated artifacts.
      type: object
      required:
      - self
      title: TaskLinks
    TaskCallback:
      properties:
        url:
          type: string
          title: Url
        status:
          type: string
          enum:
          - pending
          - dispatching
          - delivered
          - retrying
          - failed
          title: Status
        attempt_count:
          type: integer
          title: Attempt Count
        delivered_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Delivered At
        last_error:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Error
          description: Stable Beatra-owned callback delivery failure summary.
      type: object
      required:
      - url
      - status
      - attempt_count
      title: TaskCallback
    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
    SocialTaskIdentity:
      properties:
        platform:
          type: string
          title: Platform
        operation_key:
          type: string
          title: Operation Key
        operation_name:
          type: string
          title: Operation Name
        schema_hash:
          type: string
          title: Schema Hash
      type: object
      required:
      - platform
      - operation_key
      - operation_name
      - schema_hash
      title: SocialTaskIdentity
    UsageObject:
      properties:
        input_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Input Tokens
        output_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Output Tokens
        cache_read_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Cache Read Tokens
        cache_creation_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Cache Creation Tokens
        reasoning_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Reasoning Tokens
        image_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Image Count
        image_pixels:
          anyOf:
          - type: integer
          - type: 'null'
          title: Image Pixels
        video_seconds:
          anyOf:
          - type: number
          - type: 'null'
          title: Video Seconds
        input_video_seconds:
          anyOf:
          - type: number
          - type: 'null'
          title: Input Video Seconds
          description: Authoritative input-video seconds included in settled video usage.
        output_video_seconds:
          anyOf:
          - type: number
          - type: 'null'
          title: Output Video Seconds
          description: Authoritative generated/output-video seconds included in settled video usage.
        audio_seconds:
          anyOf:
          - type: number
          - type: 'null'
          title: Audio Seconds
        characters:
          anyOf:
          - type: integer
          - type: 'null'
          title: Characters
        lines:
          items:
            $ref: '#/components/schemas/UsageLine'
          type: array
          title: Lines
        credits:
          anyOf:
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          - type: 'null'
          title: Credits
          description: Credits charged for this Task. Populated by PR-2 / PR-3.
      type: object
      title: UsageObject
    ErrorBody:
      properties:
        code:
          type: string
          title: Code
          description: Stable public error code
        type:
          type: string
          title: Type
          description: Broad SDK-friendly error family
        message:
          type: string
          title: Message
          description: Human-readable explanation
        retryable:
          type: boolean
          title: Retryable
          description: If true, retrying the exact same request may succeed
        details:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Details
          description: Code-specific structured info
        request_id:
          type: string
          title: Request Id
          description: Echo of X-Request-Id for support correlation
        param:
          anyOf:
          - type: string
          - type: 'null'
          title: Param
          description: JSON Pointer to offending field, if applicable
      type: object
      required:
      - code
      - type
      - message
      - retryable
      - request_id
      title: ErrorBody
x-refined-from:
- beatra-ai-api-openapi.json
- beatra-ai-docs-openapi.json