Meetings API
Read your meeting history over HTTP: meetings, transcripts with timestamps, summaries and summary templates, action items, questions and recordings, with a meetings:read secret key.
The Meetings API lets your own code read the meetings Safeguard has captured for you. It is read-only. You can list meetings, fetch a transcript with timestamps, read a summary (and the summary templates behind it), list action items and questions, and get a short-lived link to a recording.
- Base URL:
https://api.safeguard.sh/gpt/v1 - Authentication:
Authorization: Bearer sg_sk_... - Scope:
meetings:read - Format: JSON, UTF-8. Transcripts are kept in their original script, so Hindi, Devanagari and Hinglish come back as spoken.
The workspace needs meetings turned on. Without it, every route answers 404 not_found as if the API did not exist.
Create a key
- Open Settings and choose Secret keys. In the Console, the same page is under Console > Settings > Secret keys.
- Choose Create key and set the kind to Meetings.
- Copy the key from the dialog. This is the only time the full key is shown.
A Meetings key carries one scope, meetings:read, and no other. It cannot be limited to an organization, project, product or agent. Revoke it on the same page at any time; a revoked key is refused within a short time.
A key made for another purpose, such as an inference, MCP, Guard or CI key, is refused here with 403 insufficient_scope. A Meetings key cannot call any other Safeguard API.
Authentication
Send the key in the Authorization header of every request:
curl https://api.safeguard.sh/gpt/v1/meetings \
-H "Authorization: Bearer $SAFEGUARD_MEETINGS_KEY"The examples on this page read the key from SAFEGUARD_MEETINGS_KEY. Any name works. Keep the key on your servers and never put it in browser code or a public repository.
What a key can see
A key acts as the person who created it.
- It reads that person's own meetings: the ones they sent a Safeguard agent to or recorded. Meetings other people shared with them are read in the Safeguard app.
- It never sees other people's meetings. A workspace administrator's key sees no more than any other key: there is no admin widening for keys.
- Participant emails and the owner's email are returned only on meetings that belong to the key's owner.
shared_withandmeeting_urlare returned for the owner's own meetings.- A meeting the key cannot see answers
404 not_found, the same as a meeting that does not exist. - On an agent's calendar, a meeting the key's owner may not see appears only as a busy block: an id, a start and an end, with no title, people, link or anything else.
Endpoints
All paths below are relative to the base URL.
| Method | Path | Returns |
|---|---|---|
| GET | /meetings | A page of meetings |
| GET | /meetings/summary-templates | The summary templates |
| GET | /meetings/{id} | One meeting in full |
| GET | /meetings/{id}/transcript | The transcript segments |
| GET | /meetings/{id}/summary | The meeting's summary |
| GET | /meetings/{id}/action-items | The action items |
| GET | /meetings/{id}/questions | Questions asked by each side |
| GET | /meetings/{id}/recording | Signed links to the recording |
| GET | /meetings/agents | The meeting agents whose calendars the key can read |
| GET | /meetings/agents/{agent_id}/events | One agent's calendar between two dates |
List meetings
GET /meetings
| Query parameter | Meaning |
|---|---|
from, to | ISO 8601 date or time, applied to the meeting's start. |
q | Text to find in the title, the summary or participant names. |
platform | One of google_meet, teams, zoom, webex, slack, whereby, jitsi, safeguard_meet, discord, goto, whatsapp, other. |
status | in_progress, completed or failed. |
view | all (default), mine or team. Over the API, all and mine return the key owner's own meetings and team returns none. |
source | safeguard, or the id of the note taker an imported meeting came from. |
participant | Text to find in a participant's name or email. |
has_action_items | true or false. |
audience | internal, external or unknown. |
assigned | me for meetings with an open action item assigned to the key's owner. |
page, page_size | See Pagination. |
curl "https://api.safeguard.sh/gpt/v1/meetings?from=2026-11-01&view=mine&page_size=2" \
-H "Authorization: Bearer $SAFEGUARD_MEETINGS_KEY"{
"data": [
{
"id": "9f2c4b7e1a3d4c58b6e0a1d2c3f4e5a6",
"source": "safeguard",
"external_id": null,
"capture_mode": "agent",
"title": "Northwind security review",
"platform": "google_meet",
"status": "completed",
"started_at": "2026-11-14T09:00:00Z",
"ended_at": "2026-11-14T09:42:10Z",
"duration_seconds": 2530,
"participants": [
{ "name": "Alex Chen", "kind": "owner", "email": "alex.chen@example.com" },
{ "name": "Priya Nair", "kind": "speaker", "email": "priya.nair@northwind.example" }
],
"participant_count": 2,
"summary_preview": "Alex and Priya reviewed Northwind's open vulnerabilities and agreed on a rollout plan for the next quarter.",
"action_item_count": 5,
"open_action_item_count": 3,
"my_open_action_item_count": 2,
"audience": "external",
"has_transcript": true,
"has_recording": true,
"access": "owner"
}
],
"page": 1,
"page_size": 2,
"total": 14,
"has_more": true
}List summary templates
GET /meetings/summary-templates
curl https://api.safeguard.sh/gpt/v1/meetings/summary-templates \
-H "Authorization: Bearer $SAFEGUARD_MEETINGS_KEY"{
"data": [
{
"id": "sales_discovery",
"name": "Sales discovery",
"description": "Pain points, current solution, budget, decision makers and timeline.",
"sections": [
{ "key": "pain_points", "heading": "Pain points" },
{ "key": "current_solution", "heading": "Current solution" }
]
}
]
}The list is trimmed here. The full set is in Summary templates.
Get a meeting
GET /meetings/{id} returns the list item fields plus the summary, action items, questions, recording details and more. can_edit is always false over the API.
curl https://api.safeguard.sh/gpt/v1/meetings/9f2c4b7e1a3d4c58b6e0a1d2c3f4e5a6 \
-H "Authorization: Bearer $SAFEGUARD_MEETINGS_KEY"{
"id": "9f2c4b7e1a3d4c58b6e0a1d2c3f4e5a6",
"title": "Northwind security review",
"platform": "google_meet",
"status": "completed",
"started_at": "2026-11-14T09:00:00Z",
"ended_at": "2026-11-14T09:42:10Z",
"access": "owner",
"meeting_url": "https://meet.google.com/abc-defg-hij",
"error": null,
"agents": [{ "agent_id": "a1", "name": "Ada" }],
"summary": {
"text": "Alex and Priya reviewed Northwind's open vulnerabilities and agreed on a rollout plan.",
"decisions": ["Start the rollout with the payments service."],
"key_points": ["Northwind has 41 open high severity issues."],
"template": "sales_discovery",
"sections": [],
"generated_at": "2026-11-14T09:45:00Z"
},
"action_items": [],
"shared_with": [],
"recording": {
"available": true,
"parts": [{ "index": 0, "bytes": 18234567 }],
"started_at": "2026-11-14T09:00:02Z",
"external_url": null,
"mime_type": "audio/webm"
},
"can_edit": false,
"line_count": 412,
"self_speakers": ["Alex Chen", "You"],
"questions": { "yours": [], "theirs": [] },
"summary_language": "auto"
}Fields shared with the list item (participants, duration_seconds, counts and so on) are present and are left out of the example above to keep it short.
Get the transcript
GET /meetings/{id}/transcript
curl https://api.safeguard.sh/gpt/v1/meetings/9f2c4b7e1a3d4c58b6e0a1d2c3f4e5a6/transcript \
-H "Authorization: Bearer $SAFEGUARD_MEETINGS_KEY"{
"id": "9f2c4b7e1a3d4c58b6e0a1d2c3f4e5a6",
"segments": [
{
"index": 0,
"speaker": "Alex Chen",
"text": "Thanks for joining, Priya. Let's start with where Northwind is today.",
"start_ms": 0,
"end_ms": 5000,
"at": "2026-11-14T09:00:05Z",
"agent": false
},
{
"index": 1,
"speaker": "Priya Nair",
"text": "We scan on every pull request, but nobody owns the backlog.",
"start_ms": 5200,
"end_ms": 11800,
"at": "2026-11-14T09:00:10Z",
"agent": false
}
],
"recording_started_at": "2026-11-14T09:00:02Z"
}A very long meeting keeps its first 6,000 lines.
Get the summary
GET /meetings/{id}/summary returns the summary object described in Objects.
curl https://api.safeguard.sh/gpt/v1/meetings/9f2c4b7e1a3d4c58b6e0a1d2c3f4e5a6/summary \
-H "Authorization: Bearer $SAFEGUARD_MEETINGS_KEY"{
"text": "Alex and Priya reviewed Northwind's open vulnerabilities and agreed on a rollout plan.",
"decisions": ["Start the rollout with the payments service."],
"key_points": ["Northwind has 41 open high severity issues."],
"template": "sales_discovery",
"sections": [
{
"key": "pain_points",
"heading": "Pain points",
"bullets": [
{
"text": "Nobody owns the vulnerability backlog.",
"label": null,
"line": 1,
"start_ms": 5200,
"children": []
}
]
}
],
"generated_at": "2026-11-14T09:45:00Z"
}List action items
GET /meetings/{id}/action-items
curl https://api.safeguard.sh/gpt/v1/meetings/9f2c4b7e1a3d4c58b6e0a1d2c3f4e5a6/action-items \
-H "Authorization: Bearer $SAFEGUARD_MEETINGS_KEY"{
"id": "9f2c4b7e1a3d4c58b6e0a1d2c3f4e5a6",
"data": [
{
"id": "ai_3f9a",
"text": "Send the SOC 2 report",
"assignee": "Alex Chen",
"due": "2026-11-20",
"done": false,
"line": 87,
"start_ms": 512000,
"source": "notes"
}
]
}List questions
GET /meetings/{id}/questions returns the transcript lines that read as questions, at most 30 per side. yours holds questions from your side of the call (the owner and any Safeguard agents); theirs holds questions from everyone else.
curl https://api.safeguard.sh/gpt/v1/meetings/9f2c4b7e1a3d4c58b6e0a1d2c3f4e5a6/questions \
-H "Authorization: Bearer $SAFEGUARD_MEETINGS_KEY"{
"id": "9f2c4b7e1a3d4c58b6e0a1d2c3f4e5a6",
"yours": [
{ "text": "What is your timeline?", "speaker": "Alex Chen", "line": 40, "start_ms": 201000 }
],
"theirs": [
{ "text": "Does it support SSO?", "speaker": "Priya Nair", "line": 52, "start_ms": 260000 }
]
}Get the recording
GET /meetings/{id}/recording returns one signed link for each recorded part. See Recordings.
curl https://api.safeguard.sh/gpt/v1/meetings/9f2c4b7e1a3d4c58b6e0a1d2c3f4e5a6/recording \
-H "Authorization: Bearer $SAFEGUARD_MEETINGS_KEY"{
"id": "9f2c4b7e1a3d4c58b6e0a1d2c3f4e5a6",
"data": [
{
"index": 0,
"bytes": 18234567,
"url": "https://api.safeguard.sh/gpt/v1/meetings/playback/eyJ0IjoiLi4uIn0.c2lnbmF0dXJl",
"expires_at": "2026-11-14T10:00:00Z",
"mime_type": "audio/webm"
}
]
}A meeting with no recording returns an empty data list.
List agent calendars
GET /meetings/agents returns the meeting agents whose calendars the key's owner can read: every built-in agent, and any custom agent that is on a meeting the owner can see.
curl https://api.safeguard.sh/gpt/v1/meetings/agents \
-H "Authorization: Bearer $SAFEGUARD_MEETINGS_KEY"{
"data": [
{"agent_id": "ledger", "name": "Maya", "kind": "built_in"},
{"agent_id": "c-0123456789ab", "name": "Northwind notes helper", "kind": "custom"}
]
}Get an agent's events
GET /meetings/agents/{agent_id}/events?from=...&to=... returns what one agent did and will do between from and to (ISO-8601, at most 62 days apart; without them, the week before and after now): meetings it joined, joins scheduled for it, and other agent work such as calls it places. Meetings the key's owner may not see come back as busy blocks only.
curl "https://api.safeguard.sh/gpt/v1/meetings/agents/ledger/events?from=2026-11-09T00:00:00Z&to=2026-11-16T00:00:00Z" \
-H "Authorization: Bearer $SAFEGUARD_MEETINGS_KEY"{
"agent_id": "ledger",
"from": "2026-11-09T00:00:00Z",
"to": "2026-11-16T00:00:00Z",
"data": [
{
"id": "meeting:9f2c4b7e1a3d4c58b6e0a1d2c3f4e5a6",
"kind": "meeting",
"source": "history",
"busy": false,
"meeting_id": "9f2c4b7e1a3d4c58b6e0a1d2c3f4e5a6",
"title": "Northwind rollout review",
"platform": "google_meet",
"status": "completed",
"start": "2026-11-12T09:00:00Z",
"end": "2026-11-12T09:42:00Z",
"access": "owner",
"has_recording": true
},
{"id": "busy_3c1f9a2b7d4e5f60a1b2", "kind": "busy", "busy": true, "start": "2026-11-13T15:00:00Z", "end": "2026-11-13T15:30:00Z"},
{
"id": "schedule:5b7e2c9d1a4f4e8b9c0d1e2f3a4b5c6d",
"kind": "scheduled_join",
"source": "schedule",
"busy": false,
"schedule_id": "5b7e2c9d1a4f4e8b9c0d1e2f3a4b5c6d",
"title": "Northwind pilot check-in",
"status": "scheduled",
"start": "2026-11-15T10:00:00Z",
"end": "2026-11-15T11:00:00Z",
"agent_ids": ["ledger"],
"meeting_url": "https://meet.google.com/abc-defg-hij",
"meeting_id": null,
"can_edit": false,
"access": "owner"
}
]
}An agent the key's owner cannot read answers 404 not_found. Scheduling, availability and pauses are managed in the Safeguard app; the API reads them.
Objects
Meeting list item
| Field | Meaning |
|---|---|
id | The meeting's id. Use it in every path above. |
source | safeguard for meetings Safeguard captured, or the note taker's id for an imported meeting. |
external_id | The note taker's own id for an imported meeting, else null. |
capture_mode | agent (a Safeguard agent joined), extension (the browser extension captured it) or import. |
title | The title. May be an empty string. |
platform | The meeting platform, from the list in List meetings. |
status | in_progress, completed or failed. |
started_at, ended_at | UTC timestamps. |
duration_seconds | The length of the meeting. |
participants | Objects with name, kind (speaker, agent or owner) and, when allowed, email. |
participant_count | The number of participants. |
summary_preview | The first 240 characters or so of the summary. |
action_item_count, open_action_item_count | All and open action items. |
my_open_action_item_count | Open action items assigned to the key's owner. |
audience | internal, external or unknown. |
has_transcript, has_recording | Whether those exist. |
access | owner (always, over the API). |
Meeting
A meeting is a list item plus meeting_url (owner only, else null), error, agents, summary, action_items, shared_with (owner only, else []), recording, can_edit (always false over the API), line_count, self_speakers, questions and summary_language.
recording has available, parts (each with index and bytes), started_at, external_url (set for an imported recording that is played from its own address, else null) and mime_type.
Transcript segment
| Field | Meaning |
|---|---|
index | The line's position, starting at 0. |
speaker | The speaker's name. |
text | What was said, in its original script. |
start_ms, end_ms | Offsets in milliseconds from the start of the recording, or from the start of the meeting when there is no recording. null when unknown. |
at | The wall-clock time of the line in UTC, or null. |
agent | true when a Safeguard agent spoke the line. |
The offsets are what a player needs: pass start_ms / 1000 as the seek time in the recording.
Summary
| Field | Meaning |
|---|---|
text | A one-paragraph summary. |
decisions, key_points | Lists of short strings. |
template | The summary template id used, or null. |
sections | One object per template section: key, heading and bullets. |
generated_at | When the summary was written, or null. |
Each bullet has text, an optional bold lead-in in label, the transcript line and start_ms it came from (or null), and children, a list of {label, text} pairs that is empty when a bullet has no sub-points. With the General template, key_takeaways bullets use label and topics bullets use children (Problem, Impact, Purpose, Action).
The summary is written in the meeting's own language, with quotes kept in their original script.
Action item
| Field | Meaning |
|---|---|
id | The action item's id. |
text | What needs doing. |
assignee | A name, or null. |
due | A YYYY-MM-DD date, or null. |
done | Whether it is complete. |
line, start_ms | Where in the transcript it came from, or null. |
source | notes (found in the meeting) or manual (added by a person). |
Question
text, speaker, line and start_ms.
Summary templates
GET /meetings/summary-templates returns each template with its id, name, description and sections (key and heading).
id | name | Section keys |
|---|---|---|
general | General | purpose, key_takeaways, topics |
sales_discovery | Sales discovery | pain_points, current_solution, budget, decision_makers, timeline, next_steps |
sales_meddpicc | Sales, MEDDPICC | metrics, economic_buyer, decision_criteria, decision_process, paper_process, identify_pain, champion, competition |
sales_bant | Sales, BANT | budget, authority, need, timeline |
customer_success | Customer success check-in | health, wins, issues_risks, requests, next_steps |
interview | Candidate interview | background, strengths, concerns, follow_ups |
standup | Internal standup | done, planned, blockers |
project_kickoff | Project kickoff | goals, scope, roles, milestones, risks, next_steps |
demo | Product demo | audience_needs, features_shown, questions, objections, next_steps |
Pagination
GET /meetings takes page (1-based, default 1) and page_size (1 to 100, default 25). The answer carries page, page_size, total and has_more. When has_more is true, ask for page + 1.
import os, requests
base = "https://api.safeguard.sh/gpt/v1"
headers = {"Authorization": f"Bearer {os.environ['SAFEGUARD_MEETINGS_KEY']}"}
page, meetings = 1, []
while True:
r = requests.get(f"{base}/meetings", headers=headers,
params={"page": page, "page_size": 100})
r.raise_for_status()
body = r.json()
meetings += body["data"]
if not body["has_more"]:
break
page += 1
print(len(meetings), "meetings")Recordings
GET /meetings/{id}/recording returns, for each part of the recording, an absolute signed url, its expires_at and its mime_type, which is audio/webm.
- A signed link is valid for 10 minutes. Ask again for a fresh one when it expires.
- The link needs no
Authorizationheader: the signature is the grant, so do not share it. - The link supports
Rangerequests, so a player can seek. A valid range answers206 Partial Content, an unsatisfiable range answers416, andAccept-Ranges: bytesis sent on every answer. - An expired or invalid link answers
404.
curl -r 0-1048575 -o part0.webm "$RECORDING_URL"Rate limits
- 120 requests a minute for each key.
- 600 requests a minute for each workspace, across all its keys.
Every answer carries X-RateLimit-Limit and X-RateLimit-Remaining. Past a limit, the request is refused with 429 rate_limited and a Retry-After header giving the seconds to wait. Wait that long, then retry.
Errors
Errors use this body. Branch on code; the message wording may change.
{
"error": {
"code": "insufficient_scope",
"message": "This key does not have the meetings:read scope."
}
}| Status | code | When | Retry? |
|---|---|---|---|
| 400 | invalid_request | A query parameter is not valid, such as a bad date, a page_size outside 1 to 100 or an unknown platform. | No. Fix the request. |
| 401 | invalid_api_key | The key is missing, malformed, unknown, revoked or expired, or its owner can no longer use it. | No. |
| 403 | insufficient_scope | The key is valid but does not carry meetings:read, for example an inference, MCP, Guard or CI key. | No. Use a Meetings key. |
| 404 | not_found | The meeting does not exist, the key cannot see it, it has no recording, or meetings are not turned on for the workspace. | No. |
| 429 | rate_limited | The key or the workspace reached its limit. | Yes, after Retry-After. |
| 503 | auth_unavailable | Safeguard could not check keys at that moment. | Yes, after a short wait. |
See also Authentication for the other kinds of key.
Limits
Rate limits per key, spend limits per key and per workspace, the prepaid credit hard stop, request size and time limits, and what happens when each is reached.
Pricing and billing
How the API Platform bills model usage: the provider's list price with no markup, paid from prepaid credit, with spend limits you set.