majr-app Uploads API

openapi: 3.2.0
info:
  title: media-encoding Uploads 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: Uploads
paths:
  /v1/uploads:
    post:
      operationId: createUpload
      summary: Mint a presigned upload into managed temporary storage (Onramp v1)
      description: Optional managed storage so a caller with no S3 bucket of their own can still encode. Returns a presigned PUT plus the `source` object to hand to POST /v1/encode. PUT your file bytes to upload.url yourself — bytes never transit this API. The whole body is optional; pass {contentType} to have S3 enforce it on the PUT. Managed objects are temporary (~72h lifecycle). 503 when this deployment has no managed scratch configured.
      security:
      - bearerAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadRequest'
      responses:
        '201':
          description: Presigned managed-upload contract.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadContract'
        '401':
          description: Missing or invalid bearer token.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '422':
          description: Request failed validation.
          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'
        '503':
          description: Either managed uploads are not configured in this deployment (a capability-off 503, no Retry-After), or auth is not judgeable yet (cold boot / plane outage — honor Retry-After, never a key-validity verdict).
          headers:
            Retry-After:
              description: Seconds until the auth cache retries a load (auth-retry 503 only).
              schema:
                type: integer
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      tags:
      - Uploads
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
    UploadRequest:
      type: object
      additionalProperties: false
      description: POST /v1/uploads body — all fields optional; an empty body is accepted.
      properties:
        contentType:
          type: string
          minLength: 1
          maxLength: 255
          description: MIME of the file you will PUT. If set, it is signed into the presigned PUT (S3 enforces the Content-Type header on upload) and echoed in upload.headers.
    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
    ObjectRef:
      type: object
      additionalProperties: false
      required:
      - bucket
      - key
      properties:
        bucket:
          type: string
          minLength: 1
        key:
          type: string
          minLength: 1
    UploadContract:
      type: object
      required:
      - uploadId
      - source
      - upload
      - note
      description: 'POST /v1/uploads 201 response: where to PUT, and the source to encode.'
      properties:
        uploadId:
          type: string
        source:
          $ref: '#/components/schemas/ObjectRef'
          description: Pass this as `source` to POST /v1/encode once the PUT succeeds.
        upload:
          type: object
          required:
          - url
          - method
          - headers
          - urlExpiresAt
          properties:
            url:
              type: string
              format: uri
              description: Presigned PUT target.
            method:
              type: string
              const: PUT
            headers:
              type: object
              additionalProperties:
                type: string
              description: Headers you MUST send on the PUT (e.g. Content-Type when signed).
            urlExpiresAt:
              type: string
              format: date-time
              description: When this presigned PUT URL stops working.
        note:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Per-product fleet API key (Authorization: Bearer <api key>) — the same key works across MAJR Agent Services.'