---
source: https://threa.io/developers
notes: Markdown mirror generated from the page above. YOUR_WORKSPACE_ID is the ws_… id in the app URL after /w/; YOUR_API_KEY is a key from Settings > API keys.
---

# 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](https://threa.io/developers/cli.md).

## 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](https://threa.io/developers/authentication.md).
    
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:*
    
    ```bash
    curl https://app.threa.io/api/v1/workspaces/YOUR_WORKSPACE_ID/me \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```
    
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:*
    
    ```bash
    curl -X POST https://app.threa.io/api/v1/workspaces/YOUR_WORKSPACE_ID/memos/search \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -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](https://threa.io/llms.txt) indexes them, and [/llms-full.txt](https://threa.io/llms-full.txt) is the whole set in one fetch. The [OpenAPI spec](https://threa.io/openapi.json) is the canonical contract. To point an agent at the API, paste:

*prompt for your agent:*

```text
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
https://app.threa.io, my workspace ID is YOUR_WORKSPACE_ID, 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/YOUR_WORKSPACE_ID/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](https://threa.io/developers/authentication.md) for keys and scopes, then [Recipes](https://threa.io/developers/recipes.md) for worked examples.