DEVELOPERS
Connect your agents and scripts
AI apps connect to your library through the MCP server, and sign in with your account. Scripts use the REST API with a personal API key. Either way they act as you, only with the permissions you give them, and you can see what they did in Account → Activity.
Connect an AI app
The MCP server is at https://audiochad.com/mcp. It speaks Streamable HTTP and signs in with OAuth, so most apps only need the address.
Claude
On claude.ai, the desktop app, or the phone app, open Settings → Connectors → Add custom connector, paste the address, and choose Connect. Sign in to AudioChad and choose what Claude may do.
Claude Code
claude mcp add --transport http audiochad https://audiochad.com/mcp
Then run /mcp in Claude Code, pick audiochad, and choose Authenticate. To use an API key instead, add --header "Authorization: Bearer ac_…".
ChatGPT
Turn on developer mode under Settings → Apps & Connectors → Advanced (plans with developer mode), then create a connector with the address and OAuth sign-in.
Codex
codex mcp add audiochad --url https://audiochad.com/mcp codex mcp login audiochad
Or, with an API key in an environment variable, set bearer_token_env_var = "AUDIOCHAD_API_KEY" under [mcp_servers.audiochad] in ~/.codex/config.toml.
Agents on a server
Agents without a browser, like Hermes on a home server, can connect with a device code: the agent asks https://audiochad.com/oauth/device_authorization for a code, you approve it at https://audiochad.com/oauth/device on any device, and the agent picks up its tokens. Or give it an API key.
Other apps
Any MCP client works if it supports OAuth 2.1 with PKCE (registering itself, or with a client ID metadata document) or lets you set an Authorization: Bearer header with an API key. Make keys in Account on the web or in the app.
Tools
An app only sees the tools its permissions allow.
search_soundsread- Search the sounds this account can see, by words in their titles, tags, private tags, and transcripts. Leave query empty to list everything. Returns at most limit sounds, with the start of each transcript. Set drafts to search this account's drafts instead: long uploads waiting to have clips cut from them.
get_soundread- Get one sound with its whole transcript, tags, boards, and loudness adjustment. Set include_words for when each word is said, to pick times for trim_sound and split_sound. audioUrl downloads the audio when requested with the same Authorization header.
list_boardsread- List the boards this account owns or was invited to, with its role on each (owner, editor, or viewer) and how many sounds they hold.
get_usageread- How much storage this account's library uses, against its plan's allowance, split into served audio, originals kept for editing, and card photos.
get_upload_linkwrite- Get a one-time link to upload an audio or video file from this computer, for agents that can run shell commands. Upload with: curl --fail-with-body -T <path to file> <url>. The link works once, for an hour, and responds with the new sound. The file's name becomes the title unless title is set. Files up to 500 MB and 2 hours; anything over a minute is saved as a draft to cut clips from.
import_from_linkwrite- Add a sound from a direct link to an audio or video file on the public internet, like https://example.com/clip.mp3. Links to web pages, such as a video's page, are refused; link to the file itself. Files up to 500 MB and 2 hours; anything over a minute is saved as a draft to cut clips from.
trim_soundwrite- Keep part of a sound as a new sound named title: from start_seconds to end_seconds, or wherever a quote is said, like quote "let's go" (found in the transcript's word timings, ignoring case and punctuation, with padding_seconds around it). Set remove_range to cut that part out instead. Set repeat to play a kept part up to 3 times in a row. Set overwrite to replace the sound's audio instead of saving a new one; only the owner can. Clips are a minute at most. Cutting from a draft deletes the draft unless keep_draft is set.
split_soundwrite- Save parts of a sound as new sounds, each with its own title, given by start_seconds and end_seconds or by a quote that's said in it. Clips must be in order, not overlap, and be a minute at most. The original is kept, except a draft, which is deleted unless keep_draft is set.
set_loudnesswrite- Make a sound louder or quieter than the library's normal level, in dB from -12 to +12. 0 plays it at the normal level. The audio is re-rendered in the background.
update_soundwrite- Change a sound's title, replace its tags, or correct its transcript. Fields left out stay as they are. Only the owner can change the title and tags; editors of its boards can correct the transcript.
add_to_boardwrite- Put sounds this account owns on a board it owns or edits.
remove_from_boardwrite- Take sounds off a board. The sounds stay in their owners' libraries.
share_soundshare- Make an unlisted link to a sound that anyone with the link can play, with a preview card in chats. Each call makes a new link.
delete_sounddelete- Permanently delete a sound this account owns, with its audio, card, and share links. It's removed from every board. This can't be undone.
Adding files from your computer
Chat apps can't send files through MCP. An agent that can run commands, like Claude Code or Codex, calls get_upload_link and uploads with the command it returns:
curl --fail-with-body -T ./clip.mp3 https://audiochad.com/v1/upload-links/<token>/
The link works once, for an hour. For files already online, import_from_link takes a direct link to the audio or video file.
Permissions and limits
- read is always on: search, listen, and see transcripts and boards. write adds and edits sounds, share makes links and invites people to boards, and delete deletes sounds and boards.
- Keys and apps can't sign in, manage keys or connected apps, or delete your account, and never act as an admin.
- Each key and app can make 120 reads and 30 changes a minute, and 20 heavy jobs (uploads, imports, edits, loudness changes, exports) every 10 minutes. Over the limit, the API answers 429 with Retry-After, and tools return an error saying when to try again.
- Sounds are a minute at most. Uploads and imports up to 2 hours and 500 MB are saved as drafts, kept for 7 days, to cut clips from with
trim_soundandsplit_sound;search_soundsfinds them withdraftsset. - Disconnect an app or delete a key in Account; it stops working right away.
REST API
The base address is https://audiochad.com. Send a personal API key as Authorization: Bearer ac_…. The OpenAPI document describes every request and response.
- Errors are JSON:
{"error": "what went wrong"}. - Times named
…Msare milliseconds; other times are Unix nanoseconds. GET /v1/soundsand the activity log come a page at a time: passnextfrom one page ascursor(orbefore) to get the next.- Uploads, imports, and edits take an
Idempotency-Keyheader, so a retry returns the first response instead of making a second sound.
Sounds
POST | /v1/imports | Import a sound from a direct link write |
POST | /v1/me/private-tags | Add private tags to sounds write |
POST | /v1/requests | Request a sound write |
GET | /v1/sounds | Search and list sounds read |
POST | /v1/sounds/tags | Add tags to sounds write |
POST | /v1/sounds/visibility | Set whether sounds are public write |
DELETE | /v1/sounds/{id} | Delete a sound delete |
GET | /v1/sounds/{id} | Get a sound read |
PATCH | /v1/sounds/{id} | Change a sound's title and tags write |
GET | /v1/sounds/{id}/audio | Stream a sound's audio read |
GET | /v1/sounds/{id}/download | Download a sound's audio read |
GET | /v1/sounds/{id}/waveform | A waveform image read |
POST | /v1/uploads | Upload a sound write |
Editing
POST | /v1/sounds/{id}/edit | Trim, cut, or split a sound write |
PUT | /v1/sounds/{id}/gain | Set a sound's loudness write |
POST | /v1/sounds/{id}/transcribe | Transcribe a sound again write |
PUT | /v1/sounds/{id}/transcript | Correct a sound's transcript write |
GET | /v1/sounds/{id}/words | When each transcript word is said read |
Boards
GET | /v1/boards | List boards read |
POST | /v1/boards | Make a board write |
DELETE | /v1/boards/{id} | Delete a board delete |
PATCH | /v1/boards/{id} | Rename a board write |
GET | /v1/boards/{id}/invites | List a board's invite links read |
POST | /v1/boards/{id}/invites | Make an invite link share |
DELETE | /v1/boards/{id}/invites/{inviteId} | Revoke an invite link share |
GET | /v1/boards/{id}/members | List a board's members read |
POST | /v1/boards/{id}/members | Add someone to a board share |
DELETE | /v1/boards/{id}/members/{userId} | Remove a member, or leave share |
PATCH | /v1/boards/{id}/members/{userId} | Change a member's role share |
DELETE | /v1/boards/{id}/sounds | Take sounds off a board write |
POST | /v1/boards/{id}/sounds | Add sounds to a board write |
GET | /v1/invites/{token} | What an invite link is for read |
POST | /v1/invites/{token}/accept | Join a board with an invite link write |
Sharing
PUT | /v1/sounds/{id}/card | Style a sound's card write |
GET | /v1/sounds/{id}/card.mp4 | The card as a video with the sound read |
GET | /v1/sounds/{id}/card.png | The card as an image read |
DELETE | /v1/sounds/{id}/card/photo | Remove the card photo write |
GET | /v1/sounds/{id}/card/photo | The card photo read |
PUT | /v1/sounds/{id}/card/photo | Set the card photo write |
POST | /v1/sounds/{id}/share | Make a share link share |
DELETE | /v1/sounds/{id}/share/{shareId} | Remove a share link share |
Account
POST | /v1/accounts | Create an account from an invite link |
DELETE | /v1/me | Delete the account and its library read |
GET | /v1/me | Who the request acts as |
GET | /v1/me/activity | The activity log read |
POST | /v1/me/email-verification | Email a new verification link read |
GET | /v1/me/exports | List library exports read |
POST | /v1/me/exports | Start a zip export of the library read |
GET | /v1/me/exports/{id}/download | Download a ready export read |
DELETE | /v1/me/sessions | Sign out every session read |
GET | /v1/me/storage | Storage used against the plan's allowance read |
POST | /v1/password-reset | Email a password reset link |
DELETE | /v1/session | Sign out this session read |
POST | /v1/session | Sign in with an email and password |
Agents
GET | /v1/me/api-keys | List API keys read |
POST | /v1/me/api-keys | Create an API key read |
DELETE | /v1/me/api-keys/{id} | Delete an API key read |
GET | /v1/me/connections | List connected apps read |
DELETE | /v1/me/connections/{id} | Disconnect an app read |
POST | /v1/upload-links | Make a one-time upload link write |
POST | /v1/upload-links/{token}/{name} | Upload a file through an upload link |
PUT | /v1/upload-links/{token}/{name} | Upload a file through an upload link |
Public
GET | /v1/changelog | What's new |
GET | /v1/openapi.json | This document |
GET | /v1/shares/{token} | A shared sound's details |
GET | /v1/shares/{token}/audio | A shared sound's audio |
GET | /v1/shares/{token}/card.png | A shared sound's card |
Admin
GET | /v1/admin/status | Sign-in and server status |
GET | /v1/admin/users | List accounts read |
PATCH | /v1/admin/users/{id} | Change an account's role or plan read |
POST | /v1/admin/users/{id}/password | Set an account's password read |