API Reference

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.

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&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

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

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

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