majr-app Jobs API

openapi: 3.2.0
info:
  title: media-encoding Jobs API
  version: 1.3.2
  description: 'A MAJR Agent Service: encodes user uploads into streaming media (video -> HLS, audio -> AAC/M4A, image -> WebP) as async jobs — enqueue, then a signed completion callback, with GET /v1/jobs/{jobId} as the poll backstop. Media bytes are never persisted beyond the job. Storage is caller-supplied per request, OR use the managed temporary storage path (POST /v1/uploads — presigned upload in, presigned outputs out) for zero-setup onboarding. Both callback and destination are optional (polling-first).'
servers:
- url: https://encoding.majr.app
tags:
- name: Jobs
paths:
  /v1/jobs/{jobId}:
    get:
      operationId: getJob
      summary: Job status + manifest (the poll backstop)
      security:
      - bearerAuth: []
      parameters:
      - name: jobId
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]{1,255}$
      responses:
        '200':
          description: Current job state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobState'
        '401':
          description: Missing or invalid bearer token.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: No such job.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '410':
          description: The managed outputs for this job are no longer retrievable — deleted (retention window elapsed) OR incomplete (a required manifest artifact was partially deleted). A deliberate Gone, never presigned URLs to missing objects.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: 'Free-tier quota reached (`code: free_tier_quota`): `reason` is `account_quota` (this builder''s calls for the month are used) or `fleet_quota` (every self-serve key is paused for the day); `resets_at` says when the key works again. Honor Retry-After; the key is valid — do not rotate keys on 429.'
          headers:
            Retry-After:
              description: Seconds until resets_at — when the key works again.
              schema:
                type: integer
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/QuotaProblem'
        '500':
          description: The encode succeeded but its managed output inventory exceeded the single-page listing cap — a deliberate failure rather than a silently partial inventory.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: 'Auth not judgeable right now: service auth unconfigured, or the key store has not loaded yet (cold boot / plane outage). Retryable — honor Retry-After; never a key-validity verdict, so do not rotate keys on 503.'
          headers:
            Retry-After:
              description: Seconds until the auth cache will attempt another load (when retryable).
              schema:
                type: integer
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      tags:
      - Jobs
components:
  schemas:
    QuotaProblem:
      description: 'Free-tier quota reached: RFC 7807 problem details plus the machine fields an agent acts on.'
      allOf:
      - $ref: '#/components/schemas/Problem'
      properties:
        code:
          type: string
          enum:
          - free_tier_quota
        reason:
          type: string
          enum:
          - account_quota
          - fleet_quota
          description: 'account_quota: this builder''s calls for the month are used; fleet_quota: every self-serve key is paused for the day.'
        resets_at:
          type: string
          format: date-time
          description: When the key works again (ISO-8601 UTC); Retry-After counts down to it.
      required:
      - code
      - reason
      - resets_at
    Problem:
      type: object
      description: RFC 7807 problem details (application/problem+json).
      properties:
        type:
          type: string
          default: about:blank
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
      required:
      - title
      - status
    PrimaryPlayback:
      type: object
      required:
      - kind
      - path
      description: 'The single entry point to treat as "the output": the HLS master playlist (video), the audio file, or the image. `path` matches one entry in outputs[].'
      properties:
        kind:
          type: string
          enum:
          - hls
          - audio
          - image
        path:
          type: string
    JobState:
      type: object
      required:
      - jobId
      - status
      description: 'Job status + manifest. For a SUCCEEDED job whose output is in managed temporary storage, ALSO carries the structured, HLS-aware managed result: primaryPlayback (the labeled entry point), an optional poster, and a complete presigned outputs[] inventory. These managed fields are absent when you supplied your own destination.'
      properties:
        jobId:
          type: string
        status:
          type: string
          enum:
          - QUEUED
          - PROCESSING
          - SUCCEEDED
          - FAILED
        manifest:
          $ref: '#/components/schemas/Manifest'
        error:
          type:
          - string
          - 'null'
        primaryPlayback:
          $ref: '#/components/schemas/PrimaryPlayback'
        poster:
          type: object
          required:
          - path
          additionalProperties: false
          properties:
            path:
              type: string
          description: Video poster frame, if produced (managed jobs only).
        outputs:
          type: array
          items:
            $ref: '#/components/schemas/ManagedOutput'
          description: 'Complete object inventory for a managed job — download ALL of these, preserving relative paths, then re-host. An HLS master URL is NOT directly streamable: its relative segment/variant references are unsigned.'
        storage:
          type: string
          const: managed-temporary
    ManagedOutput:
      type: object
      required:
      - path
      - bytes
      - url
      - urlExpiresAt
      - objectExpiresAt
      description: 'One managed object: a presigned GET plus the two distinct expiries.'
      properties:
        path:
          type: string
          description: Full object key (as it appears in the manifest).
        bytes:
          type: integer
        url:
          type: string
          format: uri
          description: Presigned GET — an individual object URL, NOT a streamable HLS package.
        urlExpiresAt:
          type: string
          format: date-time
          description: When THIS url stops working (~1h). Re-poll GET /v1/jobs/{jobId} for fresh URLs.
        objectExpiresAt:
          type: string
          format: date-time
          description: When the object itself is deleted (~72h). Distinct from urlExpiresAt.
    Manifest:
      description: Shape depends on media type; paths are object keys under destination.prefix.
      oneOf:
      - type: object
        title: VideoManifest
        required:
        - type
        - primary
        - renditions
        properties:
          type:
            type: string
            const: video
          primary:
            type: object
            required:
            - path
            - durationSec
            properties:
              path:
                type: string
                description: HLS master playlist key.
              durationSec:
                type: number
              aspectRatio:
                type: number
          poster:
            type: object
            required:
            - path
            properties:
              path:
                type: string
              aspectRatio:
                type: number
          renditions:
            type: array
            items:
              type: object
              required:
              - height
              - bandwidth
              - path
              properties:
                height:
                  type: integer
                width:
                  type: integer
                bandwidth:
                  type: integer
                path:
                  type: string
      - type: object
        title: AudioManifest
        required:
        - type
        - primary
        properties:
          type:
            type: string
            const: audio
          primary:
            type: object
            required:
            - path
            - durationSec
            properties:
              path:
                type: string
              durationSec:
                type: number
          metadata:
            type:
            - object
            - 'null'
      - type: object
        title: ImageManifest
        required:
        - type
        - primary
        properties:
          type:
            type: string
            const: image
          primary:
            type: object
            required:
            - path
            properties:
              path:
                type: string
              aspectRatio:
                type: number
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Per-product fleet API key (Authorization: Bearer <api key>) — the same key works across MAJR Agent Services.'