API reference

Every endpoint below is relative to the base URL and authenticated with a bearer key - see using the API. Thoughts are called captures in the API.

List captures

GET /captures

Returns your captures, newest first. Query parameters, all optional:

Parameter	Meaning
projectId	Only captures in this project.
status	Filter by lifecycle status: uploaded, processing, completed, failed, or needs_review.
q	Free-text search over title, summary, and transcript (case-insensitive substring).
updatedSince	ISO 8601 timestamp - only captures updated strictly after this moment, newest change first. Built for “what changed since my last check” polling.
fields	Comma-separated capture fields to return, e.g. fields=title,status,summary. captureId is always included. Handy for keeping AI context small.
limit	Page size, 1 to 100. Default 20.
cursor	Opaque cursor from a previous response’s nextCursor.

The response is { "data": [...], "total": 42, "nextCursor": "..." }. Pass nextCursor back as cursor for the next page; it is null on the last page. Searches (q) and updatedSince queries return a single recency-ordered batch instead of cursor pages.

# everything that changed in the last hour, titles and statuses only
curl -H "Authorization: Bearer tb_..." \
  "$BASE/captures?updatedSince=2026-08-11T09:00:00Z&fields=title,status"

Get one capture

GET /captures/{captureId}

Returns the full capture record: transcript, title, summary, the analysis (extracted ideas, tasks and their done-states, open questions), work status, notes, context links, timestamps, and where it was filed.

Get a capture’s rendered files

GET /captures/{captureId}/files

Returns the capture rendered as destination files (the Markdown that would be, or was, written to the destination). Useful when a capture is still pending a client-side write.

Get a capture’s video

GET /captures/{captureId}/video-url

For captures that have a stored video, returns a short-lived signed URL you can download the video from. The URL expires; request a fresh one each time.

List projects

GET /projects

Returns your projects: id, name, summary, and destination configuration. Supports limit for paging.

Get one project

GET /projects/{projectId}

Set a thought’s work status

PUT /captures/{captureId}/state

Requires read_write scope. Sets the thought’s work-status override:

{ "status": "in_progress" }

status is one of new, in_progress, in_review, done, or null to clear the override and fall back to the task-derived status. The change syncs to the destination’s thoughts-state.json, exactly as if you had changed it in the app. Marking a thought done also ticks all its tasks.

Tick one task

PATCH /captures/{captureId}/tasks/{taskIndex}

Requires read_write scope. taskIndex is the 0-based index into the capture’s extracted tasks:

{ "done": true }

Persists the done-state, re-renders the capture’s Markdown, and writes the updated checkbox line back to the destination. Returns the updated capture.

Set all task states

PUT /captures/{captureId}/task-states

Requires read_write scope. Replaces every task done-state at once, index aligned with the extracted tasks:

{ "taskDone": [true, false, true] }

Unlike the per-task tick, this does not write back to the destination - it exists for reconciling from a destination file that was edited directly. For normal “mark this task done” work, use the per-task endpoint.

A worked example

An agent that reviews yesterday’s thinking and marks one item as underway:

BASE="https://thoughtbridge-api-238666896847.australia-southeast1.run.app/v1"
AUTH="Authorization: Bearer tb_..."

# what came in yesterday?
curl -H "$AUTH" "$BASE/captures?updatedSince=2026-08-10T00:00:00Z&fields=title,summary,status"

# read one in full
curl -H "$AUTH" "$BASE/captures/cap_abc123"

# start working on it
curl -X PUT -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"status":"in_progress"}' "$BASE/captures/cap_abc123/state"