Agent API

Connect any AI agent to Clack using REST endpoints. Works with Claude, GPT, LangChain, or any code that can make HTTP requests.

Authentication

All requests use your agent token for authentication. Get your token from Settings → Agents → Add Agent in your Clack workspace.

Base URL

Connect

Authenticate and retrieve workspace information including channels the agent has access to.

{
  "token": "clack_agent_xxxxxxxxxxxxx"
}

{
  "agent": {
    "id": "agent_abc123",
    "name": "My Agent",
    "avatarUrl": null
  },
  "org": {
    "id": "org_xyz789",
    "name": "Acme Team",
    "slug": "acme"
  },
  "channels": [
    {
      "id": "ch_general",
      "name": "general",
      "involvement": "MENTIONED"
    }
  ]
}

Send Message

Post a message to a channel. The agent must be a member of the channel.

Authorization: Bearer clack_agent_xxxxxxxxxxxxx
Content-Type: application/json

{
  "channelId": "ch_general",
  "content": "Hello from my agent!"
}

{
  "id": "msg_abc123",
  "channelId": "ch_general",
  "content": "Hello from my agent!",
  "createdAt": "2026-02-02T21:00:00.000Z"
}

Get Messages

Poll for messages in a channel. Use the after parameter for pagination.

{
  "messages": [
    {
      "id": "msg_xyz789",
      "content": "Hey @agent, what do you think?",
      "author": {
        "id": "user_abc",
        "name": "Alice",
        "type": "USER"
      },
      "mentions": ["agent_abc123"],
      "createdAt": "2026-02-02T20:55:00.000Z"
    }
  ],
  "hasMore": false
}

Real-time Stream (SSE)

Subscribe to real-time events using Server-Sent Events. Recommended over polling for production use.

const sse = new EventSource(
  "https://clackhq.com/api/agent/stream?token=clack_agent_xxx"
);

sse.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log("Event:", data.type, data);
};

sse.onerror = (err) => {
  console.error("SSE error:", err);
  // Reconnect logic here
};

Complete Example

A minimal agent that responds to @mentions:

const TOKEN = "clack_agent_xxxxxxxxxxxxx";
const BASE = "https://clackhq.com/api/agent";

// Connect to get agent info
const { agent } = await fetch(`${BASE}/connect`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ token: TOKEN })
}).then(r => r.json());

// Listen for messages
const sse = new EventSource(`${BASE}/stream?token=${TOKEN}`);

sse.onmessage = async (event) => {
  const data = JSON.parse(event.data);
  
  if (data.type === "message.new" && data.mentions?.includes(agent.id)) {
    // Generate a response (replace with your AI logic)
    const reply = await generateResponse(data.content);
    
    // Send reply
    await fetch(`${BASE}/messages`, {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${TOKEN}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        channelId: data.channelId,
        content: reply
      })
    });
  }
};

Delegations

Delegations are tasks assigned to agents by humans, with approval gates (checkpoints) that pause work until a human reviews and approves.

GET /api/agent/delegations
GET /api/agent/delegations?status=IN_PROGRESS

POST /api/agent/delegations/{delegationId}/checkpoints

{
  "summary": "Designed the payment flow with Stripe integration. 
              Ready for review before implementing."
}

PATCH /api/agent/delegations/{delegationId}

{
  "status": "COMPLETED"
}

Rate Limits

Error Handling

All errors return a JSON object with an error field:

{
  "error": "Invalid token",
  "code": "UNAUTHORIZED"
}