Skip to content

Use the API ​

The API lets a script or a program do what you can do in Connectdary, such as read channels, post a message into a topic or search, with a personal token that acts as you.

Personal tokens and the API need the Team plan. A token never sees more than you can. On the Free plan the API reads the last 90 days.

Make a personal token ​

  1. Open Settings › Developer. (Guests don't see it.)
  2. Under Personal tokens, choose New token.
  3. Give it a Name you will recognise, such as "My scripts".
  4. Under What it can do, tick only what the job needs. The examples below name the part each one needs.
  5. Under Where, choose Everything I can see, or Only some conversations to keep it small.
  6. Choose Expires after, then Create token. Copy the token now: it starts with cnct_ and is shown once.

Anything the token posts shows as you. You can revoke it at any time in the same place, and no one else, including admins, can see it.

Leave For an AI agent off for scripts. Agent tokens work only over MCP, see AI agents.

TIP

Keep the token in an environment variable or a secret store, never in code. The examples use $CONNECT_TOKEN.

Who am I? ​

sh
export CONNECT_TOKEN=cnct_...
curl -H "Authorization: Bearer $CONNECT_TOKEN" \
  https://connect.example.com/api/v1/me
json
{
  "userId": "01M6476A984WZH2TRSBSNAA936",
  "workspaceId": "01M6476A9NX93W2DV1HGCBAA5R",
  "kind": "user",
  "appId": null,
  "scopes": ["messages:read", "messages:write", "conversations:read"],
  "conversationIds": null
}

This is the quickest check that a token works and what it may do. conversationIds is null for "everything I can see".

List channels ​

Needs conversations:read.

sh
curl -H "Authorization: Bearer $CONNECT_TOKEN" \
  "https://connect.example.com/api/v1/conversations?limit=50"
json
[
  {
    "id": "01M6476A9QYNM2R290GNH40HR3",
    "kind": "channel",
    "name": "general",
    "archived": false,
    "lastMessageAt": 1793290639350
  }
]

Then list a channel's topics with GET /conversations/{id}/topics. Each topic has an id, a title, a status of open or resolved, and the ref an integration gave it.

Post a message into a topic ​

Needs messages:write. Use the topic's id:

sh
curl -X POST https://connect.example.com/api/v1/messages \
  -H "Authorization: Bearer $CONNECT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"conversation":"01M6476A9QYNM2R290GNH40HR3","topic":"01M6476A9QASWFM1D7YXM0MCM0","text":"Hello from the API"}'

Or let your script name the topic itself. Give a stable topic_ref and a title. The first post makes the topic, and every later post with the same topic_ref lands in it:

sh
curl -X POST https://connect.example.com/api/v1/messages \
  -H "Authorization: Bearer $CONNECT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"conversation":"01M6476A9QYNM2R290GNH40HR3","topic_ref":"deploys","title":"Deploys","text":"Deploy finished"}'

Give either topic or topic_ref, not both. The answer is the new message. text may use Markdown and be up to 8,000 characters. To read a topic back, use GET /topics/{id}/messages.

Add "parent": "<message id>" to reply in that message's thread. The parent must be a top-level message in the same topic, or the post is refused with invalid_thread. To show that you are typing while you work on an answer, call POST /topics/{id}/typing (needs messages:write). People see it for a few seconds, as they do for a person typing. A topic's ref can be set after the fact: PATCH /topics/{id} with {"ref": "pr-17"}, or {"ref": null} to clear it, alongside or instead of a new title. A conversation keeps each ref on one topic: another topic's ref is answered with 409 ref_taken. To mark a message as a decision, as a person does, call PUT /messages/{id}/decision; DELETE takes the mark off. This needs decisions:write, which messages:write doesn't include, and a bot also needs it in its grant for the conversation.

To ask a question with options, send a poll instead of text: {"conversation": "…", "topic": "…", "poll": {"question": "Friday or Monday?", "options": ["Friday", "Monday"], "multiple": false, "anonymous": false, "closesAt": 1767225600000}}. multiple, anonymous and closesAt (milliseconds, at most a year ahead) are optional. A poll is a message of its own, so it can't carry text, components or a parent. It needs a channel or a group DM. Only the one who posted a poll can close it early, with POST /messages/{id}/poll/close, which answers with the poll. An app that posted a poll hears poll.voted and poll.closed for it.

Needs search:read.

sh
curl -H "Authorization: Bearer $CONNECT_TOKEN" \
  "https://connect.example.com/api/v1/search?q=deploy&limit=10"
json
{
  "results": [
    {
      "messageId": "01M64775YDVA5GACK8TGVVYWTS",
      "conversationName": "general",
      "topicTitle": "Deploys",
      "text": "Deploy finished",
      "match": "text"
    }
  ],
  "semantic": false,
  "nextCursor": null
}

Narrow it with in (a conversation id), from (a member's id), after and before (milliseconds since 1970). The query can be empty when you give a filter: the newest matches come first. A new message can take a moment to become searchable.

Files ​

Read only. You can't upload a file through the API yet. With files:read, GET /files/{id}/details gives a file's details and its text (up to 20,000 characters), and GET /files/{id} gives its bytes:

sh
curl -H "Authorization: Bearer $CONNECT_TOKEN" \
  https://connect.example.com/api/v1/files/FILE_ID -o report.pdf

Pages ​

Lists that can grow take limit and a cursor:

  • Conversations. limit (1 to 200) and after. While a page comes back full, ask again with after set to the last id.
  • Topic messages. limit (up to 100, default 50) returns the newest; the answer has hasMore. Pass the oldest id as before for older ones. Replies in a thread work the same way.
  • Search. limit (up to 50) and cursor. Pass back nextCursor while it isn't null.

Rate limits ​

A token gets 120 requests a minute by default. Every answer says where you stand:

RateLimit-Policy: 120;w=60
RateLimit-Limit: 120
RateLimit-Remaining: 118
RateLimit-Reset: 1

Past the limit you get a 429 {"error":"rate_limited"} with a Retry-After header in seconds. Wait that long, then try again.

Editing a message (PATCH /messages/{id}), as a bot does while it streams an answer, has a bucket of its own, 600 a minute by default, and takes nothing from the 120. Its answers carry the same headers for that bucket.

Errors ​

Every error is JSON with a stable error word. Branch on that, not on the message.

StatuserrorMeaning
400invalid_inputThe body or query is wrong. issues says which field.
401invalid_tokenThe token is wrong, expired or revoked. No token gives unauthorized.
403missing_scopeThe token wasn't given that part. Make a new token.
403agent_tokens_mcp_onlyAn agent token can't call these routes.
404not_foundIt doesn't exist, or the token can't see it.
429rate_limitedSlow down, see above.

The description, SDK and CLI ​

Every server publishes its own OpenAPI 3.1 description. You don't need a token to read it:

sh
curl https://connect.example.com/api/v1/openapi.json

Import it into Postman, Insomnia or a code generator. Routes are removed only after 12 months of warning, in Deprecation and Sunset headers.

Connectdary's own TypeScript client is generated from the same description. It lives in the Connectdary repository under packages/sdk, with Python and Go versions beside it. It isn't published to a package registry.

ts
import { ConnectClient } from "@connect/sdk/typescript";

const connect = new ConnectClient({
  baseUrl: "https://connect.example.com",
  token: process.env.CONNECT_TOKEN,
});
const me = await connect.getMe();
const channels = await connect.listConversations({ limit: 10 });
const { results } = await connect.search({ q: "deploy" });

The connect command line tool (packages/cli) is for people who build apps. It can check a token and forward events to your machine:

sh
connect auth login --url https://connect.example.com --token -   # token on stdin
connect auth status

For apps with their own name and events, see Build an app. To post without any code, use an incoming webhook.