Overview

The Echosaw REST API lets you programmatically submit media for analysis, poll for processing status, retrieve intelligence results, and search your media library. All endpoints live under the /v1/ path prefix.

Getting Started

1. Subscribe — Choose a Developer, Growth, Pro, or Agency plan. Your API key and base URL are delivered in the welcome email.
2. Authenticate — Include your API key in every request using the X-Api-Key header. No other credentials are required.
3. Submit media — Call POST /v1/analyze with the media type and filename. You will receive a pre-signed upload URL.
4. Upload the file — PUT your file to the upload URL returned in step 3.
5. Poll for status — Call GET /v1/analysis/status/{mediaId} until the status is complete.
6. Retrieve results — Call GET /v1/analysis/results/{mediaId} to fetch the full intelligence report.

Base URL

Your API base URL is included in the welcome email you received at subscription time. All /v1/ paths are relative to this base URL.

https://api.echosaw.com/v1/

If your welcome email contains a different base URL, use that instead.

Authentication

Every request must include an X-Api-Key header containing the API key from your welcome email. No other credentials or tokens are required.

X-Api-Key: your-api-key

Your API key is shown once in the welcome email and is not recoverable. Store it securely. If your key is lost or compromised, contact support for a replacement.

Endpoints

POST /v1/analyze

Submit media for analysis. Returns a job ID and a pre-signed upload URL.

Request Body

Example Request

curl -X POST https://api.echosaw.com/v1/analyze \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaType": "video",
    "originalFilename": "interview.mp4",
    "fileSize": 52428800,
    "contentType": "video/mp4"
  }'

Response 200 OK

{
  "jobId": "38be3491-b9a4-446f-b3f5-95380576baf4",
  "mediaId": "38be3491-b9a4-446f-b3f5-95380576baf4",
  "uploadUrl": "https://...presigned-s3-url..."
}

After receiving the response, upload your file with a PUT request to the uploadUrl. The URL expires in 15 minutes.

curl -X PUT "UPLOAD_URL_FROM_RESPONSE" \
  -H "Content-Type: video/mp4" \
  --data-binary @interview.mp4

GET /v1/analysis/status/{mediaId}

Poll for the current processing status of a submitted job.

Path Parameters

Example Request

curl https://api.echosaw.com/v1/analysis/status/38be3491-b9a4-446f-b3f5-95380576baf4 \
  -H "X-Api-Key: your-api-key"

Response 200 OK

{
  "mediaId": "38be3491-b9a4-446f-b3f5-95380576baf4",
  "status": "processing",
  "createdAt": 1773087339,
  "updatedAt": 1773087726
}

Status Values

GET /v1/analysis/results/{mediaId}

Retrieve the full intelligence report for a completed analysis. Only returns data when status is complete.

Path Parameters

Example Request

curl https://api.echosaw.com/v1/analysis/results/38be3491-b9a4-446f-b3f5-95380576baf4 \
  -H "X-Api-Key: your-api-key"

Response 200 OK

{
  "videoId": "38be3491-...",
  "mediaType": "VIDEO",
  "createdAt": "2026-03-09T20:15:39.000Z",
  "summary": {
    "title": "string",
    "description": "string",
    "primarySubject": "string",
    "categories": "string"
  },
  "transcript": {
    "fullText": "string",
    "wordCount": 0,
    "languageCode": "en-US"
  },
  "safety": {
    "overallRating": "string",
    "categories": {}
  },
  "insights": {
    "sentiment": "string",
    "entities": [],
    "contentSignals": {}
  },
  "metadata": {
    "durationSec": 0,
    "format": "string",
    "resolution": "string"
  },
  "thumbnailUrl": "string",
  "thumbnails": [],
  "location": {
    "displayName": "string",
    "coordinates": { "lat": 0, "lon": 0 }
  },
  "downloads": {
    "intelligenceReport": "presigned URL",
    "transcript": "presigned URL"
  }
}

Response fields vary by media type (video, audio, image) and subscription tier. Higher tiers include additional fields such as transcript segments, visual intelligence, and semantic analysis.

GET /v1/media/locker

List all media items in your library.

Example Request

curl https://api.echosaw.com/v1/media/locker \
  -H "X-Api-Key: your-api-key"

Response 200 OK

{
  "items": [
    {
      "mediaId": "string (UUID)",
      "fileName": "string",
      "originalFilename": "string | null",
      "mediaType": "VIDEO | AUDIO | IMAGE",
      "status": "COMPLETE | UPLOADED_PENDING_SCAN | PROCESSING | FAILED",
      "uploadedAt": 1773089776,
      "durationSec": 12.7,
      "fileSize": "50.00 MB",
      "fileSizeBytes": 52428800,
      "contentType": "video/mp4"
    }
  ],
  "count": 1
}

GET /v1/media/search

Semantic search across your analyzed media library.

Query Parameters

Example Request

curl "https://api.echosaw.com/v1/media/search?q=outdoor+wildlife" \
  -H "X-Api-Key: your-api-key"

Response 200 OK

{
  "query": "outdoor wildlife",
  "resultCount": 3,
  "results": [
    {
      "mediaId": "string (UUID)",
      "mediaType": "VIDEO",
      "title": "string",
      "summary": "string",
      "transcriptSnippet": "string",
      "labels": ["Animal", "Nature", "Outdoors"],
      "tags": ["wildlife", "nature"],
      "durationSec": 12.7,
      "createdAt": 1773087339,
      "score": 0.95
    }
  ],
  "searchType": "semantic"
}

Rate Limits

Rate limits are enforced per API key based on your subscription tier. Exceeding the limit returns 429 Too Many Requests.

Error Responses

All errors return JSON with an error field and the appropriate HTTP status code.

Example Error Response

{
  "error": "Authentication required"
}