API Reference

curl https://api.swake.io/v1/sdk/ping \
  -H "X-API-Key: ep_live_xxxxxxxxxxxxxxxxxxxxxxxx"

// Recommended: proxy through your own backend so the
// secret key never ships to the browser.
Swake.init({
  apiKey: 'proxy-placeholder',        // your backend holds the real key
  baseUrl: 'https://yourapp.com/api/swake',
  credentials: 'include',             // send your session cookie
});

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "title is required",
    "details": [{ "path": "title", "message": "Required" }]
  }
}

curl "https://api.swake.io/v1/sdk/submissions?externalUserId=user_123&limit=20&cursor=01J8..." \
  -H "X-API-Key: ep_live_..."

{
  "data": [ /* ...items... */ ],
  "pagination": { "hasMore": true, "cursor": "01J9..." }
}

curl -X POST https://api.swake.io/v1/sdk/identify \
  -H "X-API-Key: ep_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "user_123",
    "email": "jane@example.com",
    "name": "Jane Smith",
    "image": "https://cdn.example.com/avatars/jane.jpg",
    "customMetadata": { "plan": "pro" }
  }'

{
  "data": {
    "id": "01J8...",
    "externalId": "user_123",
    "email": "jane@example.com",
    "name": "Jane Smith",
    "customMetadata": { "plan": "pro" },
    "firstSeenAt": "2026-03-25T10:00:00Z",
    "lastSeenAt": "2026-03-25T10:00:00Z"
  }
}

curl -X POST https://api.swake.io/v1/sdk/submissions \
  -H "X-API-Key: ep_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "bug",
    "title": "Checkout button unresponsive on mobile",
    "description": "Tapping Pay does nothing on iOS 17.",
    "externalUserId": "user_123",
    "deviceInfo": { "os": "iOS 17.2", "appVersion": "2.4.1" },
    "customFields": { "01JCF...": "Pro" }
  }'

{
  "data": {
    "id": "01J8...",
    "type": "bug",
    "title": "Checkout button unresponsive on mobile",
    "status": "open",
    "priority": "medium",
    "createdAt": "2026-03-25T10:00:00Z"
  }
}

curl https://api.swake.io/v1/sdk/custom-fields \
  -H "X-API-Key: ep_live_..."

{
  "customFields": [
    { "id": "01JCF...", "name": "Account tier", "fieldType": "dropdown", "options": ["Free", "Pro"], "required": true, "position": 0 },
    { "id": "01JCG...", "name": "Requested by", "fieldType": "text", "options": null, "required": false, "position": 1 }
  ]
}

curl "https://api.swake.io/v1/sdk/submissions?externalUserId=user_123&status=open&limit=10" \
  -H "X-API-Key: ep_live_..."

{
  "data": [
    { "id": "01J8...", "type": "bug", "title": "...", "status": "open", "createdAt": "...", "isPublished": true }
  ],
  "pagination": { "hasMore": true, "cursor": "01J9..." }
}

curl https://api.swake.io/v1/sdk/submissions/01J8... \
  -H "X-API-Key: ep_live_..."

{
  "data": {
    "id": "01J8...",
    "type": "bug",
    "title": "Checkout button unresponsive on mobile",
    "status": "in_progress",
    "isPublished": true,
    "customFieldValues": { "01JCF...": "Pro" },
    "comments": [
      { "id": "01J8...", "authorType": "team", "body": "Thanks — looking into it.", "createdAt": "..." }
    ],
    "attachments": [
      { "id": "01J8...", "filename": "screenshot.png", "viewUrl": "https://...", "expiresAt": "..." }
    ]
  }
}

curl -X POST https://api.swake.io/v1/sdk/submissions/01J8.../comments \
  -H "X-API-Key: ep_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "externalUserId": "user_123", "body": "Still happening on 2.4.2." }'

{
  "data": {
    "id": "01J8...",
    "submissionId": "01J8...",
    "authorType": "user",
    "authorId": "01J8...",
    "body": "Still happening on 2.4.2.",
    "createdAt": "2026-03-25T10:05:00Z"
  }
}

# 1. Ask for a presigned upload URL
curl -X POST https://api.swake.io/v1/uploads/presign \
  -H "X-API-Key: ep_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "submissionId": "01J8...",
    "filename": "screenshot.png",
    "contentType": "image/png",
    "sizeBytes": 82345
  }'

{
  "uploadUrl": "https://<r2-signed-url>",
  "r2Key": "attachments/01J8...",
  "attachmentId": "01J8...",
  "expiresAt": "2026-03-25T10:15:00Z"
}

# 2. PUT the raw bytes to uploadUrl (Content-Type must match), then confirm
curl -X POST https://api.swake.io/v1/uploads/confirm \
  -H "X-API-Key: ep_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "attachmentId": "01J8..." }'

curl "https://api.swake.io/v1/sdk/notifications?externalUserId=user_123&unreadOnly=true" \
  -H "X-API-Key: ep_live_..."

{
  "data": [
    {
      "id": "01J8...",
      "submissionId": "01J8...",
      "type": "team_reply",
      "payload": { "submissionTitle": "...", "commentPreview": "...", "teamMemberName": "Alex" },
      "readAt": null,
      "createdAt": "2026-03-25T10:05:00Z"
    }
  ],
  "pagination": { "hasMore": false, "cursor": null }
}

curl "https://api.swake.io/v1/sdk/surveys/eligible?external_user_id=user_123" \
  -H "X-API-Key: ep_live_..."

{
  "eligible": [
    {
      "id": "01J8...",
      "type": "nps",
      "title": "How likely are you to recommend us?",
      "presentation": "bottom_sheet",
      "webPosition": "bottom-right",
      "questions": [
        { "id": "q1", "type": "rating", "text": "0–10", "required": true }
      ]
    }
  ]
}

curl -X POST https://api.swake.io/v1/sdk/surveys/01J8.../responses \
  -H "X-API-Key: ep_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "user_123",
    "answers": [ { "question_id": "q1", "value": 9 } ]
  }'

{
  "response": {
    "id": "01J8...",
    "surveyId": "01J8...",
    "externalUserId": "user_123",
    "startedAt": "2026-03-25T10:06:00Z",
    "completedAt": "2026-03-25T10:06:03Z",
    "alreadySubmitted": false
  }
}

# No API key — public endpoints are open (rate-limited by IP)
curl https://api.swake.io/v1/public/portal/acme

X-Swake-Signature:   sha256=a1b2c3d4e5f6...
X-Swake-Timestamp:   1711353600
X-Swake-Event:       feedback.created
X-Swake-Delivery-Id: evt_01J8...

const crypto = require('crypto');

function verify(rawBody, headers, secret) {
  const ts = headers['x-swake-timestamp'];
  const sig = headers['x-swake-signature'].replace('sha256=', '');

  // Reject deliveries older than 5 minutes (replay defence)
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) throw new Error('stale');

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${ts}.${rawBody}`)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    throw new Error('bad signature');
  }
}