What BR-AI is good for

BR-AI already acts as an evidence-backed memory and inference service. It is strongest when the external assistant asks for structured facts and then cites the underlying evidence.

The assistant should prefer BR-AI for:

• where someone was and when
• what conversations happened and who was involved
• what self notes were recorded
• what longer-running threads exist
• what memory items and task suggestions have been extracted

Recommended assistant architecture

1. User asks a question.
2. The assistant decides which BR-AI domain is relevant.
3. The assistant queries one or more BR-AI API endpoints.
4. The assistant synthesizes an answer.
5. The assistant cites the BR-AI evidence objects it relied on.

Authentication

• All API access requires an API key.
• Send the key in X-API-Key or Authorization: Bearer YOUR_KEY.
• Issue or revoke keys from the API Access settings page.

Which OpenAPI Manifest To Use

• /api/openapi-assistant-v2.json: best default for Custom GPT experimentation. It is smaller and more strictly typed, which is better for ChatGPT actions.
• /api/openapi-chat.json: use for external chat applications that expect an OpenAI-style /v1/chat/completions backend instead of many narrow helper routes.
• /api/openapi-assistant.json: broader assistant manifest if you need more helper routes and are not seeing tool instability.
• /api/openapi-integrations.json: use when the GPT also needs Calendar, Todoist, alias-mapping, or self-note creation actions.
• /api/openapi-observability.json: use for detection/stream/people focused tools.
• /api/openapi-ingestion.json: use for transcript/location/job focused tooling.
• /api/openapi.json: full schema, not ideal for ChatGPT actions because it is larger.

Recommended API usage by question type

Visits and location history

• Use GET /api/visits for filtered lists.
• Use GET /api/visits/{visit_id} for one visit.
• Filter primarily by person_id, time range, and source.

Raw messages

• Use GET /api/messages for direct message retrieval.
• Use GET /api/message-contact-days for aggregated day/contact memory.

Transcript-derived intelligence

• Use GET /api/conversations for AI-derived transcript conversations.
• Use GET /api/self-notes for self-directed monologue notes.
• Use POST /api/self-notes when the external assistant needs to save an explicit user-provided reminder or note to self.
• Use GET /api/transcript-time-chunks only when raw chunk text is needed.

Calendar and tasks

• Use GET /api/calendar-integration/calendars to understand which Google calendars BR-AI is explicitly allowed to read and write.
• Use GET /api/todoist-integration/projects to understand which Todoist projects BR-AI is explicitly allowed to read from and export tasks into.
• Use POST /api/todoist-integration/tasks/refresh and GET /api/todoist-integration/tasks to inspect the canonical Todoist task list before proposing or exporting duplicates.
• Use PATCH /api/todoist-integration/tasks/{task_row_id}, POST /api/todoist-integration/tasks/{task_row_id}/complete, and DELETE /api/todoist-integration/tasks/{task_row_id} to sort, accept, move, or reject tasks after they already exist in Todoist.
• Use POST /api/todoist-integration/export/{task_suggestion_id} only when the user explicitly asks to push a particular suggestion into Todoist.

Long-running matters

• Use GET /api/threads and GET /api/threads/{thread_id} for recurring issues and ongoing matters.
• Prefer the assistant-focused helpers first when they fit: GET /api/assistant/latest-on, GET /api/assistant/open-commitments, GET /api/assistant/waiting-ons, GET /api/assistant/unresolved-issues, GET /api/assistant/recent-decisions.
• Use PATCH /api/threads/{thread_id} only when the user is explicitly correcting or confirming an inferred thread.
• Use GET /api/memory-items for durable facts, place assertions, preferences, relationships, ongoing states, and meaningful decisions.
• Use POST /api/memory-items when the user explicitly wants to store a durable fact or context item that the system should rely on later.
• Use PATCH /api/memory-items/{memory_item_id} when the user is explicitly reviewing, confirming, dismissing, or correcting a memory item.
• Use GET /api/task-suggestions for reviewable follow-up tasks.
• Use PATCH /api/task-suggestions/{task_suggestion_id} to approve, reject, or otherwise review a suggestion.

Suggested question-routing logic for a Custom GPT

• If the user asks “where/when was I” or “where did X happen”, start with /api/visits.
• If the user asks a simple day-based question like “where did I go last Thursday?”, prefer /api/assistant/where-was-person-on-date first. Use /api/assistant/visit-timeline only if a fuller structured timeline is needed, and /api/assistant/visits-on-date only if full visit detail is actually needed.
• If the user asks about a specific timestamp, prefer /api/assistant/where-was-person-at.
• If the user asks “how many times have I been to X?”, prefer /api/assistant/place-visit-count.
• If the user asks “when was I last at X?”, prefer /api/assistant/last-time-at-place.
• If the user asks for prior visits to a place, prefer /api/assistant/place-history.
• If the user asks “when did we discuss X?” or “what did they say about Y?”, prefer /api/assistant/search-messages.
• If the user asks “what’s the latest in messages about X?”, prefer /api/assistant/messages-latest-on.
• If the user asks “what plans did we make with X last weekend?”, prefer /api/assistant/messages-with-contact with a narrow date range.
• If the user asks “when did I talk about X?” or “what was said in transcripts about Y?”, prefer /api/assistant/search-transcripts.
• If the user asks “what’s the latest transcript evidence on X?”, prefer /api/assistant/transcripts-latest-on.
• If the user wants a source/date-bounded conversation list, prefer /api/assistant/conversations-with-source.
• If the user asks what they told themselves or asked to remember, prefer /api/assistant/search-self-notes.
• If the user asks “what’s the latest on X?” across everything, prefer /api/assistant/cross-domain-latest-on.
• If the user asks what was agreed with someone, prefer /api/assistant/agreements.
• If the user asks what plans were made with someone, prefer /api/assistant/plans.
• If the user asks generally about a named person across domains, prefer /api/assistant/latest-on-person.
• If the user asks “what’s the latest on X”, start with /api/assistant/latest-on, then only drill down into /api/threads, /api/memory-items, or /api/conversations if needed.
• If the user asks “what did I tell myself” or “what reminders did I leave”, start with /api/self-notes.
• If the user asks “what should I do next” or “what am I waiting on”, start with /api/assistant/current-tasks, then use /api/assistant/open-commitments and /api/assistant/waiting-ons for context.
• If the user asks about unresolved problems, use /api/assistant/unresolved-issues.
• If the user asks what was decided recently, use /api/assistant/recent-decisions.
• If the user asks about the calendar, first check what BR-AI is allowed to read and write via /api/calendar-integration/calendars.
• If the user asks to push something into Todoist, first inspect /api/todoist-integration/projects and confirm the export target.
• If the user wants to map a raw contact name to a known person, use PATCH /api/message-party-aliases/{alias_id}.
• If the user asks for raw proof, drill into the underlying message, conversation, visit, or transcript endpoints.

Prompt guidance for the external assistant

Your assistant should be instructed to:

• treat BR-AI as an evidence source, not an oracle
• prefer threads and memory items for higher-level questions
• prefer visits, messages, and conversations for factual verification
• cite IDs, timestamps, names, and source objects in answers
• say when the evidence is incomplete or ambiguous

Note: the assistant-focused OpenAPI manifest intentionally omits the generic /api/visits, message, transcript-self-note, and other broad exploratory routes so external LLMs use the more stable helper endpoints first.

Example system prompt fragment

Use BR-AI as an evidence-backed tool, not as background knowledge.

For questions about where, when, what was discussed, what was agreed, what was planned, what I told myself, or what is latest on a topic:
1. Call the most specific BR-AI assistant endpoint first.
2. Prefer assistant endpoints over broad list endpoints.
3. If one endpoint is insufficient, make at most 1-2 follow-up BR-AI calls.
4. Answer only from returned evidence.
5. Separate direct evidence from inference.
6. Cite timestamps, names, and object IDs where available.
7. If BR-AI returns weak or conflicting evidence, say so plainly.

Routing rules:
- day-based location question -> /api/assistant/where-was-person-on-date or /api/assistant/visit-timeline
- point-in-time location question -> /api/assistant/where-was-person-at
- place frequency / last visit / place history -> the place assistant endpoints
- "when did we discuss X?" -> /api/assistant/search-messages
- "what's the latest in messages about X?" -> /api/assistant/messages-latest-on
- transcript topic search -> /api/assistant/search-transcripts
- "what did I tell myself?" -> /api/assistant/search-self-notes
- cross-domain "latest on X" -> /api/assistant/cross-domain-latest-on
- agreements -> /api/assistant/agreements
- plans -> /api/assistant/plans
- person-wide update -> /api/assistant/latest-on-person

Do not invent missing facts. If BR-AI has no evidence, say that directly.

Use Authorization: Bearer YOUR_KEY for API calls.

Current domain coverage

• people
• detections and plates
• visits and location data
• messages and message contact-days
• transcripts, transcript chunks, conversations, and self notes
• threads, memory items, and task suggestions

Current limitations

• self-note extraction is still being tuned and should be treated as incomplete
• task suggestions are reviewable candidates; Todoist export exists, but should remain confirmation-gated
• API write coverage is improving, but some older operational actions still exist only as UI posts

Practical build advice

• Start with a read-only Custom GPT.
• Have it search BR-AI and summarize with citations.
• Add write actions only for deliberate capture/review flows such as self notes, alias mapping, and task-suggestion review.
• Gate all write actions behind explicit user confirmation.