API for assistants

Let an assistant such as Muse read what your secretary heard and give her instructions.

Basics

Base address: https://api.gurusecretary.com/v1. This is the only host the API uses. Recording links point to gurusecretary.com.
Auth: Authorization: Bearer <key>. Each account makes, names and revokes its own keys on the dashboard's Connect tab. A revoked key stops working at once. Keys are never accepted in the address, a cookie or the body.
Scopes: read:calls, read:messages, read:appointments, write:calls, write:messages, write:appointments, write:agent.
JSON in and out. Times are ISO 8601 UTC. Phone numbers are E.164. Lists return data, has_more and next_cursor.
Errors: { "error": { "code", "message" } }. 401 bad key, 403 missing scope, 404 not found, 409 conflict, 422 bad input, 429 rate limited, 503 not available.
Rate limit: 120 requests a minute per key. A 429 carries Retry-After.

Endpoints

Request	Scope	What it does
`GET /v1/me`	any	Harmless check that the key works: account, key scopes, lines, whether outbound calling is on.
`GET /v1/calls?from=&to=&direction=&status=&limit=&cursor=`	read:calls	Calls, newest first.
`GET /v1/calls/{id}`	read:calls	One call with `transcript` and `recording_url` (signed, good for one hour).
`POST /v1/calls`	write:calls	The secretary places a call. Body: `to`, `from_line`, `script` (or `instructions` / `purpose`), `idempotency_key`, optional `to_name`, `team`. Returns `call_id` and `status`. Final once accepted.
`GET /v1/voicemails`	read:calls	Always empty: calls are answered live. Silent calls are in `/v1/calls` with status `missed`.
`GET /v1/messages?thread=`	read:messages	Texts in and out, newest first.
`POST /v1/messages`	write:messages	Send a text from the secretary's number. Body: `to`, `text`, `idempotency_key`. Final once sent.
`GET /v1/appointments`	read:appointments	Upcoming appointments.
`POST /v1/appointments`	write:appointments	Book an open slot. Body: `at`, `service`, `caller_name`, `callback_number`, `note`. 409 when the time is not open.
`PATCH` / `DELETE /v1/appointments/{id}`	write:appointments	Move (send a new `at`) or cancel. The id is the appointment's `at` time.
`GET /v1/agent`	any	Greeting, instructions, services, FAQ, hours, languages, lines.
`PATCH /v1/agent`	write:agent	Change `greeting`, `instructions`, `services`, `faq`, `name`, `hours`. The voice agent rebuilds in about a minute.

Call fields: id, direction, from, to, team, agent_id, started_at, ended_at, duration_seconds, status, outcome, urgent, caller_name, callback_number, summary, action_items, appointment, read, plus transcript and recording_url on a single call. Status is in_progress, completed, missed or failed.

Outbound calls and texts

Confirm the recipient, the line and the script with the account owner before every request. A call or text cannot be taken back.
idempotency_key is required. Sending the same key again returns the first result and never dials or texts twice.
from_line is required and must be one of the account's own lines. There is no silent default.
We never re-dial. If placing the call fails you get status failed with the reason.
Poll GET /v1/calls/{call_id} or wait for the call.completed webhook for the result and transcript.
Outbound calling is switched on per deployment. GET /v1/me says whether it is on; when it is off, POST /v1/calls returns 503 and dials nothing.

curl https://api.gurusecretary.com/v1/me -H "Authorization: Bearer $KEY"

curl -X POST https://api.gurusecretary.com/v1/calls -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{
  "to": "+13135550100", "to_name": "Ali", "from_line": "+13139924441",
  "script": "Confirm the brake appointment for Thursday at 2:00 PM.",
  "idempotency_key": "2026-11-12-ali-confirm" }'

Webhooks

Set one address on the Connect tab. Events: call.completed, call.missed, call.placed, sms.received, appointment.booked, appointment.changed.
Body: { id, type, created_at, account_id, team, data }. Call events carry the call object with its summary, so an alert needs no second fetch.
Signature header: X-GuruSecretary-Signature: t=<unix>,v1=<hex>, where v1 is HMAC-SHA256 of "<t>.<raw body>" with your signing secret.
Each event has a unique id; ignore one you have already handled. A failed delivery is retried twice within a few seconds. Use the API to catch up on anything missed.

Email summaries

With no connection at all: one email per call to the report address, subject [Guru Secretary] Call - {caller} - {outcome}, then caller, number, time, outcome, summary, action items, appointment and the full transcript below a divider.