Synced from Hive. This page is pulled from hivecommons/hive@v5 during the docs build. Edit the canonical source in the Hive repository.

Dashboard REST API reference — Knowledge

Part of the Dashboard REST API reference; see that page for how auth levels and pkg/<file>:<line> source citations are read and checked. Edit this file for routes in this area and run src/scripts/check-api-reference-citations.sh --fix to resync citations.

MethodPathAuthPurposeSource
GET/api/knowledgeDashboard auth/sessionPaginated knowledge facts: type filter, limit (default 50, max 200; invalid/non-positive values use the default), offset (default 0). Returns enabled, facts, count (this page), total, limit, offset, has_more; ordered by layer then slug. Offsets are not snapshot cursors: concurrent edits may shift pages.pkg/dashboard/api.go:365
GET/api/knowledge/exportDashboard auth/sessionKnowledge Exportpkg/dashboard/api.go:366
POST/mcp/knowledgePublic (read-only) when the dashboard setting or HIVE_PUBLIC_KNOWLEDGE is on; otherwise 404 to a signed-in caller and 401 to one who is notPublic Knowledge MCP endpoint — initialize, tools/list, tools/call for knowledge_search/knowledge_toc/knowledge_get/knowledge_export (docs)pkg/dashboard/api.go:375
GET/api/knowledge/searchDashboard auth/sessionKnowledge Searchpkg/dashboard/api.go:367
GET/api/knowledge/tocDashboard auth/sessionScoped knowledge table of contents: capped, body-free entries (id, title, type, layer, repo, tags, status, confidence, updated, size_bytes, source) plus total/returned/truncated. Query: layers, repos, types, tags (comma-separated), limit (default 50, max 200), include_states (operator opt-in for draft/deprecated/superseded/all), format=prompt with max_chars for a bounded markdown rendering, agent to apply that agent’s knowledge.agent_scopes entry (the other parameters can only narrow it). Approved knowledge only by default (docs)pkg/dashboard/api.go:368
GET/api/knowledge/effectiveDashboard auth/sessionEffective knowledge for one agent (agent required): the agent’s knowledge.agent_scopes entry (unrestricted when it has none) intersected with the request scope (approved only unless include_states is set). Returns scope (resolved scope applied, with configured), included TOC entries, excluded entries each with a reason (lifecycle, layer, repo, type or tag — first failing check, in that order), included_total/excluded_total/included_returned/excluded_returned and truncated; limit caps each list (default 50, max 200) (docs)pkg/dashboard/api.go:369
GET/api/knowledge/entry/{id}Dashboard auth/sessionFull read of one knowledge entry: markdown (front-matter plus body) and the fact. Takes the same scope, include_states and agent query as the table of contents and returns 404 for an entry outside it (docs)pkg/dashboard/api.go:370
POST/api/knowledge/cli-memory/drain-legacyOwner onlyOne-shot drain of the shared home’s legacy Claude memory (/data/home/.claude/projects/*/memory) into state: draft entries in bead-synth-wiki, tagged cli-memory and agent:shared, deduplicated by content hash. Body {"truncate": bool} (default false) empties only files whose every fact is now stored. Returns store, agent, sources, drained, dupes, skipped, truncate, truncated, kept, errors; 409 when the vault is not connected. Audited as knowledge_drain_legacy_memory (docs)pkg/dashboard/api.go:372
GET/api/knowledge/publicDashboard auth/sessionPublic Knowledge MCP sharing status (enabled, tags, source, endpoint URL)pkg/dashboard/api.go:376
PUT/api/knowledge/publicOwner onlyPersist public Knowledge MCP sharing setting; overrides env vars until changedpkg/dashboard/api.go:377
GET/api/knowledge/healthDashboard auth/sessionKnowledge Healthpkg/dashboard/api.go:378
GET/api/knowledge/statsDashboard auth/sessionKnowledge Statspkg/dashboard/api.go:379
GET/api/knowledge/graphDashboard auth/sessionKnowledge Graphpkg/dashboard/api.go:380
GET/api/knowledge/fact-historyDashboard auth/sessionFact Historypkg/dashboard/api.go:381
POST/api/knowledge/createDashboard auth/sessionCreate one fact (title, body, type, tags, layer, confidence, state). state is approved (default) or draft; a draft is written with state: draft into the local channel named by layer (400 when there is none, 409 when its title already names an entry). A request tagged cli-memory must be a draft carrying only cli-memory, agent:&lt;name&gt;, cli:<claude|codex|gemini>, memhash:&lt;hex&gt; and repo:&lt;org&gt;/&lt;repo&gt; tags (400 otherwise)pkg/dashboard/api.go:382
POST/api/knowledge/importDashboard auth/sessionKnowledge Importpkg/dashboard/api.go:383
POST/api/knowledge/promoteDashboard auth/sessionKnowledge Promotepkg/dashboard/api.go:389
GET/api/knowledge/subscriptionsDashboard auth/sessionKnowledge Subs Listpkg/dashboard/api.go:390
POST/api/knowledge/subscriptionsDashboard auth/sessionKnowledge Subs Addpkg/dashboard/api.go:391
DELETE/api/knowledge/subscriptionsDashboard auth/sessionKnowledge Subs Removepkg/dashboard/api.go:392
PUT/api/knowledge/{layer}/{slug}Dashboard auth/sessionKnowledge Updatepkg/dashboard/api.go:393
DELETE/api/knowledge/{layer}/{slug}Dashboard auth/sessionKnowledge Deletepkg/dashboard/api.go:394
GET/api/knowledge/{layer}Dashboard auth/sessionKnowledge Layerpkg/dashboard/api.go:395
GET/api/knowledge/{layer}/{slug}Dashboard auth/sessionKnowledge Factpkg/dashboard/api.go:396
PUT/api/knowledge/enabledOwner onlyKnowledge Togglepkg/dashboard/api.go:397
GET/api/knowledge/bead-synthesizerDashboard auth/sessionBead Synth Statuspkg/dashboard/api.go:398
PUT/api/knowledge/bead-synthesizer/enabledOwner onlyBead Synth Togglepkg/dashboard/api.go:399
GET/api/knowledge/vaultsDashboard auth/sessionVaults Listpkg/dashboard/api.go:400
POST/api/knowledge/vaultsOwner onlyVaults Connectpkg/dashboard/api.go:401
DELETE/api/knowledge/vaultsDashboard auth/sessionVaults Disconnectpkg/dashboard/api.go:402
POST/api/knowledge/vaults/reindexDashboard auth/sessionVaults Reindexpkg/dashboard/api.go:403
GET/api/knowledge/vaults/{name}/factsDashboard auth/sessionVault Factspkg/dashboard/api.go:404
GET/api/config/knowledge/connectorsDashboard auth/sessionKnowledge connectors config (name, type, layer, scope, env/file auth reference) and registered typespkg/dashboard/api.go
PUT/api/config/knowledge/connectorsOwner onlyReplace knowledge.connectors after validation; inline secrets rejectedpkg/dashboard/api.go
GET/api/config/knowledge/connectors/statusDashboard auth/sessionPer-connector status pill, last sync, pages/facts, last error, running and the live progress block (phase, items_done/items_total, current item, started_at; see knowledge-connectors.md), plus the publish mirror statuspkg/dashboard/api.go
POST/api/config/knowledge/connectors/validateOwner onlyDry-run validate one connector entry (no network)pkg/dashboard/api.go
POST/api/config/knowledge/connectors/{name}/syncOwner onlyStart an immediate background sync of one connectorpkg/dashboard/api.go
GET/api/config/knowledge/agent-scopesDashboard auth/sessionPer-agent knowledge scopes (knowledge.agent_scopes: layers, repos, types, tags, include_states) (docs)pkg/dashboard/api.go
PUT/api/config/knowledge/agent-scopesOwner onlyReplace knowledge.agent_scopes after validating layer and state names; persisted and audited as config_knowledge_agent_scopespkg/dashboard/api.go
GET/api/config/knowledge/pipelineOwner onlyScalar bead synthesizer, curator, code map and primer settings, plus the read-only engine, vault paths and primer merge strategy (docs)pkg/dashboard/api.go
PUT/api/config/knowledge/pipelineOwner onlyUpdate those settings after config.ValidateKnowledgePipeline; 0 or empty restores the default; the bead synthesizer switch applies at once, the rest after a restart; audited as config_knowledge_pipelinepkg/dashboard/api.go
GET/api/knowledge/git-sourcesDashboard auth/sessionGit Sources Listpkg/dashboard/api.go:414
POST/api/knowledge/git-sourcesOwner onlyGit Sources Connectpkg/dashboard/api.go:415
DELETE/api/knowledge/git-sourcesOwner onlyGit Sources Disconnectpkg/dashboard/api.go:416
POST/api/knowledge/obsidian/syncDashboard auth/sessionObsidian Syncpkg/dashboard/api.go:417
GET/api/knowledge/documentsDashboard auth/sessionDocuments Listpkg/dashboard/api.go:418
POST/api/knowledge/documentsDashboard auth/sessionDocuments Importpkg/dashboard/api.go:419
GET/api/knowledge/documents/{slug}Dashboard auth/sessionDocument Getpkg/dashboard/api.go:420
DELETE/api/knowledge/documents/{slug}Dashboard auth/sessionDocument Deletepkg/dashboard/api.go:421
POST/api/knowledge/documents/{slug}/reimportDashboard auth/sessionDocument Reimportpkg/dashboard/api.go:422
GET/api/knowledge/context7/searchDashboard auth/sessionContext7 Searchpkg/dashboard/api.go:423
POST/api/knowledge/cleanup-orphansDashboard auth/sessionCleanup Orphanspkg/dashboard/api.go:424
GET/api/knowledge/channelsDashboard auth/sessionKnowledge Channels Listpkg/dashboard/api.go:387
POST/api/knowledge/channelsDashboard auth/sessionKnowledge Channel Createpkg/dashboard/api.go:388
GET/api/knowledge/connectorsDashboard auth/sessionKnowledge connector statuses, each with a live progress block while a sync runs, and publish mirror status ({"connectors": [...], "publish": {...}|null}, see knowledge-connectors.md)pkg/dashboard/api_knowledge_connectors.go:24
POST/api/knowledge/connectors/{name}/syncOwner onlyStart one connector sync now (202; 404 unknown, 409 running)pkg/dashboard/api_knowledge_connectors.go:25
POST/api/knowledge/publish/syncOwner onlyRun a publish mirror batch now (202 with publish status; 503 mirror not running, 409 batch in progress)pkg/dashboard/api_knowledge_connectors.go:26
GET/api/knowledge/connectors/{name}/authDashboard auth/sessionInteractive sign-in state for a connector (Plaud OAuth, Zoom OAuth app, Teams Graph application permissions, Google Meet OAuth client or service account, Webex integration, Slack huddles token probe, Otter API key probe, Granola API key probe, Limitless API key probe, Fathom API key probe, Fireflies API key probe, Discord bot token): connected, account, pending, auth_url; ?refresh=1 re-checks upstream; for teams a missing admin consent is reported in message with the Entra consent page in auth_url (400 for connector types without interactive sign-in)pkg/dashboard/api_knowledge_connector_auth.go:25
POST/api/knowledge/connectors/{name}/auth/connectOwner onlyStart the connector’s sign-in flow (202 with state incl. auth_url; Zoom user-level: the app’s authorization URL, pending until the redirect URL is pasted; Zoom Server-to-Server and Teams: token fetched at once, outcome in the state)pkg/dashboard/api_knowledge_connector_auth.go:26
POST/api/knowledge/connectors/{name}/auth/disconnectOwner onlySign out and revoke the connector’s credential upstream (Zoom: revoke + token store cleared; Teams: cached token dropped)pkg/dashboard/api_knowledge_connector_auth.go:27
POST/api/knowledge/connectors/{name}/auth/completeOwner onlyFinish a sign-in from pasted material on a hosted hive: {redirect_url} (Plaud: the localhost:8199/auth/callback?… URL the browser landed on, forwarded in-pod while the login is pending; Zoom, Google Meet and Webex: the registered redirect URL with code and state, exchanged for tokens kept in the connector token store) or {tokens} (Plaud only: contents of ~/.plaud/tokens-mcp.json); see inbox-voice-sources.mdpkg/dashboard/api_inbox.go:32
GET/api/inboxDashboard auth/sessionInbox items (voice recordings, dictations and meeting recordings keyed by (source, id)) with per-destination route state, source connection status, candidate repos and auto-routing settings; see inbox-voice-sources.mdpkg/dashboard/api_inbox.go:24
POST/api/inbox/routeOwner onlyRoute one item: {source, item_id, destination: spek_rfc|dibs|dismiss, repo?} (202 queued; 400 unconfigured destination, 404 unknown item, 409 already queued/running)pkg/dashboard/api_inbox.go:25
POST/api/inbox/emailHub relay signatureMail-in files hive-mx received for hive@<host> (#18395, #18564): Markdown, audio, video and image attachments, and a body-only mail as message.md, become email Inbox items under connector-state/email/items; the mail’s text body is kept as each item’s note (files.note). A sender who passed DMARC alignment and is a proven calendar email of a user with access gets normal items; anyone else’s items carry awaiting_approval and cannot be shared, routed or transcribed until approved. 200 {items, awaiting_approval}; 409 off (meetings.email.files_enabled); 507 spool full (1 GiB); 401 bad relay signaturepkg/dashboard/api_inbox_email.go:29
POST/api/inbox/email/chunkHub relay signature, per pieceOne piece of a large mail-in delivery the hub relays in order (X-Hive-Relay-Delivery: <id>.<index>.<count>, at most 8 MiB per piece, X-Hive-Mail-Body-Type the whole body’s type: multipart/form-data from hive-mx or JSON). Pieces are staged under connector-state/email/items/.incoming/<id> (dropped after an hour if incomplete); the last one decodes the body, checks each file’s size and SHA-256, and answers like /api/inbox/email. 200 {piece, pieces} for an earlier piece; 400 invalid piece or body; 413 over HIVE_INBOX_EMAIL_MAX_BYTES (48 MiB); 507 spool fullpkg/dashboard/api_inbox_email.go:30
POST/api/inbox/email/{id}/approveOwner onlyApprove a mailed-in item from outside the allowlist. Audited as inbox-email-approvepkg/dashboard/api_inbox_email.go:31
POST/api/inbox/email/{id}/declineOwner onlyDelete a mailed-in item and its file. Unapproved items are also deleted after 14 days. Audited as inbox-email-declinepkg/dashboard/api_inbox_email.go:32
GET/api/inbox/email/{id}/fileOwner or read-writeThe stored file with its sniffed type (Markdown as text/plain), inline for images (audio and video download), nosniff and a sandbox CSPpkg/dashboard/api_inbox_email.go:33
POST/api/inbox/dismissOwner onlyBulk “Knowledge only”: {items: [{source, item_id}], undo?}pkg/dashboard/api_inbox.go:26
GET/api/inbox/settingsDashboard auth/sessionAuto-routing rules, default RFC repo, dibs URL, destination readinesspkg/dashboard/api_inbox.go:27
POST/api/inbox/settingsOwner onlyUpdate inbox.rules / inbox.spek.repo / inbox.dibs.url in the runtime config (omitted fields unchanged)pkg/dashboard/api_inbox.go:28
GET/api/inbox/{source}/{id}/contentDashboard auth/sessionFull text of one item: {title, summary, transcript, highlights, markdown, pending, provenance}, from the fact or live from the source while the fact has no text yet (404 unknown item, 502 source unreachable)pkg/dashboard/api_inbox.go:29
POST/api/inbox/{source}/{id}/transcribeOwner or read-writeQueue a machine transcription of one pending item with the resolved inbox.transcription.provider (auto: whisper, then gemini, then deepgram); runs execute one at a time in queue order (202 {source, item_id, state}; 200 when skipped up front: no audio, too long, budget); audited per run as inbox_transcribe (403 role, 404 unknown item, 409 queued/running/already transcribed/has text, 412 disabled or not consented); see inbox-transcription.mdpkg/dashboard/api_inbox.go:33
GET/api/inbox/transcriptionsDashboard authLive progress of queued and running transcriptions in queue order ({active: [{source, id, state}]} with phase, progress, estimated, started_at, audio_seconds, processed_seconds, eta_seconds, queue_position); reads no source, so the Inbox polls it every 3 s while a job runs; Cache-Control: no-store; see inbox-transcription.mdpkg/dashboard/api_inbox.go:34
GET/api/inbox/{source}/{id}/audioOwner or read-writeMint a fresh short-lived audio/video link for one item ({url, expires_at}; Plaud: presigned, 24h; Zoom: audio-only or video download_url with a one-hour download token; Webex: the recording’s temporary direct audio (else MP4) download link, valid 3 hours; Teams and Google Meet: 404, no browser-playable link; Slack huddles: 404, Slack keeps no huddle audio; Otter: the conversation’s MP3 download link (GET /conversations/{id}/audio), minted per click; Granola: 404, Granola keeps no meeting audio; Limitless: 404, Pendant audio is served only behind the API key; Fathom: the signed url of a recording download (POST /recordings/{id}/download, audio-only recordings complete at once, video is polled), valid about 24 hours; Fireflies: the transcript’s hashed audio_url (else video_url), valid 24 hours, Pro plan or higher); never stored by the hive, replied with Cache-Control: no-store, audited as inbox_audio (403 role, 404 unknown item or no audio, 502 source unreachable)pkg/dashboard/api_inbox.go:30
GET/api/inbox/{source}/{id}/audio/streamOwner or read-writeStream one item’s audio from the dashboard origin, for the Inbox player (the CSP refuses cross-origin media). The hive mints the link as above, fetches it server-side and copies the bytes with the media Content-Type (from storage, else the link’s extension); a single Range: bytes=… is passed through (206 + Content-Range; 200 whole file when storage ignores it; 416 passed through). The link stays in memory for one playback’s Range requests (10 min, never past expiry), is never logged, returned or stored, and is re-minted once when storage refuses it; nothing is written to disk. Cache-Control: no-store; audited as inbox_audio_stream once per minted link (403 role, 404 unknown item or no audio, 413 over the 2 GiB cap, 502 source or storage unreachable, or link refused/expired)pkg/dashboard/api_inbox.go:31
POST/api/inbox/uploadsOwner or read-writeAdd dropped files to the Inbox: multipart/form-data with one or more file fields (at most inbox.uploads.max_files_per_drop, default 20, each up to inbox.uploads.max_file_bytes, default 25 MiB). Each file is typed by content (magic bytes, UTF-8, a parse check), never by name or client MIME alone; md, txt, json, jsonl, yaml, csv, tsv, html, docx and pdf (parsed in the hive-pdftext sandbox) become upload items; audio and video (mp3, m4a, aac, wav, ogg, opus, webm, mp4, mov) stream to disk under inbox.recording.max_bytes, become pending audio items played from disk and are transcribed when transcription is on with extracted markdown and a Knowledge fact. One file: 201 {results: [{filename, ok, source, item_id, title, kind}]} or its refusal (400 empty/too_many_files, 413 too_large, 415 unsupported_type, 422 parse_failed, 507 quota_exceeded, each with code and error); several files: 200 with per-file results unless all failed. Cross-site requests are refused; every file is audited as inbox_upload (403 role, 404 no upload store); see inbox-uploads.mdpkg/dashboard/api_inbox_uploads.go:34
POST/api/inbox/uploads/urlOwner or read-writeAdd a link: {url}. The hive fetches it under the SSRF guard (http/https only, no credentials, its own DNS lookup with the connection pinned to the checked address, private/loopback/link-local/CGNAT/multicast/ULA/metadata ranges refused, every redirect re-checked, at most 3, body capped at inbox.uploads.max_file_bytes, 60 s) and runs the body through the upload type pipeline (an HTML page becomes readable markdown titled by its <title>). 201 {results: [{filename: host, ok, source, item_id, title, kind}]}; 400 link_refused, 413, 415, 422, 502 fetch_failed, 507; audited as inbox_upload with origin=link and the host (403 role, 404 no upload store)pkg/dashboard/api_inbox_uploads.go:35
POST/api/inbox/recordingsOwner or read-writeStart a dashboard recording (● Record): {title, mime: audio/webm|audio/mp4, consent_version, includes_tab_audio}. consent_version must name the current consent notice; it is stored with the user in the recording’s metadata. One recording per user at a time. 201 {id, max_chunk_bytes, max_seconds, retention_days, transcribes}; audited as inbox_recording_start (400 consent missing or stale, 403 role, 409 {active_id} already recording, 412 inbox.recording.enabled off, 415 other media types, 507 inbox.recording.quota_bytes used up); see inbox-recording.mdpkg/dashboard/api_inbox_recordings.go:20
POST/api/inbox/recordings/{id}/chunksThe recorder (owner or read-write)Store one MediaRecorder chunk ?seq=N, the raw bytes as the body (at most max_chunk_bytes, 512 KiB). In order only; each part is fsynced before the 200 {id, seq, next_seq, bytes, duplicate?}. The first chunk must start with a WebM or MP4 signature; the hive never decodes audio. A re-send with the same bytes is acknowledged again (duplicate: true) (400 bad seq, 403 someone else’s, 409 {expected_seq} gap, other bytes for a stored seq, or already ended, 413 chunk over 512 KiB or past max_bytes / max_seconds, 415 not WebM/MP4, 507 quota)pkg/dashboard/api_inbox_recordings.go:21
POST/api/inbox/recordings/{id}/finalizeThe recorderEnd a recording: {duration_ms?} (the recorder’s count, pauses excluded). The chunks are concatenated in order into audio.webm or audio.mp4, a pending Knowledge fact (personal layer) is written and the item appears in the Inbox. 200 {id, state, title, duration_ms, bytes, chunks, transcribes}; audited as inbox_recording_finalize (400 no chunk received, 403, 404, 409 already ended)pkg/dashboard/api_inbox_recordings.go:22
DELETE/api/inbox/recordings/{id}The recorder, or an ownerAbort an in-progress recording and delete its chunks; audited as inbox_recording_abort (403, 404, 409 already ended)pkg/dashboard/api_inbox_recordings.go:23
GET/api/inbox/recordings/{id}/audioOwner or read-writePlay a finished recording from this hive’s disk on the dashboard origin: http.ServeContent (Range, 206), Content-Type audio/webm or audio/mp4, Cache-Control: no-store, Cross-Origin-Resource-Policy: same-origin. Opening a playback is audited as inbox_recording_audio (seeks are not). GET /api/inbox/hive-recording/{id}/audio/stream serves the same file (404 unknown or not finished, 410 audio expired after inbox.recording.retention_days)pkg/dashboard/api_inbox_recordings.go:24
DELETE/api/inbox/hive-recording/{id}An owner, or the read-write member who recorded itDelete a finished recording for good: its stored audio and chunks, the Inbox item and its state, and its Knowledge fact with the machine transcript. What was already shared from it (RFC, issues, DIBS ideas, spek seeds) is not touched. 200 {id, deleted, fact_removed, shares_kept}; audited as inbox_recording_delete (403 read role or someone else’s recording, 404 unknown, 409 still in progress or being transcribed)pkg/dashboard/api_inbox_recordings.go:25
GET/api/meetings/settingsOwner onlyMeetings settings: enabled, enabled_env_override, running, vexa_url, vexa_key_set, discord_token_set, transcribe_token_set, tts_token_set (secrets are never returned) and effective values of the other meetings.* keys (env vars)pkg/dashboard/api_meetings.go:129
POST/api/meetings/settingsOwner onlyUpdate meetings.enabled and meetings.vexa.url, and write the Vexa tenant key, Discord bot token, transcription service token and TTS service token to keystore-sealed secret files ("" clears one): {enabled?, vexa_url?, vexa_api_key?, discord_token?, transcribe_token?, tts_token?}. Returns the settings with restart_required; 400 on an invalid value. Audited as meetings_settingspkg/dashboard/api_meetings.go:130
POST/api/meetingsOwner onlySend hive to a meeting: {url} for Google Meet, Teams or Zoom, or {platform: "discord", guild_id, channel_id}, plus title? and voice?. Returns the meeting record; 400 invalid request, 502 Quorum refused, 503 meetings off. Audited as meeting_joinpkg/dashboard/api_meetings.go:131
GET/api/meetingsOwner only{meetings: [...]}, newest firstpkg/dashboard/api_meetings.go:132
GET/api/meetings/{id}Owner only{meeting, transcript, live}: the record, stored final segments and chat, and the live-loop state (notes, research, asks, budget); 404 unknownpkg/dashboard/api_meetings.go:133
POST/api/meetings/{id}/leaveOwner onlyMake hive leave; returns the record. Audited as meeting_leavepkg/dashboard/api_meetings.go:134
POST/api/meetings/{id}/voiceOwner only{enabled}: allow hive to answer aloud when addressed (with meetings.voice_on_address). Audited as meeting_voicepkg/dashboard/api_meetings.go:135
POST/api/meetings/{id}/research/{rid}/approveOwner onlyDispatch a research item waiting past the per-meeting cap; 409 when it is not waiting or the live session ended. Audited as meeting_research_approvepkg/dashboard/api_meetings.go:136
POST/api/meetings/{id}/approveOwner onlyApprove a platform join request (Discord /hive join): joins that channel; optional {voice}. 409 when the meeting is not a pending request. Audited as meeting_request_approvepkg/dashboard/api_meetings.go:137
POST/api/meetings/{id}/declineOwner onlyDecline a platform join request with meeting.leave. Audited as meeting_request_declinepkg/dashboard/api_meetings.go:138
DELETE/api/meetings/{id}Owner onlyDelete a meeting in a final state (ended, failed, blocked, declined, left, handed off, purged) or a pending join request (declined with meeting.leave, then removed): the record, transcript and live state on this hive, the meeting in Vexa (Quorum meeting.delete, best effort: not_found is fine, any other error comes back as upstream_error while the record is still removed), and the Calendar entry that existed only for it. Knowledge facts and drafts made from it are not touched. 200 {id, state, upstream_error?, calendar_removed?}; 404 unknown; 409 while hive is joining, in the lobby or live (leave the meeting first). Audited as meeting_deletepkg/dashboard/api_meetings_delete.go:44
POST/api/meetings/clear-finishedOwner onlyDelete every meeting in a final state that finished before {before?} (RFC 3339; empty or later than now means now), each as DELETE /api/meetings/{id}; live meetings and pending join requests stay. 200 {deleted, count}; 400 bad before. Each meeting audited as meeting_deletepkg/dashboard/api_meetings_delete.go:45
GET/api/meetings/{id}/wsOwner onlyWebSocket live panel: a snapshot frame, then meeting, line, intent, research, notes and dropped frames for the meetingpkg/dashboard/api_meetings.go:139
GET/api/meetings/scheduleOwner or read-writeThe Calendar: {upcoming, recent, attendee_name}; upcoming events (scheduled, awaiting approval, live) by start and events finished in the last 14 days, newest first. Each event carries its platform, source, status, next occurrences and the meeting it created; a passcode is shown only as set. See Calendarpkg/dashboard/api_meetings_schedule.go:86
POST/api/meetings/scheduleOwner or read-writeSchedule a meeting: {url, start, end?, title?, rrule?, timezone?} (RFC 3339 times, RFC 5545 RRULE expanded in an IANA timezone). The platform comes from the link (Google Meet, Teams, Zoom). The owner’s add is scheduled; a read-write user’s add awaits approval. 400 invalid or already ended. Audited as meeting_schedule_addpkg/dashboard/api_meetings_schedule.go:87
POST/api/meetings/schedule/{eid}/approveOwner onlySchedule an event awaiting approval. 409 when it is not awaiting approval. Audited as meeting_schedule_approvepkg/dashboard/api_meetings_schedule.go:88
POST/api/meetings/schedule/{eid}/declineOwner onlyDecline an event awaiting approval; later updates of the same invite stay declined. Audited as meeting_schedule_declinepkg/dashboard/api_meetings_schedule.go:89
POST/api/meetings/schedule/{eid}/cancelOwner onlyStop hive joining the event (every occurrence of a series); a meeting already live is not left. Audited as meeting_schedule_cancelpkg/dashboard/api_meetings_schedule.go:90
POST/api/meetings/schedule/{eid}/skipOwner onlySkip the next occurrence hive has not joined: a single meeting becomes skipped, a series moves on. Audited as meeting_schedule_skippkg/dashboard/api_meetings_schedule.go:91
DELETE/api/meetings/schedule/{eid}Owner onlyDelete a past Calendar entry (ended, cancelled, declined, failed, blocked, skipped) and the meetings it created, each as DELETE /api/meetings/{id}. 200 {id, meetings}; 404 unknown; 409 for an entry still scheduled, awaiting approval or live (skip or cancel it) or whose meeting hive is still in. Audited as meeting_schedule_delete, plus meeting_delete per meetingpkg/dashboard/api_meetings_delete.go:46
GET/api/meetings/actionsOwner or read-writeDrafts from meetings: {drafts, pending}, newest first. Each draft carries id, meeting_id, meeting_title, meeting_link, type (issue, rfc, spek, knowledge), title, body, repo, excerpt, requested_by (a meeting display name), request, spoken, status (pending, approving, done, failed, rejected), auto_approved, result_url, result_note, error, announced (chat or notes), edited_by, decided_by, decided_at, created_at, updated_at. See Asking Betty to do thingspkg/dashboard/api_meetings_actions.go:69
GET/api/meetings/actions/settingsOwner or read-writemeetings.persona.actions as set and in effect: enabled, types, all_types, default_repo, effective_default_repo, repos (the monitored repos a draft may target), auto_approve (per type), auto_approvable (knowledge) and env_overridespkg/dashboard/api_meetings_actions.go:70
PUT/api/meetings/actions/settingsOwner onlySave {enabled?, types?, default_repo?, auto_approve?} into meetings.persona.actions; applies at once. 400 for an unknown type, a repo that is not owner/repo, or auto-approve on anything but knowledge. Audited as meetings_actions_settingspkg/dashboard/api_meetings_actions.go:71
GET/api/meetings/modelOwner or read-writeThe meetings model as set and in effect: mode, backend, model, label (what the meeting panel shows), modes, supported_backends (backends that can answer for meetings, named model gateways included), refused_backends (why each other known backend cannot), agent_backends (backends the hive’s agents use), default_backend, default_model, default_models and env_overrides. See Agent backendspkg/dashboard/api_meetings_model.go:63
PUT/api/meetings/modelOwner onlySave {mode?, backend?, model?} into meetings.llm; applies after a restart (restart_required). 400 for an unknown mode or a backend that cannot answer for meetings, with the reason. Audited as meetings_model_settingspkg/dashboard/api_meetings_model.go:64
POST/api/meetings/actions/{aid}/editOwner or read-writeChange a pending or failed draft: {type?, title?, body?, repo?}; the repo must be a monitored one. 404 unknown, 409 already decided. Audited as meeting_action_editpkg/dashboard/api_meetings_actions.go:72
POST/api/meetings/actions/{aid}/approveOwner or read-writeCreate the draft (issue or RFC on GitHub, Spek session through the Inbox spek_rfc destination, knowledge note in the meetings vault) and report the result to the meeting. Returns the draft, done with result_url or failed with error. 409 when it is not pending or failed, or action requests are off. Audited as meeting_action_approvepkg/dashboard/api_meetings_actions.go:73
POST/api/meetings/actions/{aid}/rejectOwner or read-writeReject a pending or failed draft; nothing is created. Audited as meeting_action_rejectpkg/dashboard/api_meetings_actions.go:74
GET/api/meetings/personaOwner or read-writeSettings, Meeting attendee: {effective, presets, overridden, voices, voice_types, restart_required, running, tts_configured, email, research}. research is the research agent pool Betty’s deep dives go to: {wired, agents, available, base_agent, backend, model, pool_size, warning}, with warning set when no agent can take a request. effective is the resolved persona (fields resolved as if on, enabled separately) with the rendered intro and voice_on_address; presets lists the built-in personas, the default first; overridden maps each meetings.persona key not taken from the preset or defaults to config or env; voices are the Kokoro voices with language, accent and voice type; restart_required is true when the saved persona differs from the one the hive booted with; email is the attendee address (hive@<dashboard host>), the access list with registered calendar emails and proof status, the approval queue and the email-in switches (available: false until email-in is enabled). See Meeting attendee settingspkg/dashboard/api_meetings_persona.go:166
PUT/api/meetings/personaOwner or read-writeSave meetings.persona to hive.yaml: {enabled?, preset?, clear_overrides?, name?, display_name?, aliases?, pronouns?, language?, voice?, voice_type?, accent?, intro_template?, leave_phrases?, humor?, unprompted?: {per_10m?, min_gap_s?, per_meeting?, answer_wait_s?, min_confidence?, queue_depth?, stale_s?}, voice_on_address?}. An absent field is unchanged, an empty one (or 0 for a cap) clears the override, a value equal to the preset’s is stored as no override, and clear_overrides drops every field override first. Validated as if the persona were on; returns the GET body. 400 invalid. Audited as meetings_persona. An optional email: {calendar_invites?, mail_in_files?} sets meetings.email.invites_enabled / files_enabled (owner only, else 403; #18395)pkg/dashboard/api_meetings_persona.go:167
POST/api/meetings/persona/sampleOwner or read-writeSpeak a short line through the meetings TTS service (Kokoro POST /v1/audio/speech) and return the audio (audio/mpeg, at most 2 MiB, Cache-Control: no-store). Optional {voice?, language?, display_name?, text?} (unsaved form values; text at most 200 characters, default the persona’s sample line in its language). 503 “TTS not configured” until meetings.tts_url is set, 400 invalid, 502 the TTS service failedpkg/dashboard/api_meetings_persona.go:168
GET/api/meetings/persona/sampleOwner or read-writeThe same sample with voice, language, display_name and text as query parameters, for the dashboard’s <audio> element (the dashboard CSP has no media-src, so audio must come from the dashboard origin)pkg/dashboard/api_meetings_persona.go:171
POST/api/meetings/invitesHub relay signatureCalendar invites hive-mx received for hive@<host> (#18395), relayed by the hub with X-Hive-Relay-Timestamp, X-Hive-Relay-Signature-256 and X-Hive-Relay-Delivery (5-minute skew, replay-protected). An invite is scheduled at once when the sender is its organizer, passed DMARC alignment and is on the calendar email allowlist, otherwise it awaits approval; a change or CANCEL for a meeting already on the calendar applies only when authenticated as its organizer. 200 {results[]}; 409 invites or meetings off; 422 nothing schedulable; 401 bad relay signature. See Inviting Betty by emailpkg/dashboard/api_meetings_email.go:62
POST/api/meetings/calendar-emails/proofHub relay signatureA proof mail: the address whose pending code is in the subject is proven when the mail came from it and passed DMARC alignment. 200 {proven, email}; 422 unknown code (shown, sender masked, in the owner’s recent_proof_attempts), or an expired code, another sender or no DMARC alignment for that address (the reason and SPF/DKIM/alignment summary are recorded on the address as last_failure)pkg/dashboard/api_meetings_email.go:63
GET/api/meetings/calendar-emailsAny roleThe signed-in user’s calendar emails (email, proven, proven_at, pending code and code_expires_at, last_error, last_failure with the refused proof’s reason (not_aligned, from_mismatch, expired), at, the parsed From from on a mismatch, SPF/DKIM/alignment results and plain-language message, active), the hive’s address and the invites_enabled / files_enabled switches; the owner also gets recent_proof_attempts (unknown-code proof mails, sender masked); ?all=1 adds the whole allowlist for the owner (no codes)pkg/dashboard/api_meetings_email.go:64
POST/api/meetings/calendar-emailsAny roleRegister {email} for the signed-in user: 201 {email, address, instruction} with a proof code valid for 24 hours and the instruction to send a mail from that address to hive@<host> with the code in the subject. At most 10 per user. Audited as calendar-email-addpkg/dashboard/api_meetings_email.go:65
DELETE/api/meetings/calendar-emailsAny roleRemove ?email= from the signed-in user’s list; the owner may add &login= to remove another user’s. Audited as calendar-email-removepkg/dashboard/api_meetings_email.go:66