Integrations

Testing Your Integration

Verify your Audioscrape integration end-to-end: credentials, search, uploads, permission scoping, failure handling, and continuous checks. Each step has a copy-paste command and the result to expect.

Work through the sections in order the first time; afterwards, each check stands alone. Commands use your API key. Create one in your workspace under API Keys → Create key (see Authentication). Integrating over MCP instead? The same method with MCP-native commands: Testing Over MCP.

Step 1

Verify Your Credentials

Confirm your key authenticates and resolves to the workspace and plan you expect. 

curl "https://www.audioscrape.com/api/me" \
     -H "Authorization: Bearer YOUR_API_KEY"
{
  "user": { "id": 123, "email": "[email protected]", "name": "You" },
  "workspace": { "slug": "your-workspace", "name": "Your Workspace", "role": "admin" },
  "plan": { "name": "pro", "limits": { "...": "..." } }
}

Check three things: the request returns 200, the workspace.slug is the workspace you intend to integrate against, and plan.limits match your subscription. A key from the wrong workspace is the most common integration bug, and this is the two-second test that catches it.

Connecting over MCP instead? Confirm the OAuth discovery documents load, then complete the flow from your MCP client (see MCP Overview): 

curl "https://mcp.audioscrape.com/.well-known/oauth-authorization-server"
curl "https://mcp.audioscrape.com/.well-known/oauth-protected-resource"
Step 3

Uploads Become Transcripts

Run one short recording through the full pipeline. Use a small file (a minute or two) so the round-trip is fast and cheap to repeat. 

curl -X POST "https://www.audioscrape.com/api/datasets/YOUR_DATASET_ID/items" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -F "audio=@/path/to/short-test-clip.mp3" \
     -F "title=Integration test upload"
{
  "success": true,
  "item_id": 84217,
  "message": "Audio file queued for transcription with priority 100"
}

Poll the item until transcription completes (typically a few minutes; uploads are prioritized over background ingestion): 

curl "https://www.audioscrape.com/api/items/84217" \
     -H "Authorization: Bearer YOUR_API_KEY"

A pass is all four of the following, not just "no error":

  • the item reaches completed status;
  • the transcript has more than zero segments;
  • the item's duration is greater than zero;
  • at least one segment carries a speaker attribution.

Then search the phrase your test clip contains (Step 2); it should now match. If your recordings are meetings, calls, or interviews, set content_type on the upload (or a default on the dataset) and confirm the completed item carries it: the content type selects the extraction applied to the transcript. Upload details and URL-based ingestion: Upload Audio.

Step 4

Scoping and Permissions

API keys are pinned to a workspace: they read that workspace's data plus the public corpus, and nothing else. If you operate multiple workspaces (for example dev, test, and production), verify the boundary explicitly.

  • Request an item ID that belongs to another workspace with this key and expect a clean 404, never the item.
  • List your datasets with GET /api/datasets/YOUR_DATASET_ID/items and confirm only intended items appear.
  • If a dataset is meant to stay private, confirm its items do not surface on public pages while signed out.
Step 5

Failure Handling

Exercise the failure paths on purpose, so your integration's error handling is tested before production traffic finds it.

  • No auth: repeat any call without the Authorization header and expect 401 (on MCP, with a WWW-Authenticate header pointing at the discovery metadata).
  • Invalid ID: fetch a nonexistent item and expect a structured 404 error body, not HTML.
  • Missing arguments: POST a search without a query and expect a structured 400.
  • Rate limits: read the x-ratelimit-limit / -remaining / -reset headers on responses, and back off when you receive 429. Retrying into a limit extends it.
  • Quota: plan limits (searches, transcription minutes, storage) return structured errors when exceeded. Surface them to your users rather than swallowing them. Current usage is on your workspace's Usage page.
Step 6

Keep It Tested

A passing check from onboarding week proves little in month three. Turn the two checks that matter into a scheduled canary:

  • Run the Step 3 upload round-trip on a schedule (daily is typical) and after every deploy of your own system, asserting all four pass conditions.
  • Run one Step 2 search for a phrase your canary clip contains, asserting it matches.
  • Alert on failure through whatever paging you already use. A canary nobody watches is a log file.

Then grow the canary into a small golden set: five to ten queries grounded in your own corpus, each paired with the item or phrase it must return. Run the set on the same schedule and alert when any golden query stops matching. Phrase expectations to stay true as your corpus grows: assert that a known item appears, not that a query returns an exact count. This is the same approach agent platforms use to evaluate connectors before listing them, and it catches silent regressions in indexing, permissions, and relevance that no single smoke test will.

This is the same pattern Audioscrape runs against its own upload path in production, and it catches integration-level regressions that unit tests structurally cannot: expired keys, changed dataset permissions, and quota exhaustion.

Next

Going Further

The interactive API explorer at /api/docs/swagger covers every endpoint used above. For MCP client setup, start from the MCP Overview. Enterprise plans include isolated evaluation workspaces with seeded test data for integration certification. Ask at [email protected].

Previous
Cursor
Next
Testing Over MCP