Capture thoughts from anywhere

Capturing doesn’t have to start with a human voice. Anything that can run a script can drop a thought in your inbox - spoken, transcribed, summarised, and filed exactly like something you said yourself.

A good example: a nightly test suite that pages you by capturing a thought when it fails. Instead of a bare CI notification, your product tells you about your own systems, in its own voice, with the context already structured.

GitHub Actions: the easy path

For CI, the fastest route is capture-thought-action. Drop it into a workflow and it handles turning your text into audio, the upload, and the transcription trigger for you.

- name: Tell ThoughtBridge the suite failed
  if: failure()
  uses: ThoughtBridge/capture-thought-action@v1
  with:
    api-key: ${{ secrets.THOUGHTBRIDGE_API_KEY }}
    text: >-
      The nightly suite failed on ${{ github.repository }}.
      Check the workflow run for details.

Setup

1. In the app, go to Settings > API keys and create a read_write key (see API keys for the full walkthrough).
2. Scope it to one or more projects so its captures land there - a dedicated Ops project keeps CI alerts and other automated captures separate from your own ideas. Leave it unscoped and captures go through normal routing, which can land them in your review inbox instead.
3. Store the key as a secret in whatever calls it - a GitHub Actions secret, an environment variable in a cron job. The key is the access: treat it like any other credential.

Any script: the general path

The GitHub Action is really a thin wrapper around three HTTP calls. Anything that can make an HTTP request and produce audio can do the same thing: a cron job, a Slack bot, a build script, a home automation hook.

The flow:

1. Turn your text into a short audio file - espeak-ng on Linux, say on macOS, or any other text-to-speech tool.
2. POST /captures/upload-url with fileName, contentType, sourceDevice: api, and enforceSizeLimit: true to get a signed upload URL. The response also carries maxBytes (the largest file the URL will accept) and uploadHeaders.
3. PUT the audio bytes to that URL, sending every uploadHeaders entry as a header verbatim - the signature covers them, so a PUT without them is rejected with 400.
4. POST /captures/{captureId}/complete-upload with durationSeconds to start transcription.

BASE="https://thoughtbridge-api-238666896847.australia-southeast1.run.app/v1"
AUTH="Authorization: Bearer tb_..."
TEXT="The nightly suite failed. Check the workflow run for details."

# 1. text to speech (macOS: say -o out.wav --data-format=LEI16@16000 "$TEXT")
espeak-ng "$TEXT" -w out.wav

# 2. ask for a signed upload URL
RESPONSE=$(curl -s -X POST "$BASE/captures/upload-url" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"fileName":"out.wav","contentType":"audio/wav","sourceDevice":"api","enforceSizeLimit":true}')

CAPTURE_ID=$(echo "$RESPONSE" | jq -r '.captureId')
UPLOAD_URL=$(echo "$RESPONSE" | jq -r '.uploadUrl')
# every uploadHeaders entry goes on the PUT verbatim (written as a curl config)
echo "$RESPONSE" | jq -r '.uploadHeaders // {} | to_entries[] | "header = \"\(.key): \(.value)\""' > upload-headers.conf

# 3. upload the audio (must be at most .maxBytes from the response)
curl -s -X PUT "$UPLOAD_URL" -H "Content-Type: audio/wav" -K upload-headers.conf --data-binary @out.wav

# 4. tell ThoughtBridge the upload is done
DURATION=$(soxi -D out.wav)
curl -s -X POST "$BASE/captures/$CAPTURE_ID/complete-upload" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d "{\"durationSeconds\":$DURATION}"

Allowed audio types are m4a, mp4, mpeg, wav, and webm. Audio uploads are capped at 25 MiB (maxBytes: 26214400) and video uploads via /captures/{captureId}/video-upload-url at 256 MiB - check the file size against maxBytes before the PUT. Transcription usually takes a few seconds after the completed-upload call - the capture shows up in the app once it’s done.

Honest notes

• Every capture, however it arrives, counts toward your plan’s monthly capture limit.
• A key can be revoked at any time in Settings > API keys, with no effect on captures it already filed.