AudioMap Content API

openapi: 3.2.0
info:
  title: AudioMap Content API
  version: 1.0.0
  description: 'Transcribe audio and video, then read, analyse and query it programmatically.


    Authentication: send an API key as `Authorization: Bearer am_live_...`.

    Create one at https://audiomap.ai/dashboard/api-keys. The key is shown once.

    A session JWT is NOT accepted here; only API keys.


    Plan: the REST API is included from the Pro plan up. Calls from a lower plan

    answer 403 `tier_upgrade_required` with the plan you need in `requiredTier`.


    Credits: writing operations spend monthly credits from the same balance as the

    MCP server. If an operation fails after being charged, the credits are refunded.

    Read `GET /v1/openapi.json` `x-audiomap-credits` for the current prices.


    There is also an MCP server at POST /mcp/stream with the same capabilities,

    for clients that speak Model Context Protocol. See GET /mcp/info.'
  contact:
    name: AudioMap
    url: https://audiomap.ai/developers
servers:
- url: https://api.audiomap.ai
security:
- apiKey: []
tags:
- name: Content
  description: Transcript, analysis and outline of a note
paths:
  /v1/notes/{id}/transcript:
    get:
      tags:
      - Content
      operationId: getTranscript
      summary: Transcript with segments, speakers and word timings
      description: '`format=json` (default) returns structured segments with per-word timings when the provider emits them. The other formats are the same exporters the web app uses and come back as text with their own content type.'
      parameters:
      - $ref: '#/components/parameters/NoteId'
      - name: format
        in: query
        schema:
          type: string
          enum:
          - json
          - txt
          - srt
          - vtt
          - md
          default: json
      - name: translation
        in: query
        description: Include an already generated translation in this language. In json every segment gets `translation`; in text formats see `translationMode`.
        schema:
          type: string
          enum:
          - es
          - en
          - de
          - fr
          - it
          - pt
      - name: translationMode
        in: query
        description: '`translation`: the transcript comes out translated. `both`: original with its translation under every segment.'
        schema:
          type: string
          enum:
          - translation
          - both
          default: both
      responses:
        '200':
          description: The transcript
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transcript'
            text/plain:
              schema:
                type: string
            text/markdown:
              schema:
                type: string
            application/x-subrip:
              schema:
                type: string
            text/vtt:
              schema:
                type: string
        '400':
          description: Unknown format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: invalid_format
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: Not enough credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: insufficient_credits
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Note not found, or it has no transcript yet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: no_transcript
        '429':
          $ref: '#/components/responses/RateLimited'
  /v1/notes/{id}/transcript/translation:
    get:
      tags:
      - Content
      operationId: getTranscriptTranslation
      summary: State and segments of the transcript translation
      description: Segment-aligned translation (same `sequence` as the transcript). `status` is none, pending, running, ready or failed; `stale` means the transcript changed after translating and some segments are missing again. Free.
      parameters:
      - $ref: '#/components/parameters/NoteId'
      - name: language
        in: query
        description: Target language; defaults to the user language.
        schema:
          type: string
          enum:
          - es
          - en
          - de
          - fr
          - it
          - pt
      responses:
        '200':
          description: The translation state
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Unknown language
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: invalid_language
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Note not found, or it has no transcript yet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: no_transcript
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      tags:
      - Content
      operationId: translateTranscript
      summary: Translate the transcript into a language
      description: Queues the translation and returns 202 with its progress (poll the GET), or 200 if it is already done. Costs 0 credits the first time per note and language; completing or repeating it is free. The analysis (AI notes, outline) is already written in the user language.
      parameters:
      - $ref: '#/components/parameters/NoteId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                language:
                  type: string
                  enum:
                  - es
                  - en
                  - de
                  - fr
                  - it
                  - pt
      responses:
        '200':
          description: Already translated
          content:
            application/json:
              schema:
                type: object
        '202':
          description: Queued or running
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: Not enough credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: insufficient_credits
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Note not found, or it has no transcript yet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: no_transcript
        '409':
          description: The audio is already in that language
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: same_language
        '429':
          $ref: '#/components/responses/RateLimited'
  /v1/notes/{id}/analysis:
    get:
      tags:
      - Content
      operationId: getAnalysis
      summary: Read the generated analyses of a note
      description: 'Every element carries its anchor: `anchors.keyPoints[i]` is the millisecond at which `keyPoints[i]` is said, or null when the model could not place it.'
      parameters:
      - $ref: '#/components/parameters/NoteId'
      - name: template
        in: query
        schema:
          type: string
          enum:
          - generic
          - sales
          - legal
          - medical
          - journalism
          - education
          - customer_success
          - meeting_minutes
          - consulting
          - coaching
          - therapy
          - podcast
          - university_class
          - debate
      responses:
        '200':
          description: The analyses persisted for this note
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalysisList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Note not found, or that template has not been generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: analysis_not_generated
                template: sales
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      tags:
      - Content
      operationId: generateAnalysis
      summary: Generate or regenerate an analysis template
      parameters:
      - $ref: '#/components/parameters/NoteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                template:
                  type: string
                  enum:
                  - generic
                  - sales
                  - legal
                  - medical
                  - journalism
                  - education
                  - customer_success
                  - meeting_minutes
                  - consulting
                  - coaching
                  - therapy
                  - podcast
                  - university_class
                  - debate
                templates:
                  type: array
                  minItems: 1
                  maxItems: 8
                  items:
                    type: string
                    enum:
                    - generic
                    - sales
                    - legal
                    - medical
                    - journalism
                    - education
                    - customer_success
                    - meeting_minutes
                    - consulting
                    - coaching
                    - therapy
                    - podcast
                    - university_class
                    - debate
      responses:
        '200':
          description: Generated; `report` lists which templates failed, if any
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalysisList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: Not enough credits, or the template needs a paid plan
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: upgrade_required
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: The note is not ready, or has no transcript
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: note_not_ready
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          description: Every requested template failed; credits were refunded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: llm_invalid_json
  /v1/notes/{id}/outline:
    get:
      tags:
      - Content
      operationId: getOutline
      summary: Chapters of the note with timestamps
      description: Reading is free. `?generate=1` on a note that has no outline generates one and charges credits.
      parameters:
      - $ref: '#/components/parameters/NoteId'
      - name: generate
        in: query
        schema:
          type: string
          enum:
          - '0'
          - '1'
      responses:
        '200':
          description: The outline; empty array when there is none
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Outline'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: Not enough credits to generate it
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: insufficient_credits
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: The note is not ready
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: note_not_ready
        '429':
          $ref: '#/components/responses/RateLimited'
  /v1/notes/{id}/speakers:
    get:
      tags:
      - Content
      operationId: getSpeakers
      summary: Speakers of the note with their names
      description: '`name` is the name in use: the one the user gave, or one inferred from what is said and from the source when its confidence is high enough (`nameStatus: suggested`). `suggestedName`, `suggestedNameConfidence` and `evidence` show the inference even when it is below that threshold. Free.'
      parameters:
      - $ref: '#/components/parameters/NoteId'
      responses:
        '200':
          description: The speakers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpeakerList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v1/notes/{id}/speakers/suggest:
    post:
      tags:
      - Content
      operationId: suggestSpeakerNames
      summary: Infer the speaker names from content and metadata
      description: Reads who addresses whom ("Euge, ¿tú cómo lo ves?"), self-introductions, the title, the channel or show and the people the user already confirmed on that source. No voice analysis. Never overwrites a name the user gave. Free; 10 per hour.
      parameters:
      - $ref: '#/components/parameters/NoteId'
      responses:
        '200':
          description: The speakers after the inference
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpeakerList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: The note is not ready
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: note_not_ready
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          description: The inference failed; nothing changed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: speaker_naming_failed
  /v1/notes/{id}/speakers/{label}:
    patch:
      tags:
      - Content
      operationId: renameSpeaker
      summary: Name a speaker, or confirm its suggested name
      description: The name is used in the transcript, the timeline and the exports, and remembered for the next notes of the same channel or podcast. Free.
      parameters:
      - $ref: '#/components/parameters/NoteId'
      - name: label
        in: path
        required: true
        schema:
          type: string
        description: A, B, C… as the diarizer assigned them
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 120
      responses:
        '200':
          description: The speakers after the change
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpeakerList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v1/voice-profiles:
    get:
      tags:
      - Content
      operationId: listVoiceProfiles
      summary: Voice profiles of the user and the state of the biometric consent
      description: People recognised by voice across the user's OWN recordings, only with the explicit biometric consent the person gives in the app or the web (an API key cannot grant it). Never returns the voice vectors. With consent, a voice that sounds like a profile appears as a suggested speaker name with `voice` evidence. Free.
      responses:
        '200':
          description: Consent state and profiles
          content:
            application/json:
              schema:
                type: object
                properties:
                  consent:
                    type: object
                    properties:
                      status:
                        type: string
                        enum:
                        - granted
                        - revoked
                        - never
                        - outdated
                        description: '`outdated`: granted under an older consent text; it must be accepted again in the app or the web and nothing is analysed meanwhile'
                      grantedAt:
                        type:
                        - string
                        - 'null'
                        format: date-time
                      revokedAt:
                        type:
                        - string
                        - 'null'
                        format: date-time
                  profiles:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        name:
                          type: string
                        confirmedAppearances:
                          type: integer
                        voiceSeconds:
                          type: number
                        hasVoiceprint:
                          type: boolean
                        voiceExcluded:
                          type: boolean
                          description: 'The owner chose "do not recognise this person": the profile keeps only its name and is never analysed nor matched'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    Chapter:
      type: object
      properties:
        startMs:
          type: integer
        endMs:
          type: integer
        headline:
          type: string
    Analysis:
      type: object
      properties:
        template:
          type: string
          enum:
          - generic
          - sales
          - legal
          - medical
          - journalism
          - education
          - customer_success
          - meeting_minutes
          - consulting
          - coaching
          - therapy
          - podcast
          - university_class
          - debate
        summary:
          type: string
        keyPoints:
          type: array
          items:
            type: string
        actionItems:
          type: array
          items:
            type: object
            properties:
              text:
                type: string
              assignee:
                type: string
              deadline:
                type: string
        decisions:
          type: array
          items:
            type: string
        questions:
          type: array
          items:
            type: string
        topics:
          type: array
          items:
            type: string
        anchors:
          $ref: '#/components/schemas/Anchors'
        sections:
          type:
          - object
          - 'null'
          description: Template-specific sections, only for the "debate" template (podcasts, interviews, multi-person debates). Each item carries who says it (speaker name or diarization letter) and the exact start millisecond of the transcript segment where it is said. Null for other templates.
          properties:
            positions:
              type: array
              items:
                type: object
                properties:
                  text:
                    type: string
                  speaker:
                    type:
                    - string
                    - 'null'
                  t:
                    type:
                    - integer
                    - 'null'
                required:
                - text
            arguments:
              type: array
              items:
                type: object
                properties:
                  text:
                    type: string
                  speaker:
                    type:
                    - string
                    - 'null'
                  t:
                    type:
                    - integer
                    - 'null'
                required:
                - text
            quotes:
              type: array
              items:
                type: object
                properties:
                  text:
                    type: string
                  speaker:
                    type:
                    - string
                    - 'null'
                  t:
                    type:
                    - integer
                    - 'null'
                required:
                - text
            agreements:
              type: array
              items:
                type: object
                properties:
                  text:
                    type: string
                  speaker:
                    type:
                    - string
                    - 'null'
                  t:
                    type:
                    - integer
                    - 'null'
                required:
                - text
            disagreements:
              type: array
              items:
                type: object
                properties:
                  text:
                    type: string
                  speaker:
                    type:
                    - string
                    - 'null'
                  t:
                    type:
                    - integer
                    - 'null'
                required:
                - text
        mindmap:
          type:
          - string
          - 'null'
          description: Mermaid source, when one was generated
        model:
          type: string
        updatedAt:
          type: string
          format: date-time
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Stable machine-readable code
        message:
          type: string
          description: Human-readable explanation
      additionalProperties: true
    Anchors:
      type:
      - object
      - 'null'
      description: Millisecond at which each element is said, aligned index by index with its list. Null per element when the model could not place it; null as a whole for analyses generated before Sep 2026.
      properties:
        keyPoints:
          type: array
          items:
            type:
            - integer
            - 'null'
        actionItems:
          type: array
          items:
            type:
            - integer
            - 'null'
        decisions:
          type: array
          items:
            type:
            - integer
            - 'null'
        questions:
          type: array
          items:
            type:
            - integer
            - 'null'
    Outline:
      type: object
      properties:
        noteId:
          type: string
          format: uuid
        outline:
          type: array
          items:
            $ref: '#/components/schemas/Chapter'
        attemptedAt:
          type:
          - string
          - 'null'
          format: date-time
        generated:
          type: boolean
    SpeakerList:
      type: object
      properties:
        noteId:
          type: string
          format: uuid
        speakers:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/Speaker'
            - type: object
              properties:
                evidence:
                  type: array
                  description: Quotes that support the suggested name
                  items:
                    type: object
                    properties:
                      source:
                        type: string
                        enum:
                        - transcript
                        - metadata
                        - roster
                        - voice
                        description: '`voice`: the voice sounds like one of the owner''s voice profiles (only with the owner''s biometric consent)'
                      segment:
                        type:
                        - integer
                        - 'null'
                        description: Segment `sequence` when the source is the transcript
                      quote:
                        type: string
                        description: For `voice`, the profile name
                      similarity:
                        type: number
                        description: 'For `voice`: cosine similarity with the profile (0..1)'
    AnalysisList:
      type: object
      properties:
        noteId:
          type: string
          format: uuid
        analyses:
          type: array
          items:
            $ref: '#/components/schemas/Analysis'
        report:
          type: object
          description: 'Only on POST: which templates came out and which did not'
          properties:
            ok:
              type: array
              items:
                type: string
            failed:
              type: array
              items:
                type: object
    Speaker:
      type: object
      properties:
        label:
          type:
          - string
          - 'null'
          description: A, B, C… as the diarizer assigned them
        name:
          type:
          - string
          - 'null'
          description: 'The name in use: persistent profile, name given by the user, or inferred with high confidence'
        nameStatus:
          type:
          - string
          - 'null'
          enum:
          - confirmed
          - suggested
          - null
          description: '`confirmed` = given by the user; `suggested` = inferred from the content, not confirmed yet'
        suggestedName:
          type:
          - string
          - 'null'
          description: Name inferred from the content and the source metadata
        suggestedNameConfidence:
          type:
          - number
          - 'null'
          minimum: 0
          maximum: 1
        speechSeconds:
          type:
          - number
          - 'null'
        segmentCount:
          type:
          - integer
          - 'null'
        voiceExcluded:
          type: boolean
          description: '"Do not recognise this person" is set on this speaker or on its profile: its voice is not analysed nor matched'
    Segment:
      type: object
      properties:
        sequence:
          type: integer
        startMs:
          type: integer
        endMs:
          type: integer
        speakerLabel:
          type:
          - string
          - 'null'
        speakerName:
          type:
          - string
          - 'null'
        text:
          type: string
        confidence:
          type:
          - number
          - 'null'
        locale:
          type:
          - string
          - 'null'
        words:
          type:
          - array
          - 'null'
          description: Per-word timings when the provider emits them; null otherwise
          items:
            type: object
            properties:
              text:
                type: string
              startMs:
                type: integer
              endMs:
                type: integer
    Transcript:
      type: object
      properties:
        noteId:
          type: string
          format: uuid
        language:
          type:
          - string
          - 'null'
        languagesDetected:
          type: array
          items:
            type: string
        durationSeconds:
          type:
          - integer
          - 'null'
        provider:
          type:
          - string
          - 'null'
        model:
          type:
          - string
          - 'null'
        fullText:
          type: string
        speakers:
          type: array
          items:
            $ref: '#/components/schemas/Speaker'
        segments:
          type: array
          items:
            $ref: '#/components/schemas/Segment'
  responses:
    NotFound:
      description: No note with that id belongs to you
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: not_found
    RateLimited:
      description: Too many requests for this API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: rate_limit_exceeded
            retryAfter: 60
    Forbidden:
      description: Your plan does not include the REST API
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: tier_upgrade_required
            currentTier: personal
            requiredTier: pro
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: invalid_api_key
  parameters:
    NoteId:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'An AudioMap API key: `Authorization: Bearer am_live_...`'
x-audiomap-credits:
  description: Credit cost per operation. Read operations are free unless listed here.
  costs:
    POST /v1/notes (audioUrl): 50
    GET /v1/notes/{id}/transcript: 1
    POST /v1/notes/{id}/analysis: 100 per template
    GET /v1/notes/{id}/outline?generate=1: 50
    POST /v1/notes/{id}/ask: 10
    POST /v1/notes/{id}/transcript/translation: 0 the first time per note and language
    POST /v1/ask: 10
    POST /v1/notes/{id}/deliverables: 300
  monthlyByPlan:
    free: 200
    personal: 1000
    pro: 5000
    power: 25000
    team: 5000
x-audiomap-deliverable-templates:
  email:
  - follow_up
  - recap
  - next_steps
  - thank_you
  document:
  - project_brief
  - meeting_recap
  - fiscal_revision
  - legal_acta
  - medical_consult
  slides:
  - exec_summary
  - kickoff
  - recap_visual
  - sales_pitch_es