audivo-dev Session API

openapi: 3.2.0
info:
  title: Audivo Session API
  version: 0.16.0
  description: 'The Audivo API turns a public podcast episode into a clean, timed transcript. Name an episode by an Apple Podcasts link, by its RSS feed URL and GUID, by the episode id an earlier answer gave you, or by an upload of audio you hold; get back structured, timed text — at once for an episode already transcribed, or as a job you poll for fresh audio. One call does it: `POST /v1/transcripts`. Quotes are for pricing a selection of many episodes before confirming it.


    Two authentication schemes, and which an operation takes is part of what it is: `apiKeyBearer` — an `hk_live_` key sent as `Authorization: Bearer` — authenticates the public API, and `dashboardJwt` authenticates the dashboard''s own operations. No operation that takes one accepts the other in its place. An API-key caller reads its balance and reservations from any quote response.


    The hosted MCP server at `/mcp` and the OAuth 2.1 endpoints that connect an assistant to it — `/.well-known/oauth-protected-resource`, `/.well-known/oauth-authorization-server`, and `/oauth/authorize`, `/oauth/token`, `/oauth/register`, `/oauth/revoke` — are protocol transports on the same host, not contract operations: an MCP client discovers and describes them from those two metadata documents (RFC 9728, RFC 8414), and they are documented with the MCP server. Their access tokens are checked by the same authorizer as an API key and metered by the same plan; the consent they need is two dashboard operations below, under **Connected Apps**.


    Deferred on purpose, and absent from this document rather than hidden: webhooks, subscriptions, speaker labels beyond the frozen `diarized: false` shape, custom vocabulary, caller-selected engines, raw-audio URLs, SDKs, translation, and cross-corpus search. What changed in each version is on the documentation site''s changelog.'
  license:
    name: Proprietary
    url: https://docs.audivo.dev/legal/terms
servers:
- url: https://api.audivo.dev
  description: Production API. Append the operation path, including /v1.
tags:
- name: Session
  description: Dashboard-JWT session establishment. One operation, called by the dashboard's backend-for-frontend whenever it turns a Cognito sign-in into a Audivo session, and the one place a caller who does not yet have an account is served.
paths:
  /v1/session:
    post:
      operationId: establishSession
      tags:
      - Session
      summary: Establish the signed-in user's Audivo session
      security:
      - dashboardJwt: []
      description: 'Resolves the access token''s Cognito subject to a Audivo account, creating the account and its one free credit grant if no row exists yet, and answers with the identity a session then carries.


        **Idempotent by construction, not by convention.** The account id is derived from the Cognito subject, so calling this once, twice, or concurrently converges on the same account; a second call issues no second free grant, and neither does signing up again with an address that has already had one. Callers are expected to call it on *every* session establishment rather than only on first sign-in — it is the repair path for a signup whose account row was never written, and a caller that only called it once would never take it.


        It takes no request body. Everything it acts on comes from the verified token, so there is nothing a caller can send that changes which account it resolves — including the address the one-free-grant check is keyed on, which is read from the identity provider and never from the request.


        A non-`active` account is returned with its status rather than being replaced or refused: a suspended customer needs the billing page that lifts the hold, and answering `401` would take it away.'
      responses:
        '200':
          description: The account this session acts for.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionResponse'
              examples:
                session:
                  $ref: '#/components/examples/SessionExample'
        '401':
          $ref: '#/components/responses/UnauthorizedDashboard'
        '429':
          $ref: '#/components/responses/TooManyRequestsDashboard'
        '500':
          $ref: '#/components/responses/InternalErrorDashboard'
components:
  responses:
    UnauthorizedDashboard:
      description: 'Code `unauthenticated` — the Cognito JWT is missing, malformed, expired, or was rejected. An API key presented to one of the operations that declare this response lands here too: they take a session and nothing else, and that is an authentication failure, not an authorization one. That includes `GET /v1/usage` and `GET /v1/limits`, which are served by the control-plane API alone.'
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequestsDashboard:
      description: Code `rate_limited`, e.g. plan-change rate limiting.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalErrorDashboard:
      description: 'Code `internal_error` — a call on our side failed and nothing was changed. On `POST /v1/session` this is what an unreachable identity service or an unreadable configuration answers with, deliberately rather than `401`: the session is not the problem, and telling a signed-in customer their token is bad during an outage of ours sends them into a sign-in loop. Retryable; `request_id` is what identifies it in our logs.'
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  headers:
    XRequestId:
      description: Echoed on every response, success or error. A refusal generated at the edge (401, 429, and the unmetered-key 500) carries API Gateway's own hyphenated request id after the `req_` prefix; a response from a function carries the same id without hyphens.
      schema:
        type: string
        pattern: ^req_[A-Za-z0-9-]+$
        maxLength: 100
    RetryAfter:
      description: Seconds to wait before retrying. Sent with the edge's `rate_limited` throttle refusal. Not sent with `concurrency_limited`, which clears when one of the account's own jobs reaches a terminal state — a moment the API cannot put a number on.
      schema:
        type: integer
        minimum: 0
  schemas:
    RequestId:
      type: string
      pattern: ^req_[A-Za-z0-9-]+$
      maxLength: 100
    ErrorType:
      type: string
      enum:
      - invalid_request
      - unprocessable_input
      - unauthenticated
      - conflict
      - not_found
      - content_blocked
      - payment_required
      - rate_limited
      - unavailable
      description: 'The family an error belongs to, for handling; `code` is the precise reason. `invalid_request`: something in the request is wrong — fix the integration. `unprocessable_input`: the request is well-formed but the episode or resource is outside published support. `unauthenticated`: missing, malformed, revoked or expired credential. `payment_required`: the account''s credits cannot cover the ceiling. `conflict`: the resource''s or the account''s state refuses this request as sent — a lapsed quote, a reused idempotency key, a held account. `not_found`: the job, quote, group or key the request named does not exist for this account. `rate_limited`: over a plan limit; wait and retry. `unavailable`: a failure on our side or at a provider; retry, and quote `request_id` if it persists.'
    ErrorCode:
      type: string
      enum:
      - invalid_request
      - invalid_url
      - unauthenticated
      - idempotency_conflict
      - job_not_completed
      - source_not_supported
      - feed_dead
      - episode_not_found
      - show_not_found
      - unsafe_source
      - unsupported_codec
      - unsupported_language
      - duration_exceeded
      - size_exceeded
      - content_blocked
      - payment_required
      - rate_limited
      - concurrency_limited
      - job_not_found
      - api_key_not_found
      - api_key_limit_reached
      - credit_lot_not_found
      - credits_not_refundable
      - engine_unavailable
      - processing_failed
      - discovery_unavailable
      - nothing_to_quote
      - internal_error
      - quote_not_found
      - group_not_found
      - quote_expired
      - quote_mismatch
      - quote_unverified
      - expected_total_mismatch
      - request_in_progress
      - account_suspended
      - account_closed
      - account_not_found
      - tier_unchanged
      - upload_quota_exceeded
      - upload_not_found
      - upload_not_received
      - upload_mismatch
      - max_credits_exceeded
      - oauth_request_not_found
      - connected_app_not_found
      description: Every code the API returns, and the HTTP status it comes with. `invalid_request`, `invalid_url` → 400. `unauthenticated` → 401. `payment_required` → 402. `job_not_found`, `quote_not_found`, `group_not_found`, `api_key_not_found`, `credit_lot_not_found`, `upload_not_found`, `oauth_request_not_found`, `connected_app_not_found` → 404. `idempotency_conflict`, `request_in_progress`, `job_not_completed`, `quote_expired`, `quote_mismatch`, `quote_unverified`, `expected_total_mismatch`, `account_suspended`, `account_closed`, `account_not_found`, `api_key_limit_reached`, `tier_unchanged`, `upload_not_received` → 409; `upload_not_received` is retryable once the file's PUT has landed. `source_not_supported`, `feed_dead`, `episode_not_found`, `show_not_found`, `unsafe_source`, `unsupported_codec`, `unsupported_language`, `duration_exceeded`, `size_exceeded`, `nothing_to_quote`, `credits_not_refundable`, `upload_mismatch`, `max_credits_exceeded` → 422. `content_blocked` → 451. `rate_limited`, `concurrency_limited`, `upload_quota_exceeded` → 429; `upload_quota_exceeded` is retryable, at the earliest capacity return time its message names. `internal_error`, `processing_failed` → 500. `discovery_unavailable`, `engine_unavailable` → 503. `processing_failed` also appears inside a failed job's `error` field rather than as a live status. Each code has a heading on the documentation site's errors page, which is what `doc_url` links to.
    Error:
      type: object
      additionalProperties: false
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
    AccountStatus:
      type: string
      enum:
      - active
      - suspended
      - deleting
      - deleted
      description: 'The account''s own state. `active` is the only one that may spend: `suspended` is a billing or abuse hold, and `deleting`/`deleted` are a deletion in progress or complete. Reads stay open in every state until the account''s API keys are revoked, which is when access actually ends — so a non-`active` status is a reason to show the customer their billing page, not a reason to sign them out.'
    AccountId:
      type: string
      pattern: ^acct_[A-Za-z0-9_-]{1,150}$
      maxLength: 155
      description: The calling account's opaque identifier. Self-serve accounts derive it from the Cognito subject, so it is stable for the life of the account and identical however the account was created; operator-provisioned accounts predate that and carry arbitrary names within the same shape. Callers must not parse it or infer anything from its body.
    ErrorDetail:
      type: object
      additionalProperties: false
      required:
      - type
      - code
      - message
      - doc_url
      - request_id
      - retryable
      properties:
        type:
          $ref: '#/components/schemas/ErrorType'
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
          minLength: 1
          maxLength: 1000
        doc_url:
          type: string
          format: uri
          maxLength: 300
        request_id:
          $ref: '#/components/schemas/RequestId'
        retryable:
          type: boolean
      oneOf:
      - required:
        - code
        - type
        properties:
          code:
            enum:
            - invalid_request
            - invalid_url
            - source_not_supported
            - unsafe_source
          type:
            const: invalid_request
      - required:
        - code
        - type
        properties:
          code:
            enum:
            - duration_exceeded
            - size_exceeded
            - unsupported_codec
            - unsupported_language
            - credits_not_refundable
            - upload_mismatch
            - max_credits_exceeded
          type:
            const: unprocessable_input
      - required:
        - code
        - type
        properties:
          code:
            const: unauthenticated
          type:
            const: unauthenticated
      - required:
        - code
        - type
        properties:
          code:
            enum:
            - idempotency_conflict
            - job_not_completed
            - quote_expired
            - quote_mismatch
            - quote_unverified
            - expected_total_mismatch
            - request_in_progress
            - account_suspended
            - account_closed
            - account_not_found
            - api_key_limit_reached
            - tier_unchanged
            - upload_not_received
          type:
            const: conflict
      - required:
        - code
        - type
        properties:
          code:
            enum:
            - feed_dead
            - episode_not_found
            - show_not_found
            - job_not_found
            - quote_not_found
            - group_not_found
            - api_key_not_found
            - credit_lot_not_found
            - upload_not_found
            - oauth_request_not_found
            - connected_app_not_found
          type:
            const: not_found
      - required:
        - code
        - type
        properties:
          code:
            const: content_blocked
          type:
            const: content_blocked
      - required:
        - code
        - type
        properties:
          code:
            const: payment_required
          type:
            const: payment_required
      - required:
        - code
        - type
        properties:
          code:
            enum:
            - rate_limited
            - concurrency_limited
            - upload_quota_exceeded
          type:
            const: rate_limited
      - required:
        - code
        - type
        properties:
          code:
            enum:
            - engine_unavailable
            - processing_failed
            - discovery_unavailable
            - internal_error
          type:
            const: unavailable
      - required:
        - code
        - type
        properties:
          code:
            const: nothing_to_quote
          type:
            const: unprocessable_input
    Tier:
      type: string
      enum:
      - free
      - hobby
      - startup
      - growth
      - scale
    SessionResponse:
      type: object
      additionalProperties: false
      required:
      - account_id
      - tier
      - status
      description: 'What one session carries. Deliberately no balance and no credit figure: a number frozen into a session outlives itself, and `GET /v1/usage` reads the live one.'
      properties:
        account_id:
          $ref: '#/components/schemas/AccountId'
        tier:
          $ref: '#/components/schemas/Tier'
        status:
          $ref: '#/components/schemas/AccountStatus'
  examples:
    SessionExample:
      summary: A newly repaired free-tier session
      value:
        account_id: acct_vuzw6ultz2hdteke
        tier: free
        status: active
  securitySchemes:
    apiKeyBearer:
      type: http
      scheme: bearer
      bearerFormat: hk_live_... or hk_test_...
      description: '`Authorization: Bearer hk_live_...` for live keys or `Authorization: Bearer hk_test_...` for test-mode keys. `hk_test_` keys resolve real public catalog metadata but return deterministic committed fixtures, never call inference, and never mutate live credits. This is the *only* transport for the credential: the `x-api-key` alias once documented was removed in 0.2.0, because the edge authorizer reads `Authorization` as its single identity source and a request on any other header is refused before it is authenticated.


        Never accepted on a `dashboardJwt` operation, and there are no exceptions. `GET /v1/usage` and `GET /v1/limits` briefly declared both schemes (0.8.0); that was withdrawn in 0.8.1 because no deployed route could honor it — both operations are served by the control-plane API, whose authorizer verifies a Cognito token and refuses an `hk_live_` credential on shape, and the customer API does not route either path. An API-key holder reads its balance and reservation from `QuoteResponse`, which carries `balance_credits` and `reserved_credits` on every quote. Every operation in this document takes one scheme or the other and refuses the wrong one as `unauthenticated`.'
    dashboardJwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'A Cognito access token, issued through the dashboard''s own sign-up and sign-in pages (a backend-for-frontend; there is no Cognito Hosted UI) and sent as `Authorization: Bearer <jwt>`. Dashboard operations require this scheme and cannot be called with an API key, with no exception. `GET /v1/usage` and `GET /v1/limits` offered both schemes from 0.8.0; 0.8.1 withdrew that, because the control-plane API serves them alone and its authorizer has no API-key branch. An `account_id` supplied by the client is ignored; all reads/writes are scoped server-side to the authenticated account.'