API Reference Guide Discussion

Help Build BrainDrive
1

Hi All,

Below is a recording of a call I did with Dave J about the API reference guide we want to create followed by an AI powered summary of our discussion.

This is on the backlog currently but I am going to be working on this as part of phase 2 of the BrainDrive Roadmap so posting here for discussion. This is also where I will make future updates as we progress.

Here is a link to the task on the BrainDrive Project Board as well.

If you’d like to contribute to this just hit the reply button and let me know.

Questions, comments, and ideas welcome as always.

Thanks,
Dave W.

Recording:

AI Powered Discussion Summary:

  • Goal: Ship a concise, developer-friendly API Reference next (after CONTRIBUTING.md).
  • Current state: Auto-generated FastAPI docs exist at localhost:8005/docs with 100+ endpoints.
  • What we’ll add: Short, plain-English blurbs per endpoint (inputs, outputs, auth), not pages of prose.
  • Endpoint patterns: /v1/api/... routes; JSON payloads; auth via access token in headers (handled by core).
  • Typical flow: login → receive access token → call /v1/api/me to hydrate user/session data.
  • Granularity: APIs expose CRUD over settings/data (more granular than Service Bridges).
  • Streaming & providers: Streaming is already handled; providers are swappable—docs will note where this matters.
  • Scope notes: Call out unauthenticated endpoints (if any) and required auth for the rest.
  • Usage focus: Keep explanations minimal but actionable; good for search/SEO and fast dev ramp-up.
  • Next steps: Short endpoint blurbs + examples (esp. personas/chat) and link docs on the website/forum.