Integration API

Post messages into Snook topics from external services (CI/CD, monitoring, GitHub webhooks, custom bots) using API keys.

Bot messages appear in the message flow with a BOT badge and support text formatting.

Finding Your Community and Topic IDs

The integration API requires a community ID (for key management) and a topic ID (for posting messages). Both are visible in the Snook URL when you open a topic in the browser:

https://your-app/w/{communityId}/c/{topicId}

For example, in https://snook.app/w/mJTLP72z7kM86sDR2EdG/c/AYittVTgjtlBxhjwBxst:

• Community ID: mJTLP72z7kM86sDR2EdG
• Topic ID: AYittVTgjtlBxhjwBxst

Copy these from the URL bar and provide them to your integration when configuring it.

Quick Start

1. Create an API key (requires community admin role):

curl -X POST https://your-api/api/v1/communities/{communityId}/api-keys \
  -H "Authorization: Bearer {firebase-token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Deploy Bot"}'

Response includes the raw API key (shown once, save it):

{
  "id": "abc123",
  "name": "Deploy Bot",
  "key": "snk_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "keyPrefix": "snk_a1b2",
  "createdAt": "..."
}

2. Post a message:

curl -X POST https://your-api/api/v1/integrations/topics/{topicId}/messages \
  -H "Authorization: Bearer snk_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" \
  -H "Content-Type: application/json" \
  -d '{"text": "Deploy succeeded for commit abc123"}'

Authentication

The integration API uses API keys, separate from Firebase user tokens.

• Format: snk_ prefix + 32 hex characters (e.g., snk_0786b94f3b37bc50d017e0827a4d4d4f)
• Header: Authorization: Bearer snk_...
• Scope: each key is tied to one community and can post to any topic within it
• The raw key is returned only at creation and cannot be retrieved later

API Key Management

These endpoints require Firebase user authentication and community admin/owner role.

Create a key

POST /api/v1/communities/{communityId}/api-keys

Response (201):

{
  "id": "S2XSQf01ktHBKGJu5pT7",
  "name": "GitHub Bot",
  "key": "snk_0786b94f3b37bc50d017e0827a4d4d4f",
  "keyPrefix": "snk_0786",
  "createdAt": { "_seconds": 1775763085, "_nanoseconds": 950000000 }
}

List keys

GET /api/v1/communities/{communityId}/api-keys

Returns all keys for the community. Raw keys and hashes are never included.

Response (200):

{
  "keys": [
    {
      "id": "S2XSQf01ktHBKGJu5pT7",
      "name": "GitHub Bot",
      "keyPrefix": "snk_0786",
      "createdAt": "...",
      "lastUsedAt": "...",
      "revokedAt": null
    }
  ]
}

Revoke a key

DELETE /api/v1/communities/{communityId}/api-keys/{keyId}

Soft-deletes the key. Any subsequent requests using this key will return 401.

Response: 204 No Content

Post a Bot Message

POST /api/v1/integrations/topics/{topicId}/messages

Authenticated with an API key (not a Firebase token).

Request body

Markdown formatting

When format is "markdown", standard Markdown is converted to Snook's internal format before storage:

When format is "plain" (default), the text is stored as-is. You can also use Snook's native formatting directly: *bold*, _italic_, ~strikethrough~.

Response (201)

{
  "id": "jryx6wpnveCid40cuIlY",
  "topicId": "AYittVTgjtlBxhjwBxst",
  "content": "Deploy *succeeded* for _commit abc123_",
  "createdAt": { "_seconds": 1775763099, "_nanoseconds": 329000000 }
}

Error responses

Rate Limits

• Integration endpoint: 60 requests per minute per API key
• Global: 100 requests per minute per IP (applies to all endpoints)

How Bot Messages Appear

• Display name comes from the API key's name field
• A BOT badge appears next to the sender name
• Bot messages have no edit, delete, or reaction controls
• Bot messages update the topic's lastMessageAt (they appear in "recent activity")
• Consecutive messages from the same bot are grouped (no repeated header)