BAMF.ai Jobs API

openapi: 3.2.0
info:
  title: BAMF Developer Platform Jobs API
  version: 0.1.0
servers:
- url: https://api.bamf.ai/v1
security:
- BearerAuth: []
tags:
- name: Jobs
paths:
  /jobs:
    get:
      summary: List async jobs
      parameters:
      - name: creator_id
        in: query
        schema:
          type: string
      - name: status
        in: query
        schema:
          type: string
          enum:
          - queued
          - running
          - succeeded
          - completed
          - failed
          - cancelled
          - canceled
      - name: job_type
        in: query
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          maximum: 100
      responses:
        '200':
          description: Jobs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiJobsResponse'
      tags:
      - Jobs
      operationId: getJobs
      x-operation-id-source: derived
    post:
      summary: Create async job
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateJobRequest'
      responses:
        '202':
          description: Job queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiJobResponse'
      tags:
      - Jobs
      operationId: postJobs
      x-operation-id-source: derived
  /jobs/{job_id}/private-video-diagnostic:
    get:
      summary: Reconcile an existing private video request status
      description: Read-only status reconciliation for an already-failed private video job. Requires a signed-in user JWT with images:generate and ownership of the job's exact creator/project/private-keyframe scope. Performs one provider status GET for the request ID already stored on the job; it does not submit, retry, cancel, or mutate a job. Provider detail is reduced to closed reason and detail enums; no raw provider response or request ID is returned.
      security:
      - BearerAuth: []
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Bounded provider status diagnostic.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivateVideoDiagnosticResponse'
        '400':
          description: Malformed job UUID.
        '401':
          description: Valid signed-in user session required.
        '403':
          description: Signed-in user or scope required.
        '404':
          description: No eligible private video job was found in this user's scope.
        '503':
          description: Server-side diagnostic credentials are unavailable. Provider status transport failures return a bounded 200 diagnostic.
      tags:
      - Jobs
      operationId: getJobsByJobIdPrivateVideoDiagnostic
      x-operation-id-source: derived
  /jobs/{job_id}/private-video-recovery:
    post:
      summary: Recover one failed private video job
      description: Requires a signed-in user JWT with images:generate and exact ownership of the failed private keyframe job. The original Higgsfield status must be remotely confirmed as failed and not moderated or invalid_request. The request body may be omitted or be an empty JSON object; Idempotency-Key is required. At most one fixed Fal Seedance 2.5 image-to-video child is reserved for the exact original settings. An ambiguous submit is fenced and never automatically resubmitted. Replays poll only the saved queue handle; the parent job is unchanged. The response contains only a closed recovery state and child job ID; use the normal scoped GET job route for authorized private output.
      security:
      - BearerAuth: []
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
          minLength: 8
          maxLength: 160
          pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]{7,159}$
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              maxProperties: 0
              additionalProperties: false
      responses:
        '200':
          description: Recovery reached a terminal state or replay returned the existing terminal state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivateVideoRecoveryResponse'
        '202':
          description: Recovery is submitting, queued, in progress, or fenced after an ambiguous submission. Repeating the same request never resubmits an unknown attempt.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivateVideoRecoveryResponse'
        '400':
          description: Malformed job ID, missing/invalid idempotency key, or non-empty body.
        '401':
          description: Valid signed-in user session required.
        '403':
          description: Signed-in user or images:generate scope required.
        '404':
          description: No eligible private video job was found in this user's scope.
        '409':
          description: The failure is not eligible or an existing recovery has a different idempotency/settings binding.
        '429':
          description: Generation rate limit exceeded.
        '503':
          description: Provider status, recovery persistence, or private media services are temporarily unavailable.
      tags:
      - Jobs
      operationId: postJobsByJobIdPrivateVideoRecovery
      x-operation-id-source: derived
  /jobs/{job_id}:
    get:
      summary: Get job
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiJobResponse'
      tags:
      - Jobs
      operationId: getJobsByJobId
      x-operation-id-source: derived
    delete:
      summary: Cancel job
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Job cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiJobResponse'
      tags:
      - Jobs
      operationId: deleteJobsByJobId
      x-operation-id-source: derived
components:
  schemas:
    ApiJob:
      type: object
      properties:
        id:
          type: string
        job_type:
          type: string
          enum:
          - post.generate
          - post.edit
          - image.generate
          - carousel.generate
          - carousel.pdf
          - brand_kit.generate
          - research.run
          - knowledge.process
          - analytics.sync
        status:
          type: string
          enum:
          - queued
          - running
          - succeeded
          - completed
          - failed
          - cancelled
          - canceled
        creator_id:
          type: string
        input:
          $ref: '#/components/schemas/JSONValue'
        output:
          $ref: '#/components/schemas/JSONValue'
        error:
          $ref: '#/components/schemas/JSONValue'
          description: Private founder-video jobs may return a PrivateVideoJobError with allowlisted stage, category, provider, request ID, status, and HTTP status fields; no raw provider text or URLs are exposed.
        created_at:
          type:
          - string
          - 'null'
          format: date-time
        updated_at:
          type:
          - string
          - 'null'
          format: date-time
    ApiJobsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ApiJob'
    CreateJobRequest:
      type: object
      required:
      - creator_id
      - job_type
      properties:
        creator_id:
          type: string
        job_type:
          type: string
          enum:
          - post.generate
          - post.edit
          - image.generate
          - video.generate
          - carousel.generate
          - carousel.pdf
          - brand_kit.generate
          - research.run
          - knowledge.process
          - analytics.sync
        input:
          $ref: '#/components/schemas/JSONValue'
        cost_class:
          type: string
    PrivateVideoDiagnosticResponse:
      type: object
      additionalProperties: false
      required:
      - data
      properties:
        data:
          type: object
          additionalProperties: false
          required:
          - provider
          - status
          - reason
          - detail
          - httpStatus
          properties:
            provider:
              const: higgsfield
            status:
              type:
              - string
              - 'null'
              enum:
              - queued
              - in_progress
              - completed
              - failed
              - nsfw
              - canceled
              - unknown
              - null
            reason:
              type: string
              description: Conservative normalized category inferred from provider status/error text; these are not provider-defined error codes.
              enum:
              - moderated
              - cancelled
              - insufficient_balance
              - capacity_or_rate_limit
              - invalid_request
              - provider_failed
              - upstream_http_error
              - provider_unreachable
              - unknown
            detail:
              type: string
              description: Coarse closed category inferred from explicit provider wording patterns; not a verified root cause, provider code, or raw provider text.
              enum:
              - source_fetch_failed
              - source_media_invalid
              - unsupported_model
              - provider_internal_error
              - generation_failed
              - unknown
            httpStatus:
              type:
              - integer
              - 'null'
              minimum: 100
              maximum: 599
    PrivateVideoRecoveryResponse:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    ApiJobResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ApiJob'
    JSONValue:
      description: Any JSON value returned by flexible workflow, analytics, context, or generation payloads.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer