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.

CLI and MCP server Alongside raw REST there is a threa command-line tool and an MCP server (threa mcp serve) for agent hosts, both installed from the open-source repo. See CLI & MCP server.

Base URL

The API lives at https://app.threa.io under the stable /api/v1 prefix, 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 }'

Working with an AI agent

These docs ship in machine-readable form. Every page here has a markdown mirror at the same URL plus .md, /llms.txt indexes them, and /llms-full.txt is the whole set in one fetch. The OpenAPI spec is the canonical contract. To point an agent at the API, paste:

prompt for your agent 
Integrate with the Threa API. Read https://threa.io/llms-full.txt for the docs
and https://threa.io/openapi.json for the exact contract. The base URL is
, my workspace ID is , and my API key is in the
THREA_API_KEY environment variable (send it as "Authorization: Bearer ...").
Verify the key with GET /api/v1/workspaces//me before anything else.

Don't paste the key itself into a prompt. Put it in an environment variable and let the agent read it from there.

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.