Superb AI Jobs API

openapi: 3.2.0
info:
  title: MLOps Platform Jobs API
  description: Multi-tenant labeling-platform backend.
  version: 0.1.0
tags:
- name: Jobs
paths:
  /tenants/{slug}/jobs/{job_id}:
    get:
      tags:
      - Jobs
      summary: Get Job
      operationId: jobs-get_job
      security:
      - HTTPBearer: []
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Job Id
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      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'
        '401':
          description: Unauthenticated — missing, malformed, or expired Bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Authenticated but not authorized for this resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found in this tenant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict — resource state prevents this action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate-limited (per-tenant token bucket)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /tenants/{slug}/jobs:
    get:
      tags:
      - Jobs
      summary: List Jobs
      operationId: jobs-list_jobs
      security:
      - HTTPBearer: []
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Max rows per page.
          default: 50
          title: Limit
        description: Max rows per page.
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Opaque pagination cursor from a previous response's `next_cursor`; omit for the first page.
          title: Cursor
        description: Opaque pagination cursor from a previous response's `next_cursor`; omit for the first page.
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              $ref: '#/components/schemas/JobStatus'
          - type: 'null'
          description: Filter to jobs in any of the given statuses.
          title: Status
        description: Filter to jobs in any of the given statuses.
      - name: kind
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              $ref: '#/components/schemas/JobKind'
          - type: 'null'
          description: Filter to jobs of any of the given kinds.
          title: Kind
        description: Filter to jobs of any of the given kinds.
      - name: created_by
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Filter to jobs created by this user id.
          title: Created By
        description: Filter to jobs created by this user id.
      - name: dataset_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Filter to jobs whose target references this dataset id.
          title: Dataset Id
        description: Filter to jobs whose target references this dataset id.
      - name: project_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Filter to jobs whose target references this project id.
          title: Project Id
        description: Filter to jobs whose target references this project id.
      - name: created_at_from
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Inclusive lower bound (>=) on `created_at` (ISO-8601).
          title: Created At From
        description: Inclusive lower bound (>=) on `created_at` (ISO-8601).
      - name: created_at_to
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Exclusive upper bound (<) on `created_at` (ISO-8601).
          title: Created At To
        description: Exclusive upper bound (<) on `created_at` (ISO-8601).
      - name: include_total
        in: query
        required: false
        schema:
          type: boolean
          description: When true, response carries `total` = COUNT(*) for the same filter (ignores cursor/limit).
          default: false
          title: Include Total
        description: When true, response carries `total` = COUNT(*) for the same filter (ignores cursor/limit).
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobPage'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '401':
          description: Unauthenticated — missing, malformed, or expired Bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Authenticated but not authorized for this resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found in this tenant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict — resource state prevents this action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate-limited (per-tenant token bucket)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              $ref: '#/components/schemas/ErrorCode'
            message:
              type: string
              description: Human-readable; free to evolve. Don't pattern-match on this.
            hint:
              type: string
              nullable: true
              description: When present, a concrete next step (often references a CLI command).
            details:
              type: object
              nullable: true
              description: Per-`code` structured payload; schema documented per code.
            request_id:
              type: string
              nullable: true
              description: Correlation id for support / log lookups.
    JobResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Server-assigned job identifier.
        kind:
          $ref: '#/components/schemas/JobKind'
          description: The kind of work this job performs.
        target:
          additionalProperties: true
          type: object
          title: Target
          description: Kind-specific parameters describing what the job operates on (shape varies per `kind`; internal orchestration fields are omitted).
        status:
          $ref: '#/components/schemas/JobStatus'
          description: Current lifecycle state of the job.
        total:
          type: integer
          title: Total
          description: Total number of work items the job will process.
        processed:
          type: integer
          title: Processed
          description: Number of work items processed so far.
        succeeded:
          type: integer
          title: Succeeded
          description: Number of processed items that succeeded.
        failed:
          type: integer
          title: Failed
          description: Number of processed items that failed.
        skipped:
          type: integer
          title: Skipped
          description: Number of items skipped (ineligible / already in target state).
          default: 0
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Failure message when the job errored, else null.
        result_summary:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Result Summary
          description: Kind-specific summary of the outcome, populated as the job runs and finishes. Stays a plain object here because the key set varies per `kind` (the union isn't a useful client type); the per-kind keys are registry-validated on the write side (`app/job_results.py`), so a given `kind` always carries the same shape.
        created_by:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Created By
          description: User who created the job, or null if system-initiated.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the job was created.
        completed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Completed At
          description: When the job reached a terminal state, or null if still in flight.
        pct:
          anyOf:
          - type: integer
          - type: 'null'
          title: Pct
          description: 'Derived progress percent. A COMPLETED job is always 100 — even a no-op

            with total==0 finished all of its (zero) work; showing 0/null on a done job

            was misleading. Otherwise processed/total, or None when total is unknown

            (freshly-queued, denominator not yet resolved).'
          readOnly: true
      type: object
      required:
      - id
      - kind
      - target
      - status
      - total
      - processed
      - succeeded
      - failed
      - error
      - created_by
      - created_at
      - completed_at
      - pct
      title: JobResponse
    JobStatus:
      type: string
      enum:
      - pending
      - queued
      - running
      - completed
      - failed
      - canceled
      title: JobStatus
    JobKind:
      type: string
      enum:
      - build_project_version_manifest
      - bulk_delete_image_assets
      - bulk_update_tags_project
      - bulk_add_assets_project
      - bulk_remove_assets_project
      - bulk_assign_assets_project
      - bulk_unassign_assets_project
      - bulk_approve_assets_project
      - bulk_reject_assets_project
      - bulk_create_annotations
      - bulk_delete_annotations
      - embed_dataset
      - export_dataset
      - auto_label_project
      - cleanup_s3_objects
      - delete_project_cascade
      - delete_dataset_cascade
      - duplicate_project_scope
      - bulk_set_status_assets_project
      title: JobKind
    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
    JobPage:
      properties:
        items:
          items:
            $ref: '#/components/schemas/JobResponse'
          type: array
          title: Items
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
        total:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total
      type: object
      required:
      - items
      title: JobPage
    ErrorCode:
      type: string
      enum:
      - UNCATEGORIZED
      - AUTH_MISSING
      - AUTH_INVALID_CREDENTIAL
      - AUTH_TOKEN_EXPIRED
      - AUTH_FORBIDDEN
      - AUTH_TENANT_MISMATCH
      - VALIDATION_ERROR
      - VALIDATION_REQUIRED_CLASSIFICATION_MISSING
      - BAD_REQUEST
      - INVALID_CURSOR
      - INVALID_FILTER
      - UNSUPPORTED_OPERATION
      - PAYLOAD_TOO_LARGE
      - TENANT_NOT_FOUND
      - TENANT_SLUG_TAKEN
      - USER_NOT_FOUND
      - USER_EMAIL_TAKEN
      - INVITATION_NOT_FOUND
      - INVITATION_PENDING
      - INVITATION_NOT_PENDING
      - INVITATION_EXPIRED
      - LAST_ADMIN
      - DATASET_NOT_FOUND
      - DATASET_NAME_TAKEN
      - DATASET_DELETED
      - DATASET_ASSET_CAP_EXCEEDED
      - ASSET_NOT_FOUND
      - ASSET_DELETED
      - ASSET_NOT_EMBEDDED
      - ASSET_FORMAT_UNSUPPORTED
      - ASSET_TOO_LARGE
      - PROJECT_NOT_FOUND
      - PROJECT_ARCHIVED
      - PROJECT_MEMBER_NOT_FOUND
      - PROJECT_CLASS_NOT_FOUND
      - VERSION_NOT_FOUND
      - MODEL_NOT_FOUND
      - RESOURCE_NOT_READY
      - PROJECT_STATE_FORBIDDEN
      - CLASS_LOCKED
      - CLASS_IN_USE
      - DEPLOYMENT_NOT_FOUND
      - DEPLOYMENT_STATE_FORBIDDEN
      - EXPORT_EXPIRED
      - EXPORT_FAILED
      - ANNOTATION_NOT_FOUND
      - JOB_NOT_FOUND
      - JOB_ALREADY_RUNNING
      - JOB_PER_TENANT_CAP
      - JOB_TERMINAL
      - EMBEDDER_UNAVAILABLE
      - EMBEDDER_INVOCATION_FAILED
      - NAME_TAKEN
      - IDEMPOTENCY_REPLAY
      - CONCURRENT_MODIFICATION
      - RATE_LIMITED
      - RESOURCE_LIMIT_EXCEEDED
      - INTERNAL_ERROR
      - DEPENDENCY_UNAVAILABLE
      - MODEL_LOADING
      - MODEL_STARTING
      description: Stable error code enum. Pattern-match here, never on `message`. Adding values is non-breaking; renaming/removing is a major bump.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      description: Cognito access token
      scheme: bearer