Getting Started

Create your first API token, make your first REST request, and understand Disqua's authentication flow — all in under 10 minutes.

Prerequisites

Before you start, you need:

  • A Disqua account — sign up free
  • A workspace (created during onboarding)
  • curl or any HTTP client (Postman, Insomnia, etc.)

All API calls require HTTPS. HTTP requests will be redirected with a 301 to the HTTPS equivalent.

Step 1 — Create an API token

Disqua uses Bearer token authentication. Tokens are scoped to a workspace and carry the permissions of the user who created them.

  1. Log in to console.disqua.com
  2. Go to Workspace Settings → Integrations
  3. Click New API Token, give it a name (e.g. "My first app"), choose scopes
  4. Copy the token — it will only be shown once

Treat your token like a password. Never commit it to version control. Use environment variables or a secrets manager.

Token scopes

Scope Access
messages:readRead messages in channels the user is a member of
messages:writeSend and edit messages
channels:readList and read channel metadata
channels:writeCreate, update, archive channels
users:readRead user profiles within the workspace
files:readDownload files
files:writeUpload files
webhooks:writeRegister and manage webhook endpoints

Step 2 — Make your first request

Verify your token by fetching your own user profile:

Request GET /v1/users/me 
curl https://api.disqua.com/v1/users/me \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

A successful response looks like:

Response 200 OK 
{
  "ok": true,
  "data": {
    "id": "01HQ7Z2B3X4C5D6E7F8G9H0J1K",
    "username": "janedoe",
    "displayName": "Jane Doe",
    "email": "jane@example.com",
    "avatarUrl": "https://cdn.disqua.com/avatars/janedoe.jpg",
    "status": "online",
    "createdAt": "2026-01-15T10:30:00.000Z"
  }
}

List channels in a workspace

You need your workspaceId. Find it in Workspace Settings → General, or from the list endpoint:

Request GET /v1/workspaces/:workspaceId/channels 
curl "https://api.disqua.com/v1/workspaces/WORKSPACE_ID/channels?limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"
Response 200 OK 
{
  "ok": true,
  "data": [
    {
      "id": "01HQ7Z...",
      "name": "general",
      "slug": "general",
      "type": "public",
      "memberCount": 12,
      "lastMessageAt": "2026-03-18T09:44:11.000Z"
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "01HQ8A..."
  }
}

Send a message

Request POST /v1/channels/:channelId/messages 
curl -X POST "https://api.disqua.com/v1/channels/CHANNEL_ID/messages" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello from the Disqua API!"
  }'
Response 201 Created 
{
  "ok": true,
  "data": {
    "id": "01HQ8B...",
    "channelId": "CHANNEL_ID",
    "authorId": "01HQ7Z...",
    "content": "Hello from the Disqua API!",
    "contentHtml": "<p>Hello from the Disqua API!</p>",
    "createdAt": "2026-03-18T09:45:00.000Z"
  }
}

Authentication flow

Disqua's API supports two authentication strategies:

API Token (recommended for bots & scripts)

Long-lived token scoped to a workspace. Created in Workspace Settings. Attach as Authorization: Bearer <token>.

OAuth 2.0 (recommended for third-party apps)

Standard Authorization Code flow with PKCE. Short-lived access tokens (15 min) + refresh tokens (7 days). Install flow for apps distributed to other workspaces.

OAuth 2.0 Authorization Code flow

Step 1 — Redirect user to authorize
GET https://api.disqua.com/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=messages:read+channels:read
  &state=random_csrf_string
  &code_challenge=BASE64URL(SHA256(code_verifier))
  &code_challenge_method=S256
Step 2 — Exchange code for tokens
POST https://api.disqua.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE_FROM_REDIRECT
&redirect_uri=https://yourapp.com/callback
&client_id=YOUR_CLIENT_ID
&code_verifier=YOUR_CODE_VERIFIER
Response 200 OK 
{
  "access_token": "dqt_...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "dqr_...",
  "scope": "messages:read channels:read"
}

Error codes

All errors follow the same envelope format:

{
  "ok": false,
  "error": {
    "code": "E_AUTHZ_NOT_MEMBER",
    "message": "You are not a member of this channel.",
    "requestId": "req_01HQ8C..."
  }
}
HTTP Error code Description
400E_VALIDATIONRequest body/params failed schema validation
401E_AUTHN_INVALID_TOKENMissing or invalid Bearer token
401E_AUTHN_TOKEN_EXPIREDAccess token has expired — refresh it
403E_AUTHZ_NOT_MEMBERYou are not a member of this workspace/channel
403E_AUTHZ_INSUFFICIENT_SCOPEToken lacks required scope for this operation
403E_PLAN_LIMITAction blocked by your current plan limits
404E_NOT_FOUNDResource does not exist or is not accessible
409E_CONFLICTUnique constraint violation (e.g. slug already taken)
410E_CHANNEL_ARCHIVEDChannel is archived — messages cannot be sent
429E_RATE_LIMITToo many requests — check Retry-After header
500E_INTERNALUnexpected server error — contact support with requestId

Next steps

API Reference

Full endpoint documentation with all parameters and response shapes.

Webhooks

React to events in real time without polling.

Bot SDK

Build rich bots and slash commands with our Node.js SDK.