Safeguard Docs
API Platform (Console)

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

  1. Open Settings and choose Secret keys. In the Console, the same page is under Console > Settings > Secret keys.
  2. Choose Create key and set the kind to Meetings.
  3. 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_with and meeting_url are 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.

MethodPathReturns
GET/meetingsA page of meetings
GET/meetings/summary-templatesThe summary templates
GET/meetings/{id}One meeting in full
GET/meetings/{id}/transcriptThe transcript segments
GET/meetings/{id}/summaryThe meeting's summary
GET/meetings/{id}/action-itemsThe action items
GET/meetings/{id}/questionsQuestions asked by each side
GET/meetings/{id}/recordingSigned links to the recording
GET/meetings/agentsThe meeting agents whose calendars the key can read
GET/meetings/agents/{agent_id}/eventsOne agent's calendar between two dates

List meetings

GET /meetings

Query parameterMeaning
from, toISO 8601 date or time, applied to the meeting's start.
qText to find in the title, the summary or participant names.
platformOne of google_meet, teams, zoom, webex, slack, whereby, jitsi, safeguard_meet, discord, goto, whatsapp, other.
statusin_progress, completed or failed.
viewall (default), mine or team. Over the API, all and mine return the key owner's own meetings and team returns none.
sourcesafeguard, or the id of the note taker an imported meeting came from.
participantText to find in a participant's name or email.
has_action_itemstrue or false.
audienceinternal, external or unknown.
assignedme for meetings with an open action item assigned to the key's owner.
page, page_sizeSee 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

FieldMeaning
idThe meeting's id. Use it in every path above.
sourcesafeguard for meetings Safeguard captured, or the note taker's id for an imported meeting.
external_idThe note taker's own id for an imported meeting, else null.
capture_modeagent (a Safeguard agent joined), extension (the browser extension captured it) or import.
titleThe title. May be an empty string.
platformThe meeting platform, from the list in List meetings.
statusin_progress, completed or failed.
started_at, ended_atUTC timestamps.
duration_secondsThe length of the meeting.
participantsObjects with name, kind (speaker, agent or owner) and, when allowed, email.
participant_countThe number of participants.
summary_previewThe first 240 characters or so of the summary.
action_item_count, open_action_item_countAll and open action items.
my_open_action_item_countOpen action items assigned to the key's owner.
audienceinternal, external or unknown.
has_transcript, has_recordingWhether those exist.
accessowner (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

FieldMeaning
indexThe line's position, starting at 0.
speakerThe speaker's name.
textWhat was said, in its original script.
start_ms, end_msOffsets in milliseconds from the start of the recording, or from the start of the meeting when there is no recording. null when unknown.
atThe wall-clock time of the line in UTC, or null.
agenttrue 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

FieldMeaning
textA one-paragraph summary.
decisions, key_pointsLists of short strings.
templateThe summary template id used, or null.
sectionsOne object per template section: key, heading and bullets.
generated_atWhen 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

FieldMeaning
idThe action item's id.
textWhat needs doing.
assigneeA name, or null.
dueA YYYY-MM-DD date, or null.
doneWhether it is complete.
line, start_msWhere in the transcript it came from, or null.
sourcenotes (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).

idnameSection keys
generalGeneralpurpose, key_takeaways, topics
sales_discoverySales discoverypain_points, current_solution, budget, decision_makers, timeline, next_steps
sales_meddpiccSales, MEDDPICCmetrics, economic_buyer, decision_criteria, decision_process, paper_process, identify_pain, champion, competition
sales_bantSales, BANTbudget, authority, need, timeline
customer_successCustomer success check-inhealth, wins, issues_risks, requests, next_steps
interviewCandidate interviewbackground, strengths, concerns, follow_ups
standupInternal standupdone, planned, blockers
project_kickoffProject kickoffgoals, scope, roles, milestones, risks, next_steps
demoProduct demoaudience_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 Authorization header: the signature is the grant, so do not share it.
  • The link supports Range requests, so a player can seek. A valid range answers 206 Partial Content, an unsatisfiable range answers 416, and Accept-Ranges: bytes is 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."
  }
}
StatuscodeWhenRetry?
400invalid_requestA 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.
401invalid_api_keyThe key is missing, malformed, unknown, revoked or expired, or its owner can no longer use it.No.
403insufficient_scopeThe key is valid but does not carry meetings:read, for example an inference, MCP, Guard or CI key.No. Use a Meetings key.
404not_foundThe meeting does not exist, the key cannot see it, it has no recording, or meetings are not turned on for the workspace.No.
429rate_limitedThe key or the workspace reached its limit.Yes, after Retry-After.
503auth_unavailableSafeguard could not check keys at that moment.Yes, after a short wait.

See also Authentication for the other kinds of key.

On this page