Meetings API

CRUD operations for Voilo Meetings – a Meeting is a live instance of an Assistant that actually joins a call, streams the transcript, answers questions, and calls tools in real‑time.

Looking for auth, base URLs, pagination, or error formats? Head over to API Foundations.

Endpoints at a glance

Method & Path	Purpose
POST /v1/meetings	Create (start) a new Meeting
GET /v1/meetings	List Meetings (cursor‑paginated)
GET /v1/meetings/{id}	Show a Meeting
PATCH /v1/meetings/{id}	Update a Meeting (pause/resume/rename)
DELETE /v1/meetings/{id}	Delete (soft‑archive) a Meeting
GET /v1/meetings/{id}/transcript	Get the Meeting transcript

Meeting object schema

Field	Type	Description
id	string	Unique identifier for the Meeting (prefixed mtg_).
assistant_id	string	Assistant template the Meeting was initialized from.
meeting_url	string	The dial‑in URL Voilo should join.
name	string?	Friendly label shown in dashboards.
status	string	Current lifecycle state (see Statuses).
started_at	timestamp	UTC ISO‑8601 when the Assistant attempted to join.
ended_at	timestamp?	When the Assistant left or the Meeting was terminated.
duration_seconds	integer?	Calculated difference between started_at and ended_at.
language	string	BCP‑47 code for the dominant language.
audio_url	string	REST endpoint that returns audio recording.
video_url	string	REST endpoint that returns video recording.
tool_results_url	string	Endpoint exposing past tool call outputs.
realtime_endpoint	object?	Realtime endpoint for streaming transcription, audio, or video.
metadata	object?	Free‑form JSON (< 16 KB) for your app’s needs.

Statuses

Value	Meaning
queued	Meeting created, waiting for connection worker.
connecting	Connection in progress.
joined	Assistant is in the call but hasn’t heard speech yet.
listening	Streaming audio and transcripts in real‑time.
completed	Meeting ended gracefully; transcript sealed.
paused	Temporarily suspended (via PATCH).
failed	Meeting aborted due to an unrecoverable error.

Tip: Intermediate statuses (connecting, joined, listening) typically advance in less than 5 seconds each.

Realtime endpoint

Use realtime_endpoint as Meeting parameter to stream transcription, audio, or video in real-time. You can use ngrok (or any tunnel) for local dev:

ngrok http 8080   # exposes http://<id>.ngrok.app

Field	Type	Description
type	string	transcription
url	string	The URL to stream the transcription, audio, or video.

Create a Meeting

POST /v1/meetings

Example request

curl -X POST https://api.voilo.io/meetings \
  -H "Authorization: Bearer $VOILO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "asst_456",
    "meeting_url": "https://meet.google.com/abc-defg-hij",
    "name": "Daily Scrum – 2025‑06‑17",
    "metadata": { "team": "backend" }
  }'

Response 201 Created

{
  "id": "mtg_123",
  "status": "queued",
}

Error responses

Code	HTTP Status	When it happens
meeting_url_invalid	400	URL can’t be parsed or isn’t supported.
assistant_not_found	404	assistant_id is unknown.
meeting_limit_reached	429	Your org hit the concurrency cap.

List Meetings

GET /v1/meetings

Filtering

Query param	Type	Default	Purpose
cursor	string?	–	Cursor returned from previous page.
limit	integer?	20	Max objects per page (1–100).
assistant_id	string?	–	Filter by Assistant.
status	string?	–	Filter by lifecycle state.
started_after	timestamp?	–	Return Meeting that began after this UTC time.
started_before	timestamp?	–	Return Meeting that began before this UTC time.

Example request

curl "https://api.voilo.io/meetings?assistant_id=asst_456&status=completed" \
  -H "Authorization: Bearer $VOILO_API_KEY"

Response 200

{
  "data": [ /* array of Meeting objects */ ],
  "next_cursor": "MjAyNS0wNi0xMFQxNDo1MDozMFo",
  "has_more": true
}

Cursor semantics live in API Foundations → Pagination.

Show a Meeting

GET /v1/meetings/{id}

Example request

curl https://api.voilo.io/meeting/mtg_123 \
  -H "Authorization: Bearer $VOILO_API_KEY"

200 OK – returns the Meeting object.

404 Not Found – ID unknown or archived.

Update a Meeting

PATCH /v1/meetings/{id}

Body param	Type	Notes
name	string?	Rename the Meeting.
paused	boolean?	true → pause, false → resume.
completed	boolean?	true → force Assistant to leave the call.
metadata	object?	Replace entire metadata blob.

Example request

curl -X PATCH https://api.voilo.io/meetings/mtg_123 \
  -H "Authorization: Bearer $VOILO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "paused": true }'

200 OK – returns the updated resource.

Delete (archive) a Meeting

DELETE /v1/meetings/{id}

Soft‑archives the Meeting. Transcript & tool results remain readable.

curl -X DELETE https://api.voilo.io/meetings/mtg_123 \
  -H "Authorization: Bearer $VOILO_API_KEY"

204 No Content – the Assistant is now archived.

Get Meeting transcript

GET /v1/meetings/{id}/transcript

Returns the full transcript of the Meeting as a JSON object containing all spoken segments with timestamps, speaker identification, and confidence scores.

Example request

curl https://api.voilo.io/meetings/mtg_123/transcript \
  -H "Authorization: Bearer $VOILO_API_KEY"

Response 200 OK

{
  "transcript": {
    "segments": [
      {
        "id": "segment_001",
        "start": 0.0,
        "end": 3.2,
        "text": "Hello everyone, let's start the meeting.",
        "speaker": "John Doe",
        "confidence": 0.95
      },
      {
        "id": "segment_002",
        "start": 3.5,
        "end": 7.1,
        "text": "Thanks John. I'll share my screen now.",
        "speaker": "Jane Smith",
        "confidence": 0.92
      }
    ],
    "duration_seconds": 1800,
    "language": "en-US",
    "summary": "Team meeting discussing project status and next steps."
  }
}

Error responses

Code	HTTP Status	When it happens
meeting_not_found	404	Meeting ID is unknown or archived.
transcript_not_ready	409	Meeting is still in progress or transcript processing incomplete.

Error handling recap

All non‑2xx responses follow the shared envelope documented in API Foundations → Error Envelope. For example:

{
  "error": {
    "code": "invalid_auth",
    "message": "API key expired"
  }
}

See also

• Assistant Configuration – how to wire prompts & tools.
• API Foundations – base URLs, auth, pagination, and errors.