Getting Started with the Echosaw REST API: A Developer's Guide

The Echosaw REST API provides programmatic access to our media intelligence platform, enabling you to integrate automated media analysis into your custom workflows. This guide covers the essentials for developers building with our API.

Authentication

API access requires a valid API key issued through your Echosaw account. Your API key is provided in your welcome email and is shown only once—it's not recoverable, so store it securely. Authentication is straightforward: include your API key in the X-Api-Key header for all requests to /v1/ endpoints.

curl -H "X-Api-Key: your-api-key" \
  https://api.echosaw.com/v1/analyze \
  -H "Content-Type: application/json" \
  -d '{"mediaType": "video", "url": "https://example.com/video.mp4"}'

Rate Limits

API requests are subject to rate limits based on your subscription plan. These limits are enforced at the API Gateway level and help ensure fair usage across all customers:

• Starter: 10 requests/second, 1,000 requests/day
• Growth: 25 requests/second, 5,000 requests/day
• Pro: 50 requests/second, 10,000 requests/day
• Agency: 100 requests/second, 50,000 requests/day

Exceeding these limits will result in HTTP 429 responses. Design your integration with appropriate backoff and retry logic to handle throttling gracefully.

Core Endpoints

The API exposes several key endpoints for media analysis workflows:

POST /v1/analyze — Submit media for analysis. You can upload files directly or provide a URL. The response includes a mediaId that you'll use to track progress and retrieve results. GET /v1/analysis/status/{mediaId} — Check the processing status of your analysis job. Returns the current state (queued, processing, completed, or failed) along with progress information. GET /v1/analysis/results/{mediaId} — Retrieve the complete intelligence report once analysis is complete. This includes transcripts, content moderation signals, sentiment analysis, visual labels, and AI-generated summaries. GET /v1/media/search — Perform semantic search across your analyzed media library using natural language queries. Returns ranked results with relevance scores and metadata.

Common Integration Patterns

A typical integration follows this pattern: submit media for analysis, poll for status, then retrieve results. For asynchronous workflows, consider implementing webhooks or using our WebSocket updates for real-time status notifications.

When building production integrations, always handle errors gracefully, implement exponential backoff for retries, and respect rate limits. Your API key is tied to your subscription plan's entitlements, so ensure your plan matches your expected usage volume.