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.
| Method | Path | Auth | Purpose | Source |
|---|---|---|---|---|
GET | /api/knowledge | Dashboard auth/session | Paginated 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/export | Dashboard auth/session | Knowledge Export | pkg/dashboard/api.go:366 |
POST | /mcp/knowledge | Public (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 not | Public 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/search | Dashboard auth/session | Knowledge Search | pkg/dashboard/api.go:367 |
GET | /api/knowledge/toc | Dashboard auth/session | Scoped 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/effective | Dashboard auth/session | Effective 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/session | Full 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-legacy | Owner only | One-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/public | Dashboard auth/session | Public Knowledge MCP sharing status (enabled, tags, source, endpoint URL) | pkg/dashboard/api.go:376 |
PUT | /api/knowledge/public | Owner only | Persist public Knowledge MCP sharing setting; overrides env vars until changed | pkg/dashboard/api.go:377 |
GET | /api/knowledge/health | Dashboard auth/session | Knowledge Health | pkg/dashboard/api.go:378 |
GET | /api/knowledge/stats | Dashboard auth/session | Knowledge Stats | pkg/dashboard/api.go:379 |
GET | /api/knowledge/graph | Dashboard auth/session | Knowledge Graph | pkg/dashboard/api.go:380 |
GET | /api/knowledge/fact-history | Dashboard auth/session | Fact History | pkg/dashboard/api.go:381 |
POST | /api/knowledge/create | Dashboard auth/session | Create 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:<name>, cli:<claude|codex|gemini>, memhash:<hex> and repo:<org>/<repo> tags (400 otherwise) | pkg/dashboard/api.go:382 |
POST | /api/knowledge/import | Dashboard auth/session | Knowledge Import | pkg/dashboard/api.go:383 |
POST | /api/knowledge/promote | Dashboard auth/session | Knowledge Promote | pkg/dashboard/api.go:389 |
GET | /api/knowledge/subscriptions | Dashboard auth/session | Knowledge Subs List | pkg/dashboard/api.go:390 |
POST | /api/knowledge/subscriptions | Dashboard auth/session | Knowledge Subs Add | pkg/dashboard/api.go:391 |
DELETE | /api/knowledge/subscriptions | Dashboard auth/session | Knowledge Subs Remove | pkg/dashboard/api.go:392 |
PUT | /api/knowledge/{layer}/{slug} | Dashboard auth/session | Knowledge Update | pkg/dashboard/api.go:393 |
DELETE | /api/knowledge/{layer}/{slug} | Dashboard auth/session | Knowledge Delete | pkg/dashboard/api.go:394 |
GET | /api/knowledge/{layer} | Dashboard auth/session | Knowledge Layer | pkg/dashboard/api.go:395 |
GET | /api/knowledge/{layer}/{slug} | Dashboard auth/session | Knowledge Fact | pkg/dashboard/api.go:396 |
PUT | /api/knowledge/enabled | Owner only | Knowledge Toggle | pkg/dashboard/api.go:397 |
GET | /api/knowledge/bead-synthesizer | Dashboard auth/session | Bead Synth Status | pkg/dashboard/api.go:398 |
PUT | /api/knowledge/bead-synthesizer/enabled | Owner only | Bead Synth Toggle | pkg/dashboard/api.go:399 |
GET | /api/knowledge/vaults | Dashboard auth/session | Vaults List | pkg/dashboard/api.go:400 |
POST | /api/knowledge/vaults | Owner only | Vaults Connect | pkg/dashboard/api.go:401 |
DELETE | /api/knowledge/vaults | Dashboard auth/session | Vaults Disconnect | pkg/dashboard/api.go:402 |
POST | /api/knowledge/vaults/reindex | Dashboard auth/session | Vaults Reindex | pkg/dashboard/api.go:403 |
GET | /api/knowledge/vaults/{name}/facts | Dashboard auth/session | Vault Facts | pkg/dashboard/api.go:404 |
GET | /api/config/knowledge/connectors | Dashboard auth/session | Knowledge connectors config (name, type, layer, scope, env/file auth reference) and registered types | pkg/dashboard/api.go |
PUT | /api/config/knowledge/connectors | Owner only | Replace knowledge.connectors after validation; inline secrets rejected | pkg/dashboard/api.go |
GET | /api/config/knowledge/connectors/status | Dashboard auth/session | Per-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 status | pkg/dashboard/api.go |
POST | /api/config/knowledge/connectors/validate | Owner only | Dry-run validate one connector entry (no network) | pkg/dashboard/api.go |
POST | /api/config/knowledge/connectors/{name}/sync | Owner only | Start an immediate background sync of one connector | pkg/dashboard/api.go |
GET | /api/config/knowledge/agent-scopes | Dashboard auth/session | Per-agent knowledge scopes (knowledge.agent_scopes: layers, repos, types, tags, include_states) (docs) | pkg/dashboard/api.go |
PUT | /api/config/knowledge/agent-scopes | Owner only | Replace knowledge.agent_scopes after validating layer and state names; persisted and audited as config_knowledge_agent_scopes | pkg/dashboard/api.go |
GET | /api/config/knowledge/pipeline | Owner only | Scalar 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/pipeline | Owner only | Update 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_pipeline | pkg/dashboard/api.go |
GET | /api/knowledge/git-sources | Dashboard auth/session | Git Sources List | pkg/dashboard/api.go:414 |
POST | /api/knowledge/git-sources | Owner only | Git Sources Connect | pkg/dashboard/api.go:415 |
DELETE | /api/knowledge/git-sources | Owner only | Git Sources Disconnect | pkg/dashboard/api.go:416 |
POST | /api/knowledge/obsidian/sync | Dashboard auth/session | Obsidian Sync | pkg/dashboard/api.go:417 |
GET | /api/knowledge/documents | Dashboard auth/session | Documents List | pkg/dashboard/api.go:418 |
POST | /api/knowledge/documents | Dashboard auth/session | Documents Import | pkg/dashboard/api.go:419 |
GET | /api/knowledge/documents/{slug} | Dashboard auth/session | Document Get | pkg/dashboard/api.go:420 |
DELETE | /api/knowledge/documents/{slug} | Dashboard auth/session | Document Delete | pkg/dashboard/api.go:421 |
POST | /api/knowledge/documents/{slug}/reimport | Dashboard auth/session | Document Reimport | pkg/dashboard/api.go:422 |
GET | /api/knowledge/context7/search | Dashboard auth/session | Context7 Search | pkg/dashboard/api.go:423 |
POST | /api/knowledge/cleanup-orphans | Dashboard auth/session | Cleanup Orphans | pkg/dashboard/api.go:424 |
GET | /api/knowledge/channels | Dashboard auth/session | Knowledge Channels List | pkg/dashboard/api.go:387 |
POST | /api/knowledge/channels | Dashboard auth/session | Knowledge Channel Create | pkg/dashboard/api.go:388 |
GET | /api/knowledge/connectors | Dashboard auth/session | Knowledge 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}/sync | Owner only | Start one connector sync now (202; 404 unknown, 409 running) | pkg/dashboard/api_knowledge_connectors.go:25 |
POST | /api/knowledge/publish/sync | Owner only | Run 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}/auth | Dashboard auth/session | Interactive 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/connect | Owner only | Start 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/disconnect | Owner only | Sign 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/complete | Owner only | Finish 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.md | pkg/dashboard/api_inbox.go:32 |
GET | /api/inbox | Dashboard auth/session | Inbox 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.md | pkg/dashboard/api_inbox.go:24 |
POST | /api/inbox/route | Owner only | Route 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/email | Hub relay signature | Mail-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 signature | pkg/dashboard/api_inbox_email.go:29 |
POST | /api/inbox/email/chunk | Hub relay signature, per piece | One 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 full | pkg/dashboard/api_inbox_email.go:30 |
POST | /api/inbox/email/{id}/approve | Owner only | Approve a mailed-in item from outside the allowlist. Audited as inbox-email-approve | pkg/dashboard/api_inbox_email.go:31 |
POST | /api/inbox/email/{id}/decline | Owner only | Delete a mailed-in item and its file. Unapproved items are also deleted after 14 days. Audited as inbox-email-decline | pkg/dashboard/api_inbox_email.go:32 |
GET | /api/inbox/email/{id}/file | Owner or read-write | The stored file with its sniffed type (Markdown as text/plain), inline for images (audio and video download), nosniff and a sandbox CSP | pkg/dashboard/api_inbox_email.go:33 |
POST | /api/inbox/dismiss | Owner only | Bulk “Knowledge only”: {items: [{source, item_id}], undo?} | pkg/dashboard/api_inbox.go:26 |
GET | /api/inbox/settings | Dashboard auth/session | Auto-routing rules, default RFC repo, dibs URL, destination readiness | pkg/dashboard/api_inbox.go:27 |
POST | /api/inbox/settings | Owner only | Update 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}/content | Dashboard auth/session | Full 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}/transcribe | Owner or read-write | Queue 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.md | pkg/dashboard/api_inbox.go:33 |
GET | /api/inbox/transcriptions | Dashboard auth | Live 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.md | pkg/dashboard/api_inbox.go:34 |
GET | /api/inbox/{source}/{id}/audio | Owner or read-write | Mint 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/stream | Owner or read-write | Stream 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/uploads | Owner or read-write | Add 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.md | pkg/dashboard/api_inbox_uploads.go:34 |
POST | /api/inbox/uploads/url | Owner or read-write | Add 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/recordings | Owner or read-write | Start 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.md | pkg/dashboard/api_inbox_recordings.go:20 |
POST | /api/inbox/recordings/{id}/chunks | The 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}/finalize | The recorder | End 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 owner | Abort 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}/audio | Owner or read-write | Play 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 it | Delete 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/settings | Owner only | Meetings 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/settings | Owner only | Update 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_settings | pkg/dashboard/api_meetings.go:130 |
POST | /api/meetings | Owner only | Send 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_join | pkg/dashboard/api_meetings.go:131 |
GET | /api/meetings | Owner only | {meetings: [...]}, newest first | pkg/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 unknown | pkg/dashboard/api_meetings.go:133 |
POST | /api/meetings/{id}/leave | Owner only | Make hive leave; returns the record. Audited as meeting_leave | pkg/dashboard/api_meetings.go:134 |
POST | /api/meetings/{id}/voice | Owner only | {enabled}: allow hive to answer aloud when addressed (with meetings.voice_on_address). Audited as meeting_voice | pkg/dashboard/api_meetings.go:135 |
POST | /api/meetings/{id}/research/{rid}/approve | Owner only | Dispatch a research item waiting past the per-meeting cap; 409 when it is not waiting or the live session ended. Audited as meeting_research_approve | pkg/dashboard/api_meetings.go:136 |
POST | /api/meetings/{id}/approve | Owner only | Approve 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_approve | pkg/dashboard/api_meetings.go:137 |
POST | /api/meetings/{id}/decline | Owner only | Decline a platform join request with meeting.leave. Audited as meeting_request_decline | pkg/dashboard/api_meetings.go:138 |
DELETE | /api/meetings/{id} | Owner only | Delete 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_delete | pkg/dashboard/api_meetings_delete.go:44 |
POST | /api/meetings/clear-finished | Owner only | Delete 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_delete | pkg/dashboard/api_meetings_delete.go:45 |
GET | /api/meetings/{id}/ws | Owner only | WebSocket live panel: a snapshot frame, then meeting, line, intent, research, notes and dropped frames for the meeting | pkg/dashboard/api_meetings.go:139 |
GET | /api/meetings/schedule | Owner or read-write | The 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 Calendar | pkg/dashboard/api_meetings_schedule.go:86 |
POST | /api/meetings/schedule | Owner or read-write | Schedule 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_add | pkg/dashboard/api_meetings_schedule.go:87 |
POST | /api/meetings/schedule/{eid}/approve | Owner only | Schedule an event awaiting approval. 409 when it is not awaiting approval. Audited as meeting_schedule_approve | pkg/dashboard/api_meetings_schedule.go:88 |
POST | /api/meetings/schedule/{eid}/decline | Owner only | Decline an event awaiting approval; later updates of the same invite stay declined. Audited as meeting_schedule_decline | pkg/dashboard/api_meetings_schedule.go:89 |
POST | /api/meetings/schedule/{eid}/cancel | Owner only | Stop hive joining the event (every occurrence of a series); a meeting already live is not left. Audited as meeting_schedule_cancel | pkg/dashboard/api_meetings_schedule.go:90 |
POST | /api/meetings/schedule/{eid}/skip | Owner only | Skip the next occurrence hive has not joined: a single meeting becomes skipped, a series moves on. Audited as meeting_schedule_skip | pkg/dashboard/api_meetings_schedule.go:91 |
DELETE | /api/meetings/schedule/{eid} | Owner only | Delete 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 meeting | pkg/dashboard/api_meetings_delete.go:46 |
GET | /api/meetings/actions | Owner or read-write | Drafts 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 things | pkg/dashboard/api_meetings_actions.go:69 |
GET | /api/meetings/actions/settings | Owner or read-write | meetings.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_overrides | pkg/dashboard/api_meetings_actions.go:70 |
PUT | /api/meetings/actions/settings | Owner only | Save {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_settings | pkg/dashboard/api_meetings_actions.go:71 |
GET | /api/meetings/model | Owner or read-write | The 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 backends | pkg/dashboard/api_meetings_model.go:63 |
PUT | /api/meetings/model | Owner only | Save {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_settings | pkg/dashboard/api_meetings_model.go:64 |
POST | /api/meetings/actions/{aid}/edit | Owner or read-write | Change 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_edit | pkg/dashboard/api_meetings_actions.go:72 |
POST | /api/meetings/actions/{aid}/approve | Owner or read-write | Create 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_approve | pkg/dashboard/api_meetings_actions.go:73 |
POST | /api/meetings/actions/{aid}/reject | Owner or read-write | Reject a pending or failed draft; nothing is created. Audited as meeting_action_reject | pkg/dashboard/api_meetings_actions.go:74 |
GET | /api/meetings/persona | Owner or read-write | Settings, 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 settings | pkg/dashboard/api_meetings_persona.go:166 |
PUT | /api/meetings/persona | Owner or read-write | Save 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/sample | Owner or read-write | Speak 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 failed | pkg/dashboard/api_meetings_persona.go:168 |
GET | /api/meetings/persona/sample | Owner or read-write | The 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/invites | Hub relay signature | Calendar 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 email | pkg/dashboard/api_meetings_email.go:62 |
POST | /api/meetings/calendar-emails/proof | Hub relay signature | A 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-emails | Any role | The 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-emails | Any role | Register {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-add | pkg/dashboard/api_meetings_email.go:65 |
DELETE | /api/meetings/calendar-emails | Any role | Remove ?email= from the signed-in user’s list; the owner may add &login= to remove another user’s. Audited as calendar-email-remove | pkg/dashboard/api_meetings_email.go:66 |