API Documentation

Authentication

Every API request carries an API key. Pass it via:

• Authorization header (recommended): Authorization: Bearer YOUR_API_KEY
• Query parameter: ?api_key=YOUR_API_KEY

Get your API key: Sign up (free tier includes 100 searches/month and 1 API key), then visit Profile > API Keys.

Plans & pricing

Plan names, included quotas (searches, API calls, transcription minutes), and prices live on the pricing page.

See plans and pricing →

Agent checkout — programmatic upgrade

AI agents can initiate a subscription upgrade on behalf of their user:

curl -X POST "https://www.audioscrape.com/api/agent/payment-link" \
     -H "Content-Type: application/json" \
     -d '{"plan": "starter", "email": "[email protected]"}'

Returns a Stripe payment link the agent can present to the user. No API key required for this endpoint.

Endpoints

The core REST surface, grouped by resource.

curl -X POST "https://www.audioscrape.com/api/search" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"query": "artificial intelligence", "limit": 10}'

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://www.audioscrape.com/api/charts/podcasts?country=us"

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://www.audioscrape.com/api/podcasts?q=technology"

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://www.audioscrape.com/api/persons/elon-musk"

MCP Server

Audioscrape provides an MCP (Model Context Protocol) server for AI assistants and agent platforms. Our implementation follows the Nov 2025 MCP authorization spec.

connector URL  https://mcp.audioscrape.com

OAuth Authorization Flow

Authentication uses OAuth 2.1 with mandatory PKCE (S256). The flow:

1. Discover — Fetch GET /.well-known/oauth-authorization-server for endpoints
2. Register — POST /oauth/register with your client name and redirect URIs (RFC 7591 Dynamic Client Registration)
3. Authorize — GET /oauth/authorize with client_id, code_challenge (S256), redirect_uri, and optional resource parameter (RFC 8707)
4. Exchange — POST /oauth/token with authorization code and code_verifier
5. Refresh — POST /oauth/token with grant_type=refresh_token (tokens are rotated per Nov 2025 spec)

Discovery Endpoints

• GET /.well-known/oauth-authorization-server — Authorization server metadata (RFC 8414)
• GET /.well-known/openid-configuration — Same metadata, OpenID Connect compatible
• GET /.well-known/oauth-protected-resource — Protected resource metadata (RFC 9728)

Example: Register a Client

POST https://mcp.audioscrape.com/oauth/register
Content-Type: application/json

{
  "client_name": "My AI App",
  "redirect_uris": ["https://myapp.com/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "scope": "mcp:search mcp:read profile"
}

Available MCP Tools

Discover the live list and JSON schemas via the MCP tools/list method. Names below are stable.

• search_audio — Search across all transcribed audio (public podcasts + your uploads); returns matching segments with timestamps
• list_recent_transcripts — Newest episodes in the public library by publish date, optionally scoped to specific podcasts (your own recordings: list_my_uploads)
• get_transcript — Full transcript and metadata for one item (episode or upload)
• list_podcast_episodes — Episodes within one podcast show
• search_podcasts — Search podcasts by title
• search_speakers — Search hosts/speakers by name
• get_speaker — A speaker's bio and audio appearances
• search_entities — Knowledge graph search across people, companies, locations, topics
• get_trending — Currently trending people, topics, and organizations
• get_charts — Apple Podcasts and Spotify chart rankings by country
• transcribe_audio — Submit an audio URL for transcription into the user's private workspace
• get_transcription_status — Poll status of a transcribe_audio job
• list_my_datasets — Libraries and datasets the user is subscribed to (use first to scope searches)
• list_my_uploads — The user's own uploaded transcripts
• create_share_link — Shareable URL for an audio moment with social-media preview

Manage your connected MCP apps from your profile settings.

Error Handling

The status and error codes you will see, and what they mean.

Need Help?

Contact us at [email protected].