Developer Documentation

Architecture Overview

swarmrise uses Convex as its backend runtime. The frontend communicates via Convex's real-time WebSocket protocol for queries and mutations. HTTP endpoints handle inbound webhooks and file serving. The public REST API (v1) provides external access to organization resources and outbound webhook management.

                        Frontend (React 19 + Vite)
                                  |
                 Convex real-time protocol (WebSocket)
                                  |
                 +----------------+----------------+
                 |        Convex Backend           |
                 |                                 |
                 |  queries / mutations / actions   |
                 |  (domain functions in convex/*/) |
                 +-------+--------+--------+-------+
                         |        |        |
                  POST /webhooks/clerk  |  Public REST API v1
                         |        |
                  Clerk (Svix webhook)  GET /files/{storageId}

Current API Surface

The HTTP layer currently exposes two endpoints plus the full public REST API v1.

{
  "data": { ... },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2026-02-24T10:30:00Z"
  }
}

{
  "data": [ ... ],
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2026-02-24T10:30:00Z",
    "hasMore": true,
    "nextCursor": "eyJpZCI6..."
  }
}

Authentication

swarmrise supports multiple authentication methods depending on the integration type.

curl -H "Authorization: Bearer sk_live_xxxx" \
     https://your-convex-url.convex.site/api/v1/orgas

Public API Roadmap

The public REST API is organized into five tiers by integration value and implementation effort.

Error Handling

All errors follow a consistent JSON shape.

{
  "error": {
    "code": "FORBIDDEN",
    "message": "User is not a member of this organization",
    "details": {},
    "requestId": "req_abc123"
  }
}

Error Code Mapping

Rate Limiting

Rate limiting uses a token-bucket algorithm scoped per API key.

Rate Limit Tiers

Rate Limit Headers

When exceeded, the API returns 429 Too Many Requests with a Retry-After header.

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Reset: 1709290800
Retry-After: 42

Versioning

Date-Based Header Versioning

Version is specified via the X-Api-Version header (e.g., 2026-02). If omitted, the latest stable version is used.

curl -H "X-Api-Version: 2026-02" \
     -H "Authorization: Bearer sk_live_xxxx" \
     https://your-convex-url.convex.site/api/v1/orgas

Security

Security is built into every layer of the swarmrise API.

Outbound Webhook Guide

Subscribe to swarmrise events and receive real-time notifications via HTTPS webhooks.

Supported Events

{
  "url": "https://example.com/webhooks/swarmrise",
  "events": [
    "decision.created",
    "member.joined",
    "kanban.card.moved"
  ]
}

{
  "event": "decision.created",
  "timestamp": "2026-02-26T14:30:00.000Z",
  "data": {
    "decisionId": "j572x...",
    "orgaId": "k473y...",
    "targetType": "policies",
    "targetId": "p291z...",
    "authorEmail": "alice@example.com",
    "diff": {
      "type": "Policy",
      "before": null,
      "after": { "title": "..." }
    }
  }
}

{
  "event": "kanban.card.moved",
  "timestamp": "2026-02-26T14:30:00.000Z",
  "data": {
    "cardId": "c123...",
    "boardId": "b456...",
    "orgaId": "k473y...",
    "fromColumnId": "col_todo...",
    "toColumnId": "col_done..."
  }
}

const crypto = require("crypto");

function verifySignature(payload, header, secret) {
  const [tPart, v1Part] = header.split(",");
  const timestamp = tPart.replace("t=", "");
  const signature = v1Part.replace("v1=", "");

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${payload}`)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature, "hex"),
    Buffer.from(expected, "hex")
  );
}

// Usage in Express:
app.post("/webhooks/swarmrise", (req, res) => {
  const signature = req.headers["x-swarmrise-signature"];
  const isValid = verifySignature(
    JSON.stringify(req.body),
    signature,
    process.env.SWARMRISE_WEBHOOK_SECRET
  );

  if (!isValid) return res.status(401).send("Invalid signature");

  // Process event...
  console.log(req.body.event, req.body.data);
  res.status(200).send("OK");
});