API Documentation

Authentication

All API requests require 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 10 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": "basic", "email": "[email protected]"}'

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

Endpoints

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.

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 — Recently transcribed audio, optionally scoped to specific podcasts
• 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

Need Help?

Contact us at [email protected].