AudioMap API

Versión 1.0.0 · 18 operaciones · openapi.json

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.

Servidor

https://api.audiomap.ai

Autenticación

An AudioMap API key: `Authorization: Bearer am_live_...`

curl https://api.audiomap.ai/v1/notes \
  -H "Authorization: Bearer am_live_..."

Índice

notes

Create and browse notes

GET /v1/notes

List notes, newest first

Cursor pagination: pass the `nextCursor` of a response as `cursor` to get the next page. `hasMore` says whether there is one.

Parámetros

NombreDóndeTipoDescripción
limitqueryinteger
cursorquerystring (uuid)nextCursor from the previous page
qquerystringFree text over title, description and transcript
folderIdquerystringFolder UUID, or the literal "null" for notes with no folder
statusquerystring (processing | ready | failed)
sincequerystring (date-time)Only notes created at or after this instant
tagsquerystringComma separated; returns notes carrying ALL of them
originquerystringComma separated origins to keep: youtube, podcast, link, video, audio, recording. An unknown value is a 400

Respuestas

CódigoSignificadoCuerpoEjemplo
200A page of notesNoteList
400Invalid query parametersError{"error":"invalid_query"}
401Missing or invalid API keyError{"error":"invalid_api_key"}
403Your plan does not include the REST APIError{"error":"tier_upgrade_required","currentTier":"personal","requiredTier":"pro"}
404No note with that id belongs to youError{"error":"not_found"}
429Too many requests for this API keyError{"error":"rate_limit_exceeded","retryAfter":60}

POST /v1/notes

Import from a public link, or open a direct upload

Two mutually exclusive shapes: - `audioUrl`: import a YouTube video, a podcast (RSS feed or Apple Podcasts page) or a direct audio/video file URL. Spotify is not supported (DRM). - `filename` + `contentType`: open a direct upload. The response carries a presigned `upload.url`; PUT the bytes there and then call `POST /v1/notes/{id}/finalize`. Transcription is asynchronous: poll `GET /v1/notes/{id}` until `status` is "ready".

Cuerpo de la petición obligatorio

Esquema: CreateNoteRequest

Respuestas

CódigoSignificadoCuerpoEjemplo
202Note created and queuedCreateNoteResponse
400Malformed body, or a link we cannot ingestError{"error":"invalid_audio_url"}
401Missing or invalid API keyError{"error":"invalid_api_key"}
402Not enough creditsError{"error":"insufficient_credits","balance":10,"required":50}
403Your plan does not include the REST APIError{"error":"tier_upgrade_required","currentTier":"personal","requiredTier":"pro"}
404No note with that id belongs to youError{"error":"not_found"}
413File larger than the plan allows, or storage quota exceededError{"error":"file_too_large"}
415Content type that is neither audio/* nor video/*Error{"error":"unsupported_media_type"}
429Too many requests for this API keyError{"error":"rate_limit_exceeded","retryAfter":60}

GET /v1/notes/{id}

Get one note with its full text, analyses and outline

Parámetros

NombreDóndeTipoDescripción
id obligatoriopathstring (uuid)

Respuestas

CódigoSignificadoCuerpoEjemplo
200The noteNoteDetail
401Missing or invalid API keyError{"error":"invalid_api_key"}
403Your plan does not include the REST APIError{"error":"tier_upgrade_required","currentTier":"personal","requiredTier":"pro"}
404No note with that id belongs to youError{"error":"not_found"}
429Too many requests for this API keyError{"error":"rate_limit_exceeded","retryAfter":60}

POST /v1/notes/{id}/finalize

Close a direct upload and start processing

Call it after PUTting the bytes to the presigned `upload.url`.

Parámetros

NombreDóndeTipoDescripción
id obligatoriopathstring (uuid)

Cuerpo de la petición

CampoTipoDescripción
titlestring

Respuestas

CódigoSignificadoCuerpoEjemplo
202Upload accepted, processing queuedobject
401Missing or invalid API keyError{"error":"invalid_api_key"}
402Monthly minute quota exhaustedError{"error":"quota_exceeded","remaining":3,"needed":12}
403Your plan does not include the REST APIError{"error":"tier_upgrade_required","currentTier":"personal","requiredTier":"pro"}
404No note with that id belongs to youError{"error":"not_found"}
409The note is not waiting for an uploadError{"error":"invalid_state","current":"ready"}
429Too many requests for this API keyError{"error":"rate_limit_exceeded","retryAfter":60}

content

Transcript, analysis and outline of a note

GET /v1/notes/{id}/transcript

Transcript with segments, speakers and word timings

`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.

Parámetros

NombreDóndeTipoDescripción
id obligatoriopathstring (uuid)
formatquerystring (json | txt | srt | vtt | md)
translationquerystring (es | en | de | fr | it | pt)Include an already generated translation in this language. In json every segment gets `translation`; in text formats see `translationMode`.
translationModequerystring (translation | both)`translation`: the transcript comes out translated. `both`: original with its translation under every segment.

Respuestas

CódigoSignificadoCuerpoEjemplo
200The transcriptTranscript
400Unknown formatError{"error":"invalid_format"}
401Missing or invalid API keyError{"error":"invalid_api_key"}
402Not enough creditsError{"error":"insufficient_credits"}
403Your plan does not include the REST APIError{"error":"tier_upgrade_required","currentTier":"personal","requiredTier":"pro"}
404Note not found, or it has no transcript yetError{"error":"no_transcript"}
429Too many requests for this API keyError{"error":"rate_limit_exceeded","retryAfter":60}

GET /v1/notes/{id}/transcript/translation

State and segments of the transcript translation

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.

Parámetros

NombreDóndeTipoDescripción
id obligatoriopathstring (uuid)
languagequerystring (es | en | de | fr | it | pt)Target language; defaults to the user language.

Respuestas

CódigoSignificadoCuerpoEjemplo
200The translation stateobject
400Unknown languageError{"error":"invalid_language"}
401Missing or invalid API keyError{"error":"invalid_api_key"}
403Your plan does not include the REST APIError{"error":"tier_upgrade_required","currentTier":"personal","requiredTier":"pro"}
404Note not found, or it has no transcript yetError{"error":"no_transcript"}
429Too many requests for this API keyError{"error":"rate_limit_exceeded","retryAfter":60}

POST /v1/notes/{id}/transcript/translation

Translate the transcript into a language

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.

Parámetros

NombreDóndeTipoDescripción
id obligatoriopathstring (uuid)

Cuerpo de la petición

CampoTipoDescripción
languagestring (es | en | de | fr | it | pt)

Respuestas

CódigoSignificadoCuerpoEjemplo
200Already translatedobject
202Queued or runningobject
401Missing or invalid API keyError{"error":"invalid_api_key"}
402Not enough creditsError{"error":"insufficient_credits"}
403Your plan does not include the REST APIError{"error":"tier_upgrade_required","currentTier":"personal","requiredTier":"pro"}
404Note not found, or it has no transcript yetError{"error":"no_transcript"}
409The audio is already in that languageError{"error":"same_language"}
429Too many requests for this API keyError{"error":"rate_limit_exceeded","retryAfter":60}

GET /v1/notes/{id}/analysis

Read the generated analyses of a note

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.

Parámetros

NombreDóndeTipoDescripción
id obligatoriopathstring (uuid)
templatequerystring (generic | sales | legal | medical | journalism | education | customer_success | meeting_minutes | consulting | coaching | therapy | podcast | university_class | debate)

Respuestas

CódigoSignificadoCuerpoEjemplo
200The analyses persisted for this noteAnalysisList
401Missing or invalid API keyError{"error":"invalid_api_key"}
403Your plan does not include the REST APIError{"error":"tier_upgrade_required","currentTier":"personal","requiredTier":"pro"}
404Note not found, or that template has not been generatedError{"error":"analysis_not_generated","template":"sales"}
429Too many requests for this API keyError{"error":"rate_limit_exceeded","retryAfter":60}

POST /v1/notes/{id}/analysis

Generate or regenerate an analysis template

Parámetros

NombreDóndeTipoDescripción
id obligatoriopathstring (uuid)

Cuerpo de la petición obligatorio

CampoTipoDescripción
templatestring (generic | sales | legal | medical | journalism | education | customer_success | meeting_minutes | consulting | coaching | therapy | podcast | university_class | debate)
templatesarray<string (generic | sales | legal | medical | journalism | education | customer_success | meeting_minutes | consulting | coaching | therapy | podcast | university_class | debate)>

Respuestas

CódigoSignificadoCuerpoEjemplo
200Generated; `report` lists which templates failed, if anyAnalysisList
401Missing or invalid API keyError{"error":"invalid_api_key"}
402Not enough credits, or the template needs a paid planError{"error":"upgrade_required"}
403Your plan does not include the REST APIError{"error":"tier_upgrade_required","currentTier":"personal","requiredTier":"pro"}
404No note with that id belongs to youError{"error":"not_found"}
409The note is not ready, or has no transcriptError{"error":"note_not_ready"}
429Too many requests for this API keyError{"error":"rate_limit_exceeded","retryAfter":60}
502Every requested template failed; credits were refundedError{"error":"llm_invalid_json"}

GET /v1/notes/{id}/outline

Chapters of the note with timestamps

Reading is free. `?generate=1` on a note that has no outline generates one and charges credits.

Parámetros

NombreDóndeTipoDescripción
id obligatoriopathstring (uuid)
generatequerystring (0 | 1)

Respuestas

CódigoSignificadoCuerpoEjemplo
200The outline; empty array when there is noneOutline
401Missing or invalid API keyError{"error":"invalid_api_key"}
402Not enough credits to generate itError{"error":"insufficient_credits"}
403Your plan does not include the REST APIError{"error":"tier_upgrade_required","currentTier":"personal","requiredTier":"pro"}
404No note with that id belongs to youError{"error":"not_found"}
409The note is not readyError{"error":"note_not_ready"}
429Too many requests for this API keyError{"error":"rate_limit_exceeded","retryAfter":60}

GET /v1/notes/{id}/speakers

Speakers of the note with their names

`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.

Parámetros

NombreDóndeTipoDescripción
id obligatoriopathstring (uuid)

Respuestas

CódigoSignificadoCuerpoEjemplo
200The speakersSpeakerList
401Missing or invalid API keyError{"error":"invalid_api_key"}
403Your plan does not include the REST APIError{"error":"tier_upgrade_required","currentTier":"personal","requiredTier":"pro"}
404No note with that id belongs to youError{"error":"not_found"}
429Too many requests for this API keyError{"error":"rate_limit_exceeded","retryAfter":60}

POST /v1/notes/{id}/speakers/suggest

Infer the speaker names from content and metadata

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.

Parámetros

NombreDóndeTipoDescripción
id obligatoriopathstring (uuid)

Respuestas

CódigoSignificadoCuerpoEjemplo
200The speakers after the inferenceSpeakerList
401Missing or invalid API keyError{"error":"invalid_api_key"}
403Your plan does not include the REST APIError{"error":"tier_upgrade_required","currentTier":"personal","requiredTier":"pro"}
404No note with that id belongs to youError{"error":"not_found"}
409The note is not readyError{"error":"note_not_ready"}
429Too many requests for this API keyError{"error":"rate_limit_exceeded","retryAfter":60}
502The inference failed; nothing changedError{"error":"speaker_naming_failed"}

PATCH /v1/notes/{id}/speakers/{label}

Name a speaker, or confirm its suggested name

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.

Parámetros

NombreDóndeTipoDescripción
id obligatoriopathstring (uuid)
label obligatoriopathstringA, B, C… as the diarizer assigned them

Cuerpo de la petición obligatorio

CampoTipoDescripción
name obligatoriostring

Respuestas

CódigoSignificadoCuerpoEjemplo
200The speakers after the changeSpeakerList
401Missing or invalid API keyError{"error":"invalid_api_key"}
403Your plan does not include the REST APIError{"error":"tier_upgrade_required","currentTier":"personal","requiredTier":"pro"}
404No note with that id belongs to youError{"error":"not_found"}
429Too many requests for this API keyError{"error":"rate_limit_exceeded","retryAfter":60}

GET /v1/voice-profiles

Voice profiles of the user and the state of the biometric consent

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.

Respuestas

CódigoSignificadoCuerpoEjemplo
200Consent state and profilesobject
401Missing or invalid API keyError{"error":"invalid_api_key"}
403Your plan does not include the REST APIError{"error":"tier_upgrade_required","currentTier":"personal","requiredTier":"pro"}
404No note with that id belongs to youError{"error":"not_found"}
429Too many requests for this API keyError{"error":"rate_limit_exceeded","retryAfter":60}

ask

Ask questions over one note or the whole library

POST /v1/notes/{id}/ask

Ask a question about one note

The answer quotes the audio as [mm:ss]; `citedSegments` carries the transcript segment ids the retrieval used.

Parámetros

NombreDóndeTipoDescripción
id obligatoriopathstring (uuid)

Cuerpo de la petición obligatorio

CampoTipoDescripción
question obligatoriostring

Respuestas

CódigoSignificadoCuerpoEjemplo
200The answer with its citationsAnswer
401Missing or invalid API keyError{"error":"invalid_api_key"}
402Not enough creditsError{"error":"insufficient_credits"}
403Your plan does not include the REST APIError{"error":"tier_upgrade_required","currentTier":"personal","requiredTier":"pro"}
404No note with that id belongs to youError{"error":"not_found"}
409The note is not readyError{"error":"note_not_ready"}
429Too many requests for this API keyError{"error":"rate_limit_exceeded","retryAfter":60}
502The model did not answer; credits were refundedError{"error":"chat_failed"}

POST /v1/ask

Ask a question across every note you own

Answers cite [Note title | mm:ss]. Pass the returned `sessionId` back to continue the same conversation.

Cuerpo de la petición obligatorio

CampoTipoDescripción
question obligatoriostring
sessionIdstring (uuid)

Respuestas

CódigoSignificadoCuerpoEjemplo
200The answer with the notes it came fromGlobalAnswer
401Missing or invalid API keyError{"error":"invalid_api_key"}
402Not enough creditsError{"error":"insufficient_credits"}
403Your plan does not include the REST APIError{"error":"tier_upgrade_required","currentTier":"personal","requiredTier":"pro"}
404No note with that id belongs to youError{"error":"not_found"}
429Too many requests for this API keyError{"error":"rate_limit_exceeded","retryAfter":60}
502The model did not answer; credits were refundedError{"error":"chat_failed"}

deliverables

Generate emails, documents and slide decks from a note

GET /v1/notes/{noteId}/deliverables

List the deliverables generated for a note

Parámetros

NombreDóndeTipoDescripción
noteId obligatoriopathstring (uuid)

Respuestas

CódigoSignificadoCuerpoEjemplo
200The listobject
401Missing or invalid API keyError{"error":"invalid_api_key"}
403Your plan does not include the REST APIError{"error":"tier_upgrade_required","currentTier":"personal","requiredTier":"pro"}
404No note with that id belongs to youError{"error":"not_found"}
429Too many requests for this API keyError{"error":"rate_limit_exceeded","retryAfter":60}

POST /v1/notes/{noteId}/deliverables

Write a document from the note

Turns a note into a finished piece of writing: a follow-up email, a meeting record, a slide deck. This is what "draft me something out of what I imported" maps to.

Parámetros

NombreDóndeTipoDescripción
noteId obligatoriopathstring (uuid)

Cuerpo de la petición obligatorio

CampoTipoDescripción
kind obligatoriostring (email | document | slides)
template obligatoriostringValid values depend on `kind`; see x-audiomap-deliverable-templates.
locale obligatoriostring (es | en)

Respuestas

CódigoSignificadoCuerpoEjemplo
201The generated deliverableobject
400Unknown kind, template or localeError{"error":"invalid_template"}
401Missing or invalid API keyError{"error":"invalid_api_key"}
402Not enough creditsError{"error":"insufficient_credits"}
403Your plan does not include the REST APIError{"error":"tier_upgrade_required","currentTier":"personal","requiredTier":"pro"}
404No note with that id belongs to youError{"error":"not_found"}
429Too many requests for this API keyError{"error":"rate_limit_exceeded","retryAfter":60}

Créditos

Credit cost per operation. Read operations are free unless listed here.

OperaciónCréditos
POST /v1/notes (audioUrl)50
GET /v1/notes/{id}/transcript1
POST /v1/notes/{id}/analysis100 per template
GET /v1/notes/{id}/outline?generate=150
POST /v1/notes/{id}/ask10
POST /v1/notes/{id}/transcript/translation0 the first time per note and language
POST /v1/ask10
POST /v1/notes/{id}/deliverables300

Créditos incluidos al mes, por plan

PlanCréditos/mes
free200
personal1000
pro5000
power25000
team5000

Esquemas

Error

CampoTipoDescripción
error obligatoriostringStable machine-readable code
messagestringHuman-readable explanation

CreateNoteRequest

CampoTipoDescripción
audioUrlstring (uri)Public link to import
filenamestringDirect upload: original file name
contentTypestringDirect upload: audio/* or video/*
fileSizeBytesinteger
titlestring
languagestringForce a locale (es-ES, en-US…). Default: auto-detect
keepAudiobooleanDirect upload: keep the audio beyond the retention window

CreateNoteResponse

CampoTipoDescripción
noteId obligatoriostring (uuid)
status obligatoriostring (processing)
providerstringImport only: youtube | apple-podcasts | podcast-rss | direct
uploadobjectDirect upload only
nextstringWhat to do next, in plain words

Note

CampoTipoDescripción
idstring (uuid)
titlestring
descriptionstring,null
statusstring (processing | ready | failed)
errorCodestring,nullWhy it failed; null otherwise
sourceTypestring (upload | recording | url)
originstring (youtube | podcast | link | video | audio | recording)
sourceUrlstring,null
folderIdstring,null (uuid)
tagsarray<string>
durationSecondsinteger,null
languagestring,null
recordedAtstring,null (date-time)
createdAtstring (date-time)
updatedAtstring (date-time)

NoteList

CampoTipoDescripción
notesarray<Note>
nextCursorstring,null (uuid)
hasMoreboolean

NoteDetail

Tipo: —

Speaker

CampoTipoDescripción
labelstring,nullA, B, C… as the diarizer assigned them
namestring,nullThe name in use: persistent profile, name given by the user, or inferred with high confidence
nameStatusstring,null (confirmed | suggested | )`confirmed` = given by the user; `suggested` = inferred from the content, not confirmed yet
suggestedNamestring,nullName inferred from the content and the source metadata
suggestedNameConfidencenumber,null
speechSecondsnumber,null
segmentCountinteger,null
voiceExcludedboolean"Do not recognise this person" is set on this speaker or on its profile: its voice is not analysed nor matched

SpeakerList

CampoTipoDescripción
noteIdstring (uuid)
speakersarray<—>

Segment

CampoTipoDescripción
sequenceinteger
startMsinteger
endMsinteger
speakerLabelstring,null
speakerNamestring,null
textstring
confidencenumber,null
localestring,null
wordsarray,nullPer-word timings when the provider emits them; null otherwise

Transcript

CampoTipoDescripción
noteIdstring (uuid)
languagestring,null
languagesDetectedarray<string>
durationSecondsinteger,null
providerstring,null
modelstring,null
fullTextstring
speakersarray<Speaker>
segmentsarray<Segment>

Anchors

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.

CampoTipoDescripción
keyPointsarray<integer,null>
actionItemsarray<integer,null>
decisionsarray<integer,null>
questionsarray<integer,null>

Analysis

CampoTipoDescripción
templatestring (generic | sales | legal | medical | journalism | education | customer_success | meeting_minutes | consulting | coaching | therapy | podcast | university_class | debate)
summarystring
keyPointsarray<string>
actionItemsarray<object>
decisionsarray<string>
questionsarray<string>
topicsarray<string>
anchorsAnchors
sectionsobject,nullTemplate-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.
mindmapstring,nullMermaid source, when one was generated
modelstring
updatedAtstring (date-time)

AnalysisList

CampoTipoDescripción
noteIdstring (uuid)
analysesarray<Analysis>
reportobjectOnly on POST: which templates came out and which did not

Chapter

CampoTipoDescripción
startMsinteger
endMsinteger
headlinestring

Outline

CampoTipoDescripción
noteIdstring (uuid)
outlinearray<Chapter>
attemptedAtstring,null (date-time)
generatedboolean

Answer

CampoTipoDescripción
noteIdstring (uuid)
questionstring
answerstringQuotes the audio as [mm:ss]
citedSegmentsarray<string (uuid)>

GlobalAnswer

CampoTipoDescripción
questionstring
answerstringQuotes as [Note title | mm:ss]
citedSegmentsarray<string (uuid)>
citedNotesarray<object>
sessionIdstring (uuid)

Esta página se genera en el servidor a partir del mismo documento que sirve /v1/openapi.json, así que no puede quedarse desfasada respecto al contrato.