Quickstart

Send your first message in 5 minutes

Get from zero to sending messages, reading channels, and reacting — in 5 minutes.

1. Get an API key

Open your server in start.chat, go to Server Settings → API Keys, and create a key. You’ll get a key like sk_live_abc123... — save it, you won’t see it again.

API keys are scoped to one server and inherit the permissions of the role you assign. For this guide, use a role with canEditData (send messages, react, create threads).

Terminal

export START_API_KEY="sk_live_your_key_here"
export BASE="https://start.chat/api/v1"

2. Verify your key

Terminal

curl "$BASE/auth/whoami" \
  -H "Authorization: Bearer $START_API_KEY"

{
  "ok": true,
  "data": {
    "id": "usr_abc123",
    "name": "My Bot",
    "serverId": "srv_abc123"
  }
}

If you get UNAUTHORIZED, double-check the key. Keys use the format sk_live_*.

3. List channels

Terminal

curl "$BASE/servers/$SERVER_ID/channels" \
  -H "Authorization: Bearer $START_API_KEY"

{
  "ok": true,
  "data": [
    { "id": "ch_general", "name": "general", "type": "chat" },
    { "id": "ch_random", "name": "random", "type": "chat" }
  ]
}

Pick a channelId for the next step.

4. Send a message

Terminal

curl -X POST "$BASE/messages" \
  -H "Authorization: Bearer $START_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "ch_general",
    "content": "Hello from the API!"
  }'

{
  "ok": true,
  "data": {
    "id": "msg_abc123",
    "channelId": "ch_general",
    "content": "Hello from the API!",
    "type": "person",
    "createdAt": 1709251200000
  }
}

The serverId is auto-injected from your API key — you don’t need to pass it.

5. Read it back

Terminal

curl "$BASE/channels/ch_general/messages?limit=1" \
  -H "Authorization: Bearer $START_API_KEY"

{
  "ok": true,
  "data": [
    {
      "id": "msg_abc123",
      "content": "Hello from the API!",
      "creatorId": "usr_abc123",
      "createdAt": 1709251200000
    }
  ]
}

6. Add a reaction

Terminal

curl -X POST "$BASE/reactions" \
  -H "Authorization: Bearer $START_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messageId": "msg_abc123",
    "content": "👋"
  }'

Using the SDK

The same flow with the TypeScript SDK:

import { setup, query, mutate } from 'start/sdk'

await setup({ apiKey: process.env.START_API_KEY })

// list channels
const channels = await query.channelsByServer({ serverId: 'srv_abc123' })

// send a message
const msg = await mutate.message.send({
  channelId: channels[0].id,
  content: 'Hello from the SDK!',
})

// read messages
const messages = await query.channelMessages({
  channelId: channels[0].id,
  limit: 10,
})

// react
await mutate.reaction.insert({
  messageId: msg.id,
  content: '👋',
})

Overview

Authentication