Recording API Reference

All Recording endpoints are prefixed with /api/v1/agent/founder/ and require JWT authentication with a founder-authorized role.

Base URL

Production:  https://api.olympuscloud.ai/api/v1/agent/founder
Development: https://dev.api.olympuscloud.ai/api/v1/agent/founder

Endpoints

Upload Recording

Upload an audio file with metadata for transcription and CRM linking.

POST /recordings/upload
Content-Type: multipart/form-data

Form Fields:

Field	Type	Required	Description
file	binary	Yes	Audio file (WAV, MP3, M4A, OGG, WEBM)
type	string	Yes	phone, in_person, video, voice_memo
source	string	No	Source identifier (e.g., twilio, google_meet, manual)
contact_ids	string (JSON array)	No	CRM contact IDs to link
deal_id	string	No	CRM deal ID to link
consent_status	string	Yes	all_consented, one_party, pending

Response:

{
  "id": "rec_uuid",
  "status": "processing",
  "audio_url": "gs://olympus-recordings/rec_uuid.wav",
  "estimated_duration_seconds": 720,
  "transcription_status": "queued",
  "created_at": "2026-02-28T10:00:00Z"
}

Async Processing

Transcription is asynchronous. The recording is immediately stored, and transcription completes within 1-5 minutes depending on duration and STT tier selected.

List Recordings

GET /recordings

Query Parameters:

Parameter	Type	Description
contact_id	string	Filter by linked contact
deal_id	string	Filter by linked deal
type	string	Filter by recording type
date_from	string (ISO 8601)	Start date filter
date_to	string (ISO 8601)	End date filter
page	int	Page number
per_page	int	Results per page (default: 20)

Get Recording Detail

GET /recordings/{id}

Response:

{
  "id": "rec_uuid",
  "type": "phone",
  "source": "twilio",
  "contact_ids": ["contact_uuid_1"],
  "deal_id": "deal_uuid",
  "duration_seconds": 720,
  "audio_url": "gs://olympus-recordings/rec_uuid.wav",
  "transcript_text": "Speaker 1: Thank you for calling...",
  "summary": "Discussed Q3 renewal pricing. Customer requested 10% discount...",
  "action_items": [
    {"text": "Send updated proposal by Friday", "assignee": "founder"},
    {"text": "Schedule follow-up call next week", "assignee": "founder"}
  ],
  "sentiment_score": 0.82,
  "speaker_diarization": [
    {"speaker": "Speaker 1", "contact_id": "contact_uuid_1", "segments": [...]},
    {"speaker": "Speaker 2", "contact_id": null, "segments": [...]}
  ],
  "consent_status": "all_consented",
  "created_at": "2026-02-28T10:00:00Z"
}

Get Full Transcript

GET /recordings/{id}/transcript

Returns the full transcript with speaker diarization, timestamps per segment, and entity extraction annotations.

Link Recording to CRM

POST /recordings/{id}/link

Request:

{
  "contact_ids": ["contact_uuid_1", "contact_uuid_2"],
  "deal_id": "deal_uuid"
}

Contact Interaction Timeline

Get the full interaction timeline for a CRM contact, including recordings, emails, SMS, meetings, and notes.

GET /contacts/{id}/timeline

Query Parameters:

Parameter	Type	Description
types	string	Comma-separated: recording, email, sms, meeting, note
date_from	string	Start date filter
date_to	string	End date filter

Response:

{
  "contact": {
    "id": "contact_uuid",
    "name": "Jane Smith",
    "company": "Acme Corp"
  },
  "timeline": [
    {
      "type": "recording",
      "id": "rec_uuid",
      "date": "2026-02-27T14:00:00Z",
      "summary": "Discussed pricing for Q3 renewal",
      "sentiment_score": 0.82,
      "duration_seconds": 720,
      "action_items": ["Send updated proposal"]
    },
    {
      "type": "email",
      "id": "email_uuid",
      "date": "2026-02-25T09:30:00Z",
      "subject": "RE: Partnership Opportunity",
      "preview": "Thank you for the follow-up..."
    }
  ]
}

CRM Semantic Search

RAG-powered semantic search across all CRM conversations.

GET /crm/search

Query Parameters:

Parameter	Type	Description
q	string	Natural language search query
contact_id	string	Scope search to specific contact
limit	int	Max results (default: 10)

Example: GET /crm/search?q=pricing objections from restaurant prospects

Response:

{
  "results": [
    {
      "type": "recording_segment",
      "recording_id": "rec_uuid",
      "contact_name": "Jane Smith",
      "snippet": "...we think the pricing is a bit high compared to Toast...",
      "relevance_score": 0.94,
      "timestamp_seconds": 245
    }
  ]
}

Error Responses

Code	HTTP Status	Description
RECORDING_NOT_FOUND	404	Recording not found
CONTACT_NOT_FOUND	404	CRM contact not found
INVALID_AUDIO_FORMAT	422	Unsupported audio file format
CONSENT_REQUIRED	422	Recording consent status not provided
TRANSCRIPTION_FAILED	500	STT pipeline error

Related Documentation

• Conversation Recording Guide — User guide
• Founder API Reference — All Founder endpoints
• Production-Ready Standards — Recording consent compliance