Threa Developers

Developers

Threa's public API.

A REST API over your workspace: messages, streams, members, attachments, and the memos Threa builds from your conversations. The memory Ariadne reads is the memory your own agent reads, through scoped keys you issue yourself.

Add your workspace ID and an API key in the Credentials panel (top right). Every sample on these pages then fills in your real values, and the runnable ones call the API and print the response. What you paste stays in your browser and is sent only on requests you run yourself.

No MCP server yet There's no Model Context Protocol server today, so an agent host like Claude Desktop can't auto-discover Threa through MCP. You connect over the REST API and the bot runtime instead (see Recipes). An MCP server is planned.

Base URL

The API lives at https://app.threa.io, versioned under /api/v1 and scoped to a workspace: /api/v1/workspaces/{workspaceId}/…. Your workspace ID is in the app URL, after /w/.

Quickstart

  1. Create an API key

    In the app, open Settings → API keys, create a user key, pick the scopes you need, and copy it once. Full walkthrough in Authentication.

  2. Add it to the Credentials panel

    Open the panel (top right) and enter your workspace ID and key. The status turns green once a call to /me succeeds.

  3. Confirm who you are

    GET /me needs no scope. It reports the identity behind the key. Run it:

    who am I 
    curl /api/v1/workspaces//me \
  -H "Authorization: Bearer "

  4. Search your own workspace

    With memos:read, search what Threa has remembered. It's the same retrieval Ariadne uses, with source links and timestamps.

    search memos 
    curl -X POST /api/v1/workspaces//memos/search \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{ "query": "auth", "limit": 5 }'

What you can build

  • Read and write messages in any stream you can access, with idempotent sends.
  • Search messages and memos semantically or exactly, scoped to streams, types, and dates.
  • Pull memos with their source messages, so an external agent works from the same knowledge as Ariadne.
  • Run your own agent as a bot: heartbeat a runtime, claim invocations when it's mentioned, post replies. The Pi remote extension works this way.
  • Upload and read attachments, including the text Threa extracts from them.

Next: Authentication for keys and scopes, then Recipes for worked examples.