API Reference

Last updated: September 11, 2026

Overview

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

Getting Started

Subscribe — Choose a Starter, Growth, Pro, or Agency plan. Your API key and base URL are delivered in the welcome email.
Authenticate — Include your API key in every request using the X-Api-Key header. No other credentials are required.
Submit media — Call POST /v1/analyze with the media type and filename. You will receive a pre-signed upload URL.
Upload the file — PUT your file to the upload URL returned in step 3.
Poll for status — Call GET /v1/analysis/status/{mediaId} until the status is complete.
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

Field	Type	Required	Description
`mediaType`	string	Yes	One of `video`, `audio`, `image`, or `document` (PDF, TXT, MD, PPTX)
`originalFilename`	string	No	Original filename for reference
`fileSize`	number	No	File size in bytes
`contentType`	string	No	MIME type (e.g. `video/mp4`)

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

POST /v1/analyze/url

Submit a publicly accessible media or document URL, or a video platform URL (YouTube, Rumble, Vimeo, etc.). Echosaw downloads the file and starts analysis; no upload step is required.

Request Body

Field	Type	Required	Description
`url`	string	Yes	HTTP(S) URL of the file or platform page
`mediaType`	string	Yes	One of `video`, `audio`, `image`, or `document`
`originalFilename`	string	No	Filename to record for the item

Example Request

curl -X POST https://api.echosaw.com/v1/analyze/url \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "mediaType": "video"
  }'

Response `200 OK`

{
  "jobId": "38be3491-b9a4-446f-b3f5-95380576baf4",
  "mediaId": "38be3491-b9a4-446f-b3f5-95380576baf4"
}

GET /v1/analysis/status/{mediaId}

Poll for the current processing status of a submitted job.

Path Parameters

Parameter	Type	Description
`mediaId`	string (UUID)	The `mediaId` returned by `POST /v1/analyze`

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

Status	Description
`pending`	Upload received, awaiting processing
`processing`	Analysis in progress
`complete`	Analysis finished — results are ready
`failed`	Analysis encountered an error

GET /v1/analysis/results/{mediaId}

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

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, document) 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 | DOCUMENT",
      "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. Each item is matched on its summary-level embedding, on 60-second spoken transcript windows, and on visual frame/clip embeddings for video; the best spoken or visual hit supplies the item’s timestampSec. Results are ordered by score, a vector distance where lower is a closer match. Soft-deleted and failed items are excluded.

Query Parameters

Parameter	Type	Required	Description
`q`	string	Yes	Search query (natural language supported, including phrases someone said)
`scope`	string	No	One of `mine` (default), `org` (your organization’s shared media; requires org membership), or `public` (Public Library)
`mediaType`	string	No	Filter by media type. One of `VIDEO`, `AUDIO`, `IMAGE`, `DOCUMENT`
`status`	string	No	Filter by job status (e.g. `COMPLETE`)
`sentiment`	string	No	Filter by report sentiment: `positive`, `negative`, `neutral`, or `mixed`

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"],
      "contentWarnings": [],
      "durationSec": 12.7,
      "createdAt": 1773087339,
      "score": 0.31,
      "location": "string",
      "ownerEmail": "string",
      "timestampSec": 42,
      "thumbnailUrl": "string (presigned URL) | null",
      "matchReasons": ["Spoken at 0:42", "Tagged \"wildlife\""]
    }
  ],
  "searchType": "semantic"
}

timestampSec is the moment in the media that matched (spoken or visual), or null when the item matched on its summary only. Link to it with /report/{mediaId}/?t={timestampSec}. matchReasons lists human-readable reasons the item matched.

POST /v1/media/ask

Ask a natural-language question and receive an answer synthesized from your analyzed media (retrieval-augmented generation over summaries, transcripts, and the most relevant spoken passages). The response cites the media it drew from.

Request Body

Field	Type	Required	Description
`question`	string	Yes	The question to answer
`mediaIds`	string[]	No	Restrict the question to these media items. When omitted, the most relevant media in your library is retrieved automatically.
`conversationId`	string	No	Continue a prior conversation (returned by an earlier response). A new one is created when omitted.

Example Request

curl -X POST https://api.echosaw.com/v1/media/ask \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "question": "What did the speaker say about pricing?" }'

Response `200 OK`

{
  "answer": "string",
  "sources": [
    { "mediaId": "string (UUID)", "title": "string", "mediaType": "VIDEO" }
  ],
  "question": "What did the speaker say about pricing?",
  "conversationId": "string",
  "turnId": "string"
}

sources is empty when no matching media was found or the question was answered from platform knowledge.

GET /v1/media/library

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

Query Parameters

Parameter	Type	Required	Description
`folderPath`	string	No	Filter by folder path (default: "/" for root)
`limit`	number	No	Max items per page (default: 25)
`nextToken`	string	No	Pagination cursor from previous response
`includeSubfolders`	boolean	No	Include subfolder listing (default: false)
`mediaType`	string	No	Filter by media type. One of `VIDEO`, `AUDIO`, `IMAGE`, `DOCUMENT`
`status`	string	No	Filter by job status (e.g. `COMPLETE`, `PROCESSING`, `FAILED`)
`sentiment`	string	No	Filter by report sentiment. One of `positive`, `negative`, `neutral`, `mixed`

Example Request

curl "https://api.echosaw.com/v1/media/library?folderPath=/Marketing&limit=10&mediaType=VIDEO&status=COMPLETE" \
  -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

Parameter	Type	Required	Description
`name`	string	Yes	Folder display name
`parentPath`	string	No	Parent folder path (default: "/")

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": "/"}'

PATCH /v1/media/library/folder

Rename an existing folder in your media library.

Request Body

Parameter	Type	Required	Description
`folderPath`	string	Yes	Current folder path to rename
`newName`	string	Yes	New display name for the folder

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

DELETE /v1/media/library/folder

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

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

PATCH /v1/media/library/move

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

Request Body

Parameter	Type	Required	Description
`mediaIds`	string[]	Yes	Array of mediaId strings to move
`targetFolderPath`	string	Yes	Destination folder path

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

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.

Tier	Requests / sec	Burst	Daily Quota
Starter	10	20	1,000
Growth	25	50	5,000
Pro	50	100	10,000
Agency	100	200	50,000

Error Responses

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

Status	Meaning	Common Cause
`400`	Bad Request	Missing or invalid parameters
`403`	Forbidden	Invalid API key or accessing another user's resource
`404`	Not Found	Resource does not exist or has not been processed
`429`	Too Many Requests	Rate limit exceeded — back off and retry
`500`	Internal Server Error	Unexpected error — contact support if persistent

Example Error Response

{
  "error": "Authentication required"
}

API Reference

Overview

Getting Started

Base URL

Authentication

Endpoints

POST /v1/analyze

Request Body

Example Request

Response 200 OK

POST /v1/analyze/url

Request Body

Example Request

Response 200 OK

GET /v1/analysis/status/{mediaId}

Path Parameters

Example Request

Response 200 OK

Status Values

GET /v1/analysis/results/{mediaId}

Example Request

Response 200 OK

GET /v1/media/locker

Example Request

Response 200 OK

GET /v1/media/search

Query Parameters

Example Request

Response 200 OK

POST /v1/media/ask

Request Body

Example Request

Response 200 OK

GET /v1/media/library

Query Parameters

Example Request

Response 200 OK

POST /v1/media/library/folder

Request Body

Example Request

PATCH /v1/media/library/folder

Request Body

Example Request

DELETE /v1/media/library/folder

Example Request

PATCH /v1/media/library/move

Request Body

Example Request

Organization Management

Rate Limits

Error Responses

Example Error Response

Response `200 OK`

Response `200 OK`

Response `200 OK`

Response `200 OK`

Response `200 OK`

Response `200 OK`

Response `200 OK`

Response `200 OK`