canonical: https://jentic.com/apis/nexmo.com/nexmo-media-api # Nexmo Media API Jentic publishes the only available OpenAPI specification for Nexmo Media API, keeping it validated and agent-ready. This media-api slug is the alternate-named copy of the Media service. The same four endpoints under /v3/media cover listing and searching media items, retrieving and updating per-item metadata, and deleting items. Voice applications reference these stored audio files for prompts and recordings. ## For AI agents Manage audio media items used by Nexmo Voice - list, retrieve metadata, update metadata, and delete by id. Four endpoints. ## Scope Does not upload new media, transcribe audio, or play files into a call - use only to list, inspect, update metadata for, and delete items already stored in the Nexmo media bucket. ## Capabilities - List and search media items via GET / - Retrieve metadata for a specific media item via GET /:id/info - Update metadata fields on a media item via PUT /:id/info - Delete a media item by id via DELETE /:id - Reference media items by id from a Nexmo Voice NCCO talk or stream action ## Use cases ### Voice prompt management for IVR flows IVR developers store welcome messages, menu prompts, and outbound notifications as audio in Nexmo Media. The four endpoints support listing the catalogue, inspecting an individual prompt, renaming prompts when scripts change, and removing retired prompts. The Voice NCCO references each prompt by its id. Example prompt: GET / to list current prompts, then PUT /:id/info on the relevant id with a new title field. ### Recording retention enforcement Compliance teams enforce retention windows on call recordings stored by Nexmo Voice. Periodic GET / pulls recording metadata; DELETE /:id removes anything older than the retention threshold. Because the API only exposes management - not playback - sensitive audio never moves through the application during cleanup. Example prompt: GET / with a created-before filter, iterate the response, and DELETE /:id for each id. ### Inventory check by an AI agent An AI agent asked 'what audio prompts do I have on Nexmo?' lists items via Jentic, fetches each item's metadata, and returns a summary. Search by intent, load the operation, execute - no manual URL construction or pagination logic in the agent. Example prompt: Search Jentic for 'list nexmo media items', load GET /, execute, then GET /:id/info per item to enrich the list with titles and mime types. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | / | List and search media items | | GET | /:id/info | Retrieve metadata for a media item | | PUT | /:id/info | Update metadata for a media item | | DELETE | /:id | Delete a media item | ## Key resources - **Media item** — Stored audio or media file - list via GET /, manage by id via /:id and /:id/info ## Why Jentic - **Setup:** Wiring the Nexmo Media API by hand means minting a JWT from your Application signing key for each call and pointing requests at the api.nexmo.com/v3/media host to reach items already in your media bucket. Through Jentic you install once, import the Media API from the API Directory, store the Application private key once, and your agent calls it. - **Permission scoping:** The Media API puts the media item id in the URL path (/:id/info, /:id), so a rule can pin your agent to one media item: it can read that item's info and update its metadata. You choose the operations it may call, so deleting an item is not included unless you add it. - **Credential handling:** Your Vonage Application private key is stored once, encrypted, by your own Jentic One instance and used to mint per-call JWTs at execution time. The key never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'update metadata on a Nexmo media item' or 'list stored media', and Jentic returns the matching Media API operation with its parameter schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Nexmo Application API v2** — Manages applications whose Voice flows play and record these media items - **Twilio API** — Twilio Recordings and Media resources offer comparable audio storage for voice apps - **Plivo** — Plivo's Recordings API covers similar lifecycle management for voice audio ## FAQ ### Why is there no official OpenAPI spec for Nexmo Media API? Vonage (formerly Nexmo) does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Nexmo Media API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Nexmo Media API use? The OpenAPI spec does not declare a securityScheme, but in practice the Vonage Media service requires application-scoped JWT bearer authentication. Through Jentic the JWT is minted from the encrypted private key per call, so the agent never sees the signing material. ### Can I create or upload media items via this API? No. The four endpoints handle listing, retrieving, updating, and deleting items. Uploads use a separate Vonage upload mechanism, and Voice writes recordings into the bucket automatically when calls are recorded. ### What are the rate limits for the Nexmo Media API? The OpenAPI spec does not declare rate limits for /v3/media. Account-level throttles apply; the metadata endpoints are typically called at low volume relative to message or voice traffic. ### How do I delete an old call recording through Jentic? Search Jentic for 'delete a nexmo media item', load DELETE /:id, and execute with the recording id. Use GET / first with a date filter to find candidate ids. ### How does the media-api slug differ from the media slug? Both slugs index the same /v3/media service with the same four endpoints. The duplication is from the original spec ingest; either slug points to the same operations and base URL. ### Can I limit what my agent is allowed to do with the Nexmo Media API? Yes. Because you run Jentic One yourself, your own rules decide which of the four operations the agent may call, so you can allow it to list items with GET / and read metadata with GET /:id/info while withholding PUT /:id/info and DELETE /:id. Since the media item id sits in the URL path, a rule can also pin the agent to a single item, letting it read and update that item's metadata only. Deleting an item is never available unless you explicitly grant it.