Get Started

API Reference

REST API documentation for DiscoLink. All endpoints return JSON.

Base URL

The API base URL depends on your deployment:

# Self-hosted
http://localhost:3000

# Your custom domain
https://api.yourdomain.com

Endpoints

Servers

GET /servers/:id Get server details
GET /servers/:id/channels List server channels
GET /servers/:id/threads List server threads (paginated)
GET /servers/:id/stats Get server statistics

Channels

GET /channels/:id Get channel details
GET /channels/:id/threads List channel threads
GET /channels/:id/messages List channel messages (non-thread)

Threads

GET /threads/:id Get thread details
GET /threads/:id/messages List thread messages

Search

GET /search Full-text search across all content

Webhooks

POST /servers/:id/webhooks Register a webhook
GET /servers/:id/webhooks List registered webhooks
PUT /webhooks/:id Update webhook configuration
DELETE /webhooks/:id Delete a webhook
POST /webhooks/:id/test Send test webhook payload

Feeds

GET /feeds/:serverId/rss RSS 2.0 feed
GET /feeds/:serverId/atom Atom feed
GET /feeds/:serverId/json JSON Feed
GET /feeds/:channelId/rss Channel-specific RSS feed

Pagination

List endpoints support cursor-based pagination:

GET /servers/:id/threads?limit=20&cursor=abc123

Response:
{
  "data": [...],
  "pagination": {
    "cursor": "xyz789",
    "hasMore": true
  }
}

Filtering

Thread list endpoints support filtering:

# Filter by status
GET /servers/:id/threads?status=resolved

# Filter by tags
GET /servers/:id/threads?tags=faq,support

# Filter by date
GET /servers/:id/threads?after=2024-01-01&before=2024-12-31

# Sort order
GET /servers/:id/threads?sort=created&order=desc

Search

Full-text search across all synced content:

GET /search?q=authentication&limit=10

Response:
{
  "data": [
    {
      "id": "123",
      "type": "thread",
      "title": "How to implement authentication",
      "snippet": "...discussing authentication methods...",
      "score": 0.95
    }
  ],
  "total": 42
}

Webhooks

Register webhooks to receive real-time notifications when content changes.

Webhook Events

thread.createdthread.updatedthread.deletedthread.resolvedmessage.createdmessage.updatedmessage.deletedreaction.addedreaction.removedsync.completed

Payload Format

{
  "event": "thread.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "serverId": "123456789",
  "data": {
    "id": "987654321",
    "title": "New thread title",
    "channelId": "111222333",
    "authorId": "444555666"
  }
}

Signature Verification

All webhook payloads include an HMAC-SHA256 signature in the X-DiscoLink-Signature header:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  return signature === expected;
}

Rate Limits

Rate limits depend on your deployment configuration. Default limits:

  • Read endpoints: 100 requests/minute
  • Search: 30 requests/minute
  • Webhooks: 10 requests/minute

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000

Error Responses

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Thread not found"
  }
}

Common error codes:
- BAD_REQUEST (400)
- UNAUTHORIZED (401)
- NOT_FOUND (404)
- RATE_LIMITED (429)
- INTERNAL_ERROR (500)