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 Starter, 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"
}

GET /v1/media/library

List media items and folders in your library. Supports folder filtering and pagination.

Query Parameters

Example Request

curl "https://api.echosaw.com/v1/media/library?folderPath=/Marketing&limit=10" \
  -H "X-Api-Key: your-api-key"

Response 200 OK

{
  "items": [
    {
      "mediaId": "string (UUID)",
      "fileName": "interview.mp4",
      "mediaType": "VIDEO",
      "status": "COMPLETE",
      "folderPath": "/Marketing",
      "reportTitle": "Product Launch Interview",
      "reportSentiment": "positive",
      "uploadedAt": 1773087339,
      "durationSec": 312,
      "thumbnailUrl": "string (presigned URL)"
    }
  ],
  "folders": [
    {
      "folderPath": "/Marketing/Q1 2026",
      "displayName": "Q1 2026",
      "parentPath": "/Marketing",
      "createdAt": 1773087339,
      "itemCount": 5
    }
  ],
  "count": 1,
  "nextToken": "string | null"
}

POST /v1/media/library/folder

Create a new folder in your media library.

Request Body

Example Request

curl -X POST "https://api.echosaw.com/v1/media/library/folder" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Marketing", "parentPath": "/"}'

Response 200 OK

{
  "folderPath": "/Marketing",
  "displayName": "Marketing",
  "parentPath": "/",
  "createdAt": 1773087339
}

PATCH /v1/media/library/folder

Rename an existing folder in your media library.

Request Body

Example Request

curl -X PATCH "https://api.echosaw.com/v1/media/library/folder" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"folderPath": "/Marketing", "newName": "Brand & Marketing"}'

Response 200 OK

{
  "folderPath": "/Brand & Marketing",
  "displayName": "Brand & Marketing",
  "parentPath": "/"
}

DELETE /v1/media/library/folder

Delete a folder from your media library. Items in the folder are moved to the parent folder by default.

Request Body

Example Request

curl -X DELETE "https://api.echosaw.com/v1/media/library/folder" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"folderPath": "/Old Campaigns", "moveItemsToParent": true}'

Response 200 OK

{
  "deleted": true,
  "folderPath": "/Old Campaigns"
}

PATCH /v1/media/library/move

Move one or more media items to a different folder in your library.

Request Body

Example Request

curl -X PATCH "https://api.echosaw.com/v1/media/library/move" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"mediaIds": ["38be3491-b9a4-446f-b3f5-95380576baf4"], "targetFolderPath": "/Marketing"}'

Response 200 OK

{
  "moved": 1,
  "targetFolderPath": "/Marketing"
}

Organization Management

Organization management (create, invite, manage members) is available via the Echosaw web interface at /organization and through Cognito-authenticated API endpoints. These endpoints are not part of the /v1/ API key-authenticated API.

For programmatic access to organization data, use the echosaw_get_organization MCP tool, which returns your organization details, members, and roles.

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"
}