openapi: 3.1.0
info:
  title: AlefBot Public API
  description: Upload media, create transcriptions, track their status, and download
    artifacts. Use a Bearer API key and preserve X-Request-ID values when contacting
    support.
  version: v1
paths:
  /api/v1/keys:
    post:
      tags:
      - Account & keys
      summary: Create an API key
      operationId: createPublicApiKey
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicAPIKeyCreateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIKeyCreateResponse'
          headers:
            X-Request-ID:
              description: Identifier to provide when requesting support.
              schema:
                type: string
        '422':
          description: Request validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '403':
          description: Insufficient scope or plan access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
      description: Create a live or test API key with an explicit access scope.
      security:
      - PublicApiBearer: []
    get:
      tags:
      - Account & keys
      summary: List API keys
      operationId: listPublicApiKeys
      parameters: []
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PublicAPIKeyView'
                title: Response List Public Keys Api V1 Keys Get
          headers:
            X-Request-ID:
              description: Identifier to provide when requesting support.
              schema:
                type: string
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '403':
          description: Insufficient scope or plan access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
      description: List API keys without revealing their secret values.
      security:
      - PublicApiBearer: []
  /api/v1/account:
    get:
      tags:
      - Account & keys
      summary: Get API account status
      operationId: getAccount
      parameters: []
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAccountResponse'
          headers:
            X-Request-ID:
              description: Identifier to provide when requesting support.
              schema:
                type: string
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '403':
          description: Insufficient scope or plan access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
      description: Check plan eligibility, balance, and public API access.
      security:
      - PublicApiBearer: []
  /api/v1/uploads:
    post:
      tags:
      - Uploads
      summary: Create an upload slot
      operationId: createUpload
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        description: Recommended unique key for safely retrying this request.
        schema:
          type: string
          minLength: 1
          maxLength: 200
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicUploadCreateRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicUploadCreateResponse'
          headers:
            X-Request-ID:
              description: Identifier to provide when requesting support.
              schema:
                type: string
            X-RateLimit-Limit:
              description: Requests allowed in the current window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp at which the current window resets.
              schema:
                type: integer
        '422':
          description: Request validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '400':
          description: Malformed request or unsafe target
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '403':
          description: Insufficient scope or plan access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '409':
          description: Resource state or idempotency conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '500':
          description: API processing or storage configuration failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '503':
          description: API coordination dependency unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
      description: Reserve a short-lived location for one media file.
      security:
      - PublicApiBearer: []
  /api/v1/uploads/{upload_id}/binary:
    put:
      tags:
      - Uploads
      summary: Upload media bytes
      operationId: uploadBinary
      parameters:
      - name: upload_id
        in: path
        required: true
        schema:
          type: string
          title: Upload Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicUploadBinaryResponse'
          headers:
            X-Request-ID:
              description: Identifier to provide when requesting support.
              schema:
                type: string
            X-RateLimit-Limit:
              description: Requests allowed in the current window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp at which the current window resets.
              schema:
                type: integer
        '400':
          description: Malformed request or unsafe target
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '403':
          description: Insufficient scope or plan access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '410':
          description: Resource or upload slot expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '500':
          description: API processing or storage configuration failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '503':
          description: API coordination dependency unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
      description: Transfer the exact number of bytes declared for an upload slot.
      security:
      - PublicApiBearer: []
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
  /api/v1/transcriptions:
    post:
      tags:
      - Transcriptions
      summary: Create transcription
      operationId: createTranscription
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        description: Recommended unique key for safely retrying this request.
        schema:
          type: string
          minLength: 1
          maxLength: 200
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicTranscriptionCreateRequest'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicTranscriptionCreateResponse'
          headers:
            X-Request-ID:
              description: Identifier to provide when requesting support.
              schema:
                type: string
            X-RateLimit-Limit:
              description: Requests allowed in the current window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp at which the current window resets.
              schema:
                type: integer
        '422':
          description: Request validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '200':
          description: Test-mode transcription completed synchronously
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicTranscriptionCreateResponse'
          headers:
            X-Request-ID:
              description: Identifier to provide when requesting support.
              schema:
                type: string
            X-RateLimit-Limit:
              description: Requests allowed in the current window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp at which the current window resets.
              schema:
                type: integer
        '400':
          description: Malformed request or unsafe target
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '403':
          description: Insufficient scope or plan access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '409':
          description: Resource state or idempotency conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '410':
          description: Resource or upload slot expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '500':
          description: API processing or storage configuration failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '502':
          description: Upstream storage dependency unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '503':
          description: API coordination dependency unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
      description: Start a transcription from a completed upload. Test keys complete
        synchronously; live keys normally return 202.
      security:
      - PublicApiBearer: []
    get:
      tags:
      - Transcriptions
      summary: List transcriptions
      operationId: listTranscriptions
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 20
          title: Limit
      - name: cursor
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Cursor
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicTranscriptionListResponse'
          headers:
            X-Request-ID:
              description: Identifier to provide when requesting support.
              schema:
                type: string
            X-RateLimit-Limit:
              description: Requests allowed in the current window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp at which the current window resets.
              schema:
                type: integer
        '422':
          description: Request validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '403':
          description: Insufficient scope or plan access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '503':
          description: API coordination dependency unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
      description: Page through transcription jobs owned by the authenticated account.
      security:
      - PublicApiBearer: []
  /api/v1/transcriptions/{job_id}:
    get:
      tags:
      - Transcriptions
      summary: Get transcription status
      operationId: getTranscription
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: if-none-match
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: If-None-Match
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicTranscriptionResponse'
          headers:
            X-Request-ID:
              description: Identifier to provide when requesting support.
              schema:
                type: string
            X-RateLimit-Limit:
              description: Requests allowed in the current window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp at which the current window resets.
              schema:
                type: integer
            ETag:
              description: Opaque version identifier for conditional requests.
              schema:
                type: string
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '403':
          description: Insufficient scope or plan access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '503':
          description: API coordination dependency unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '304':
          description: Not modified
          headers:
            X-Request-ID:
              description: Identifier to provide when requesting support.
              schema:
                type: string
            ETag:
              description: Current opaque version identifier.
              schema:
                type: string
            X-RateLimit-Limit:
              description: Requests allowed in the current window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp at which the current window resets.
              schema:
                type: integer
      description: Read the latest job state, analysis, usage, and artifact link.
      security:
      - PublicApiBearer: []
  /api/v1/transcriptions/{job_id}/artifact:
    get:
      tags:
      - Transcriptions
      summary: Download a transcription artifact
      operationId: getTranscriptionArtifact
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: format
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Format
      - name: accept
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          default: text/plain
          title: Accept
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
          headers:
            X-Request-ID:
              description: Identifier to provide when requesting support.
              schema:
                type: string
        '400':
          description: Malformed request or unsafe target
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '403':
          description: Insufficient scope or plan access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '409':
          description: Resource state or idempotency conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '500':
          description: API processing or storage configuration failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
      description: Download the completed transcript in the requested representation.
      security:
      - PublicApiBearer: []
  /api/v1/transcriptions/{job_id}/artifact.{path_format}:
    get:
      tags:
      - Transcriptions
      summary: Download an artifact by extension
      operationId: getTranscriptionArtifactByExtension
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: path_format
        in: path
        required: true
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Path Format
      - name: format
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Format
      - name: accept
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          default: text/plain
          title: Accept
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
          headers:
            X-Request-ID:
              description: Identifier to provide when requesting support.
              schema:
                type: string
        '400':
          description: Malformed request or unsafe target
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '403':
          description: Insufficient scope or plan access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '409':
          description: Resource state or idempotency conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '500':
          description: API processing or storage configuration failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
      description: Download a completed transcript using a filename-style format suffix.
      security:
      - PublicApiBearer: []
  /api/v1/webhooks/test:
    post:
      tags:
      - Webhooks
      summary: Send a test webhook
      operationId: testWebhook
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicWebhookTestRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicWebhookTestResponse'
          headers:
            X-Request-ID:
              description: Identifier to provide when requesting support.
              schema:
                type: string
        '422':
          description: Request validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '400':
          description: Malformed request or unsafe target
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
        '403':
          description: Insufficient scope or plan access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAPIErrorEnvelope'
      description: Send a signed test event to a public HTTPS endpoint.
      security:
      - PublicApiBearer: []
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PublicAPIKeyCreateRequest:
      properties:
        name:
          type: string
          title: Name
          description: Human-readable key name.
          examples:
          - CI key
        scope:
          type: string
          enum:
          - full_access
          - read_only
          title: Scope
          description: Whether the key can create resources or only read them.
          default: full_access
          examples:
          - full_access
        mode:
          type: string
          enum:
          - live
          - test
          title: Mode
          description: Live keys process media; test keys return deterministic mock
            results.
          default: live
          examples:
          - test
      type: object
      required:
      - name
      title: PublicAPIKeyCreateRequest
    PublicAPIKeyCreateResponse:
      properties:
        key:
          type: string
          title: Key
          description: Secret API key. It is returned once and must be stored securely.
          examples:
          - alef_sk_test_...
        item:
          $ref: '#/components/schemas/PublicAPIKeyView'
          description: Persisted key metadata.
      type: object
      required:
      - key
      - item
      title: PublicAPIKeyCreateResponse
    PublicAPIKeyView:
      properties:
        id:
          type: string
          title: Id
          description: Stable API key identifier.
        name:
          type: string
          title: Name
          description: Human-readable key name.
        scope:
          type: string
          title: Scope
          description: Granted access scope.
          examples:
          - full_access
        mode:
          type: string
          title: Mode
          description: Key environment.
          examples:
          - live
        last_four_chars:
          type: string
          title: Last Four Chars
          description: Last four characters for identification.
        is_valid:
          type: boolean
          title: Is Valid
          description: Whether the key can still authenticate.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: UTC creation timestamp.
      type: object
      required:
      - id
      - name
      - scope
      - mode
      - last_four_chars
      - is_valid
      - created_at
      title: PublicAPIKeyView
    PublicAccountResponse:
      properties:
        account_id:
          type: string
          title: Account Id
          description: Authenticated AlefBot account ID.
          examples:
          - user_123
        effective_tier:
          type: string
          title: Effective Tier
          description: Plan used for API eligibility and limits.
          examples:
          - premium
        api_access:
          type: boolean
          title: Api Access
          description: Whether the plan currently permits API use.
          examples:
          - true
        wallet_balance:
          type: number
          title: Wallet Balance
          description: Available AlefBot credit balance.
          examples:
          - 1450.5
        status:
          type: string
          title: Status
          description: Account status.
          examples:
          - active
      type: object
      required:
      - account_id
      - effective_tier
      - api_access
      - wallet_balance
      - status
      title: PublicAccountResponse
    PublicTranscriptionAnalysis:
      properties:
        language:
          anyOf:
          - type: string
          - type: 'null'
          title: Language
          description: Detected primary language.
        dialect:
          anyOf:
          - type: string
          - type: 'null'
          title: Dialect
          description: Detected dialect when available.
      type: object
      title: PublicTranscriptionAnalysis
    PublicTranscriptionCreateLinks:
      properties:
        self:
          type: string
          title: Self
          description: Canonical status URL for this job.
      type: object
      required:
      - self
      title: PublicTranscriptionCreateLinks
    PublicTranscriptionCreateRequest:
      properties:
        upload_id:
          type: string
          title: Upload Id
          description: ID returned by the upload-slot operation.
          examples:
          - upl_01J...
        translate_to_hebrew:
          type: boolean
          title: Translate To Hebrew
          description: Translate non-Hebrew speech into Hebrew.
          default: false
          examples:
          - false
        model_tier:
          anyOf:
          - type: string
            enum:
            - standard
            - fast_low_cost
            - premium_quality
          - type: 'null'
          title: Model Tier
          description: Quality, speed, and cost profile for the transcription model.
          default: standard
          examples:
          - standard
          - fast_low_cost
          - premium_quality
        user_prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: User Prompt
          description: Optional vocabulary or transcription guidance.
          examples:
          - Preserve legal terminology
        output_format:
          type: string
          enum:
          - srt
          - plain_text
          title: Output Format
          description: Default downloadable artifact format.
          default: srt
          examples:
          - srt
        webhook_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Webhook Url
          description: Public HTTPS URL for signed completion events.
          examples:
          - https://client.example.com/webhooks/alefbot
      additionalProperties: false
      type: object
      required:
      - upload_id
      title: PublicTranscriptionCreateRequest
    PublicTranscriptionCreateResponse:
      properties:
        job_id:
          type: string
          title: Job Id
          description: Transcription job identifier.
          examples:
          - job_01J...
        status:
          type: string
          title: Status
          description: Initial job state.
          examples:
          - queued
        links:
          $ref: '#/components/schemas/PublicTranscriptionCreateLinks'
          description: Follow-up resource links.
      type: object
      required:
      - job_id
      - status
      - links
      title: PublicTranscriptionCreateResponse
    PublicTranscriptionLinks:
      properties:
        self:
          type: string
          title: Self
          description: Canonical status URL for this job.
        artifact:
          type: string
          title: Artifact
          description: Default completed-artifact URL.
      type: object
      required:
      - self
      - artifact
      title: PublicTranscriptionLinks
    PublicTranscriptionListResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/PublicTranscriptionResponse'
          type: array
          title: Items
          description: Jobs in the current page.
        total:
          type: integer
          minimum: 0.0
          title: Total
          description: Total matching jobs.
        links:
          additionalProperties:
            anyOf:
            - type: string
            - type: 'null'
          type: object
          title: Links
          description: Pagination links.
      type: object
      required:
      - items
      - total
      - links
      title: PublicTranscriptionListResponse
    PublicTranscriptionResponse:
      properties:
        job_id:
          type: string
          title: Job Id
          description: Transcription job identifier.
        status:
          type: string
          title: Status
          description: Current normalized job state.
          examples:
          - completed
        created_at:
          type: string
          format: date-time
          title: Created At
          description: UTC creation timestamp.
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: UTC timestamp of the latest state change.
        media_duration_seconds:
          anyOf:
          - type: number
          - type: 'null'
          title: Media Duration Seconds
          description: Processed media duration in seconds.
        credits_used:
          anyOf:
          - type: number
          - type: 'null'
          title: Credits Used
          description: Credits charged after processing.
        analysis:
          $ref: '#/components/schemas/PublicTranscriptionAnalysis'
          description: Detected media attributes.
        links:
          $ref: '#/components/schemas/PublicTranscriptionLinks'
          description: Related API resources.
      type: object
      required:
      - job_id
      - status
      - created_at
      - updated_at
      - analysis
      - links
      title: PublicTranscriptionResponse
    PublicUploadBinaryResponse:
      properties:
        ok:
          type: boolean
          title: Ok
          description: Whether all declared bytes were stored.
          examples:
          - true
        bytes_received:
          type: integer
          minimum: 0.0
          title: Bytes Received
          description: Number of media bytes stored.
          examples:
          - 10485760
      type: object
      required:
      - ok
      - bytes_received
      title: PublicUploadBinaryResponse
    PublicUploadCreateRequest:
      properties:
        filename:
          type: string
          title: Filename
          description: Original media filename including extension.
          examples:
          - lecture.mp3
        content_type:
          type: string
          title: Content Type
          description: Media MIME type.
          examples:
          - audio/mpeg
        size_bytes:
          type: integer
          exclusiveMinimum: 0.0
          title: Size Bytes
          description: Exact byte length of the file to upload.
          examples:
          - 10485760
      type: object
      required:
      - filename
      - content_type
      - size_bytes
      title: PublicUploadCreateRequest
    PublicUploadCreateResponse:
      properties:
        upload_id:
          type: string
          title: Upload Id
          description: Upload slot identifier.
          examples:
          - upl_01J...
        upload_url:
          type: string
          title: Upload Url
          description: URL that receives the media bytes.
        upload_method:
          type: string
          title: Upload Method
          description: HTTP method required by the upload URL.
          examples:
          - PUT
        expires_at:
          type: string
          format: date-time
          title: Expires At
          description: UTC time after which the upload slot expires.
      type: object
      required:
      - upload_id
      - upload_url
      - upload_method
      - expires_at
      title: PublicUploadCreateResponse
    PublicWebhookTestRequest:
      properties:
        webhook_url:
          type: string
          title: Webhook Url
          description: Public HTTPS endpoint to receive the test event.
          examples:
          - https://client.example.com/webhooks/alefbot
        event_type:
          type: string
          title: Event Type
          description: Event type placed in the signed payload.
          default: transcription.completed
          examples:
          - transcription.completed
      type: object
      required:
      - webhook_url
      title: PublicWebhookTestRequest
    PublicWebhookTestResponse:
      properties:
        ok:
          type: boolean
          title: Ok
          description: Whether the test operation completed.
        event_id:
          type: string
          title: Event Id
          description: Generated test event identifier.
        delivered:
          type: boolean
          title: Delivered
          description: Whether the target accepted the event.
        status_code:
          anyOf:
          - type: integer
          - type: 'null'
          title: Status Code
          description: HTTP status returned by the target.
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Sanitized delivery failure reason.
      type: object
      required:
      - ok
      - event_id
      - delivered
      title: PublicWebhookTestResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    PublicAPIErrorEnvelope:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - request_id
          - details
          properties:
            code:
              type: string
              examples:
              - validation_error
            message:
              type: string
              examples:
              - validation error
            request_id:
              type:
              - string
              - 'null'
              examples:
              - req_01J...
            details:
              type: object
              additionalProperties: true
              properties:
                resolution_url:
                  type: string
                  format: uri
  securitySchemes:
    PublicApiBearer:
      type: http
      scheme: bearer
      bearerFormat: AlefBot API key
      description: 'Use `Authorization: Bearer alef_sk_...`.'
servers:
- url: https://alef-bot.top
  description: Production
tags:
- name: Account & keys
  description: Inspect account access and manage scoped API keys.
- name: Uploads
  description: Reserve an upload slot and transfer media securely.
- name: Transcriptions
  description: Create, track, list, and download transcription jobs.
- name: Webhooks
  description: Validate webhook delivery before using it in production.
externalDocs:
  description: AlefBot Developer Hub
  url: https://alef-bot.top/developers
