Integration Surface

API Reference

Overview

This app exposes an HTTP API with broad read coverage plus selected write endpoints for review and memory capture. Human-readable documentation on this page and the OpenAPI documents are public. The actual protected business endpoints live under /api/... and require API keys, but the machine-readable OpenAPI manifests under /api/openapi*.json are intentionally public for external tooling. Swagger UI is available at /docs.

Datetime inputs such as start_at and end_at are interpreted in Europe/London when sent without an explicit offset. Datetime outputs are returned as ISO timestamps with offsets.

Open Custom GPT Guide

Authentication

Entry Points

OpenAPI Split Guidance

ChatGPT actions currently accept only a limited number of routes per manifest. BR-AI therefore exposes several use-case-specific OpenAPI documents in addition to the full schema.

Health And Summary

  • GET /api/health: app and dependency configuration summary.
  • GET /api/system-health: latest stored health checks. Supports ?refresh=true.
  • GET /api/summary: top-level counts for streams, events, jobs, review backlog, and webhooks.

API Access Management

  • GET /api/v1/models: list available OpenAI-compatible chat model identifiers, including the stable alias br-ai-assistant.
  • POST /api/v1/chat/completions: grounded OpenAI-compatible chat endpoint backed by BR-AI retrieval tools.
  • GET /api/api-access/keys: list issued API keys without exposing full tokens.
  • POST /api/api-access/keys: create a new API key. Accepts JSON body {"label": "..."}. The full token is only returned once.
  • POST /api/api-access/keys/{key_id}/revoke: revoke a key.

Frigate Instances

  • GET /api/frigate-instances: all configured Frigate instances.
  • GET /api/frigate-instances/{instance_id}: one instance plus its streams.

Streams

  • GET /api/streams: all streams.
  • Filters: frigate_instance_id, enabled.
  • GET /api/streams/{stream_id}: one stream plus recent events.
GET /api/streams
GET /api/streams?frigate_instance_id=1
GET /api/streams?enabled=true
GET /api/streams/28

Audio Sources

  • GET /api/audio-sources: all configured audio sources.
  • Filters: enabled.
  • GET /api/audio-sources/{source_id}: one source plus recent transcript jobs.

Events And Media

  • GET /api/events: latest 100 stored events.
  • GET /api/events/{event_id}: full stored event record, including best-result payload and metadata.
  • GET /api/events/{event_id}/media: redirect to the selected event media asset or best available event image.
  • GET /api/events/{event_id}/assets: media assets for one event, including presigned URLs.
GET /api/events
GET /api/events/13091
GET /api/events/13091/media
GET /api/events/13091/assets

Detection Search

GET /api/detections is the main filtered detection endpoint and the best choice for dashboards and exports.

Supported query parameters:

  • event_type: face, plate, or other stored event type.
  • frigate_instance_id: integer filter.
  • stream_id: integer filter.
  • identity: substring filter on resolved face identities.
  • plate: substring filter on accepted plate text.
  • confidence_min: minimum confidence threshold.
  • speed_min: minimum speed threshold in mph.
  • start_at, end_at: local datetime window.
  • sort_by: occurred_at, speed, or confidence.
  • sort_dir: asc or desc.
  • limit: default 50, maximum 500.
  • offset: default 0.
GET /api/detections?event_type=plate&limit=25
GET /api/detections?event_type=plate&stream_id=28&start_at=2026-05-07T18:00&end_at=2026-05-07T19:00
GET /api/detections?event_type=plate&speed_min=25&sort_by=speed&sort_dir=desc
GET /api/detections?event_type=face&identity=Dave

Plate-Focused Endpoints

  • GET /api/plates: reverse-chronological ALPR detections.
  • Filters: q, stream_id, start_at, end_at, speed_min, limit.
  • GET /api/speed-observations: raw speed observation records. Supports stream_id and limit.

Face Review And People

  • GET /api/face-review-items: face review backlog or resolved review items. Supports status and limit.
  • GET /api/voice-review-items: voice review backlog or resolved review items. Supports status and limit.
  • GET /api/people: known people in the face gallery.
  • GET /api/people/{person_id}: one known person plus recent sightings and trusted voice samples.

Visits And Location Data

  • GET /api/visits: canonical location visits. Supports person_id, source, start_at, end_at, q, limit, and offset.
  • GET /api/visits/{visit_id}: one location visit.
  • GET /api/location-data/settings: Traccar/location-data settings rows.
  • GET /api/location-data/mappings: device-to-person mappings. Supports traccar_setting_id.
  • GET /api/location-data/positions: raw tracked positions. Supports person_id, device_id, start_at, end_at, limit, and offset.
  • GET /api/location-data/google-timeline-imports: recent Google Timeline import jobs. Supports person_id, status, and limit.

Calendar Integration

  • GET /api/calendar-integration/settings: current Google Calendar integration state.
  • PATCH /api/calendar-integration/settings: enable/disable and rename the integration.
  • POST /api/calendar-integration/refresh: discover calendars from Google and sync them into BR-AI.
  • GET /api/calendar-integration/calendars: discovered calendars plus read/write allowlist flags. Supports selected_for_read and selected_for_write.
  • PATCH /api/calendar-integration/calendars/{target_id}: change the read/write flags for one calendar target.

Messages

  • GET /api/messages: canonical message rows with attachments. Supports contact_name, sender_name, recipient_name, channel, start_at, end_at, has_attachments, limit, and offset.
  • GET /api/messages/{message_id}: one message with attachment detail.
  • GET /api/message-import-jobs: recent Facebook/Messenger import jobs. Supports status and limit.
  • GET /api/message-party-aliases: known message-party aliases. Supports channel, unresolved_only, and limit.
  • PATCH /api/message-party-aliases/{alias_id}: map or remap a raw messaging name to a person_id, and optionally set is_self_hint. This also backfills matching messenger-family messages.
  • GET /api/message-contact-days: derived day/contact blobs. Supports person_id, contact_name, summary_date, channel_family, limit, and offset.
  • GET /api/message-contact-days/{contact_day_id}: one derived day/contact row plus its summary record.

Jobs

  • GET /api/ingest-jobs: latest 100 ingest jobs.
  • GET /api/transcripts: latest 100 transcript jobs.
  • GET /api/transcripts/{job_id}: one transcript job.
  • GET /api/transcripts/{job_id}/segments: flattened transcript segments for one transcript job.

Transcript Explorer API

  • GET /api/transcript-explorer/sources: transcript-capable sources.
  • GET /api/transcript-explorer/segments: transcript segments for a source and time window.

Recommended query parameters for /api/transcript-explorer/segments:

  • source_key: preferred form, for example stream:4 or audio_source:2.
  • Or use source_type plus source_id.
  • Windowing: day, start_time, end_time, or explicit start_at and end_at.
  • Optional filters: speaker, limit, offset.
GET /api/transcript-explorer/sources
GET /api/transcript-explorer/segments?source_key=audio_source:1&day=2026-05-07
GET /api/transcript-explorer/segments?source_key=stream:4&start_at=2026-05-07T09:00&end_at=2026-05-07T11:00&limit=200

Transcript Semantics And Conversations

  • GET /api/transcript-semantic-jobs: overnight transcript-semantic job queue. Supports status, source_kind, source_id, and limit.
  • GET /api/transcript-time-chunks: raw fixed time chunks used for transcript embeddings. Supports source_kind, source_id, summary_date, start_at, end_at, limit, and offset.
  • GET /api/threads: ongoing matters linked across conversations, self notes, and message summaries. Supports q, classification, status, limit, and offset.
  • GET /api/threads/{thread_id}: one conversation thread including evidence links.
  • PATCH /api/threads/{thread_id}: review or correct an inferred thread by updating title, classification, status, summary_text, or review_note.
  • GET /api/memory-items: durable memory items such as facts, place assertions, relationships, preferences, ongoing states, and meaningful decisions. Supports q, memory_type, source_kind, status, review_status, limit, and offset.
  • POST /api/memory-items: create a direct user-asserted memory item. Useful for facts the assistant should rely on, such as home address, important relationships, or durable preferences.
  • GET /api/memory-items/{memory_item_id}: one memory item including evidence links.
  • PATCH /api/memory-items/{memory_item_id}: review or correct an inferred memory item by updating memory_type, title, body, status, review_status, review_note, importance_score, confidence, or due_at.
  • GET /api/task-suggestions: reviewable task candidates derived from actionable memory items. Supports q, status, limit, and offset.
  • GET /api/task-suggestions/{task_suggestion_id}: one task suggestion including source-memory and thread references.
  • PATCH /api/task-suggestions/{task_suggestion_id}: set task suggestion status to pending_review, approved, rejected, or exported.
  • GET /api/conversations: AI-derived transcript conversations. Supports q, source_kind, source_id, summary_date, start_at, end_at, classification, limit, and offset.
  • GET /api/self-notes: AI-derived self-directed transcript notes. Supports q, source_kind, source_id, summary_date, start_at, end_at, note_type, limit, and offset.
  • GET /api/self-notes/{self_note_id}: one self note including embedding metadata.
  • POST /api/self-notes: create a manual self note. Accepts JSON fields note_text, optional title, note_type, occurred_at, and source_name.

Assistant-Oriented Endpoints

  • GET /api/assistant/where-was-person-on-date: ultra-simple visit answer for external LLMs. Requires person_name and day and returns a flat list plus a summary string.
  • GET /api/assistant/where-was-person-at: point-in-time lookup for a person. Returns the visit covering a timestamp, plus the nearest surrounding visits if no exact visit matches.
  • GET /api/assistant/visit-timeline: compact day timeline for a person, without the heavy raw visit payload. Supports person_id, optional person_name, and day as YYYY-MM-DD.
  • GET /api/assistant/visits-on-date: simple day-based visit lookup for a person. Supports person_id, optional person_name, and day as YYYY-MM-DD.
  • GET /api/assistant/place-visit-count: counts visits matching a place query and returns grouped place candidates, useful for vague place names or towns.
  • GET /api/assistant/last-time-at-place: returns the most recent visit matching a place query, plus a few recent matching visits.
  • GET /api/assistant/place-history: returns compact visit history for a place query.
  • GET /api/assistant/search-messages: semantic search across message contact-days and summaries. Best for “when did we discuss X?” and “what did they say about Y?”.
  • GET /api/assistant/messages-latest-on: returns the best recent message-day match for a topic, plus nearby matches.
  • GET /api/assistant/messages-with-contact: returns compact day bundles for a contact over a date range, useful for “what plans did we make last weekend with X?”.
  • GET /api/assistant/search-transcripts: semantic search across transcript conversations, self notes, and raw chunks.
  • GET /api/assistant/transcripts-latest-on: returns the best recent transcript match for a topic, plus nearby matches.
  • GET /api/assistant/conversations-with-source: returns extracted transcript conversations for a source over a date range.
  • GET /api/assistant/search-self-notes: searches transcript-derived and manual self notes.
  • GET /api/assistant/cross-domain-latest-on: combines memory, messages, and transcripts for “what’s the latest on X?” style questions.
  • GET /api/assistant/agreements: pulls likely agreements, decisions, and commitments across memory, messages, and transcripts.
  • GET /api/assistant/plans: pulls likely plans and proposed actions across memory, messages, and transcripts.
  • GET /api/assistant/latest-on-person: returns recent cross-domain evidence involving a named person.
  • GET /api/assistant/latest-on?q=...: find the best-matching ongoing thread for a topic and return the linked thread, recent memory items, task suggestions, and compact evidence objects. Supports optional person_id and limit_candidates.
  • GET /api/assistant/open-commitments: actionable commitments not marked resolved or dormant. Supports q, person_id, and limit.
  • GET /api/assistant/current-tasks: live open tasks synced from Todoist, which is the canonical task system. Supports q, project_row_id, and limit.
  • GET /api/assistant/waiting-ons: items that depend on another person or external process. Supports q, person_id, and limit.
  • GET /api/assistant/unresolved-issues: open issues not marked resolved or dormant. Supports q, person_id, and limit.
  • GET /api/assistant/recent-decisions: recent decision-type memory items. Supports q, person_id, days, and limit.
GET /api/assistant/latest-on?q=electricity%20contract
GET /api/assistant/where-was-person-on-date?person_name=Behnam&day=2026-05-14
GET /api/assistant/where-was-person-at?person_name=Behnam&at=2026-05-14T15:30:00Z
GET /api/assistant/visit-timeline?person_id=3&day=2026-05-14
GET /api/assistant/visits-on-date?person_id=3&day=2026-05-14
GET /api/assistant/place-visit-count?person_name=Behnam&q=Sheffield
GET /api/assistant/last-time-at-place?person_name=Behnam&q=Mercia%20School
GET /api/assistant/place-history?person_name=Behnam&q=St%20Oswalds
GET /api/assistant/search-messages?person_name=Behnam&contact_name=Sarah&q=price
GET /api/assistant/messages-latest-on?person_name=Behnam&contact_name=Sarah&q=electricity%20contract
GET /api/assistant/messages-with-contact?person_name=Behnam&contact_name=Sarah&start_date=2026-05-09&end_date=2026-05-12
GET /api/assistant/search-transcripts?source_name=Behnam&q=electricity%20contract
GET /api/assistant/transcripts-latest-on?source_name=Behnam&q=price
GET /api/assistant/conversations-with-source?source_name=Behnam&start_date=2026-05-14&end_date=2026-05-16
GET /api/assistant/search-self-notes?source_name=Behnam&q=remember
GET /api/assistant/cross-domain-latest-on?person_name=Behnam&with_name=Sarah&q=electricity%20contract
GET /api/assistant/agreements?person_name=Behnam&with_name=Sarah&q=price
GET /api/assistant/plans?person_name=Behnam&with_name=Sarah&q=weekend
GET /api/assistant/latest-on-person?person_name=Sarah
GET /api/assistant/current-tasks?q=broker
GET /api/assistant/open-commitments?person_id=3
GET /api/assistant/waiting-ons?q=broker
GET /api/assistant/unresolved-issues?q=contract
GET /api/assistant/recent-decisions?days=14

Todoist Integration

  • GET /api/todoist-integration/settings: current Todoist integration state.
  • PATCH /api/todoist-integration/settings: enable/disable Todoist export, choose the default project row, control whether only approved suggestions may be exported, and toggle automatic Inbox creation.
  • POST /api/todoist-integration/refresh: discover Todoist projects and sync them into BR-AI.
  • GET /api/todoist-integration/projects: discovered projects plus read/export allowlist flags. Supports selected_for_read and selected_for_export.
  • PATCH /api/todoist-integration/projects/{project_row_id}: change read eligibility, export eligibility, and optionally make one project the default export target.
  • POST /api/todoist-integration/tasks/refresh: fetch open Todoist tasks from read-enabled projects into BR-AI.
  • GET /api/todoist-integration/tasks: list synced Todoist tasks. Supports completed, project_row_id, and limit.
  • PATCH /api/todoist-integration/tasks/{task_row_id}: update a synced Todoist task, including content, description, due date, review state, or moving it to another project.
  • POST /api/todoist-integration/tasks/{task_row_id}/complete: mark a synced Todoist task complete in Todoist.
  • DELETE /api/todoist-integration/tasks/{task_row_id}: delete a synced Todoist task in Todoist and remove its BR-AI mirror row.
  • POST /api/todoist-integration/export/{task_suggestion_id}: export one approved task suggestion to Todoist and persist the returned todoist_task_id. Export is blocked if a matching synced open Todoist task already exists in the chosen target project.

Webhooks

  • GET /api/webhook-configs: configured outbound webhooks.
  • GET /api/webhook-deliveries: latest 100 webhook delivery attempts.

Response Notes

  • List endpoints either return a top-level array or an object with count, resource rows, and when relevant pagination.
  • Detection-style endpoints include UI-friendly URLs such as media_url, plate_url, and event debug/media references.
  • Event detail responses may include stored metadata and best-result payloads, which are useful for diagnostics but should be treated as implementation-facing fields.