Build on SphereOne. API, webhooks and slash commands.

curl https://app.sphereone.ai/v1/api/auth.test \
  -H "Authorization: Bearer $SPHEREONE_API_KEY"

Keep keys out of URLs, browsers and source control. A key in a query string is refused. Revoke a key you no longer trust from the same screen that made it.

Post a message

Text is Markdown. Add parentMessageId to reply in a thread and fileIds to attach files. Send an Idempotency-Key so a retry returns the message already posted instead of posting it twice. Messages arrive live, notify people you mention, and show up in search like anything typed in the app.

curl https://app.sphereone.ai/v1/api/messages \
  -H "Authorization: Bearer $SPHEREONE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: deploy-2026-10-13-001" \
  -d '{ "channelId": "CHANNEL_ID", "text": "Release **v2.4** is live" }'

{
  "ok": true,
  "data": {
    "id": "cm…",
    "channelId": "CHANNEL_ID",
    "author": { "id": "cm…", "displayName": "Deploy Bot", "isApp": true },
    "text": "Release **v2.4** is live",
    "createdAt": "2026-10-13T09:30:00.000Z",
    "idempotencyKey": "deploy-2026-10-13-001"
  }
}

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Over the limit you get HTTP 429 with the code rate_limited and a Retry-After header: wait that many seconds, then try again.

curl "https://app.sphereone.ai/v1/api/channels/CHANNEL_ID/messages?limit=100&cursor=NEXT_CURSOR" \
  -H "Authorization: Bearer $SPHEREONE_API_KEY"

{
  "ok": false,
  "error": {
    "code": "missing_scope",
    "message": "This call needs the \"chat:write\" permission, and this key doesn't have it.",
    "neededScope": "chat:write",
    "requestId": "8f3c…"
  }
}

# 1. Ask where to put the bytes
curl https://app.sphereone.ai/v1/api/files/uploads \
  -H "Authorization: Bearer $SPHEREONE_API_KEY" -H "Content-Type: application/json" \
  -d '{ "filename": "report.pdf", "contentType": "application/pdf", "sizeBytes": 48213 }'

# 2. PUT the file to the uploadUrl you got back
curl -X PUT "UPLOAD_URL" -H "Content-Type: application/pdf" --data-binary @report.pdf

# 3. Finish, then attach the file id to a message
curl https://app.sphereone.ai/v1/api/files \
  -H "Authorization: Bearer $SPHEREONE_API_KEY" -H "Content-Type: application/json" \
  -d '{ "uploadToken": "UPLOAD_TOKEN", "filename": "report.pdf", "contentType": "application/pdf", "sizeBytes": 48213 }'

curl -X POST https://app.sphereone.ai/v1/hooks/YOUR_WEBHOOK_TOKEN \
  -H "Content-Type: application/json" \
  -d '{ "text": "Build **#512** passed" }'

Check the signature

Every outgoing webhook and slash command request carries SphereOne-Signature: t=<unix seconds>,v1=<hmac>. The HMAC is SHA-256, keyed with the signing secret shown when you made the webhook, over t + "." + the raw body. Refuse anything more than 5 minutes old, and use SphereOne-Delivery to ignore a delivery you have already handled.

import { createHmac, timingSafeEqual } from 'node:crypto';

// header: the SphereOne-Signature header, e.g. "t=1760347800,v1=5f2c…"
// rawBody: the request body exactly as received, before any JSON parsing
export function verify(header, rawBody, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.trim().split('=')));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest();
  const given = Buffer.from(parts.v1 ?? '', 'hex');
  return given.length === expected.length && timingSafeEqual(given, expected);
}