REST API v1

Base URL: https://spkros.com

Authentication

# Include in every request Authorization: Bearer prsnai_live_YOUR_KEY

Generate API keys at /settings/api-keys. Keys are speaker-scoped and have read+write access by default.

Endpoints

GET/api/v1/lectures

List all lectures belonging to the authenticated speaker.

Response

{
  "data": [
    {
      "id": "uuid",
      "title": "Comunicação de Alto Impacto",
      "status": "ready",
      "qrCodeToken": "DEMO2026",
      "createdAt": "2026-04-06T12:00:00.000Z"
    }
  ],
  "meta": { "requestId": "uuid", "timestamp": "2026-04-06T12:00:01.000Z" }
}

curl

curl -X GET https://spkros.com
/api/v1/lectures \
  -H "Authorization: Bearer prsnai_live_YOUR_KEY"

GET/api/v1/lectures/:id/analytics

Get engagement analytics for a specific lecture.

Response

{
  "data": {
    "lectureId": "uuid",
    "title": "Comunicação de Alto Impacto",
    "status": "ready",
    "enrollments": 42,
    "avgCompletedDays": 18,
    "totalAiInteractions": 137
  },
  "meta": { "requestId": "uuid", "timestamp": "..." }
}

curl

curl -X GET https://spkros.com
/api/v1/lectures/LECTURE_ID/analytics \
  -H "Authorization: Bearer prsnai_live_YOUR_KEY"

POST/api/v1/enrollments

Get the join URL and QR token for a lecture to share with an attendee.

Request body

{
  "lectureId": "uuid"
}

Response

{
  "data": {
    "lectureId": "uuid",
    "lectureTitle": "Comunicação de Alto Impacto",
    "qrCodeToken": "DEMO2026",
    "joinUrl": "https://spkros.com
/join/DEMO2026",
    "instructions": "Share the joinUrl with your attendee..."
  },
  "meta": { "requestId": "uuid", "timestamp": "..." }
}

curl

curl -X POST https://spkros.com
/api/v1/enrollments \
  -H "Authorization: Bearer prsnai_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lectureId": "YOUR_LECTURE_ID"}'

GET/api/v1/enrollments/:id

Get progress details for a specific enrollment.

Response

{
  "data": {
    "id": "uuid",
    "lectureId": "uuid",
    "startDate": "2026-03-19",
    "isActive": true,
    "completedDays": [1,2,3,4,5,6,7,8,9,10],
    "totalCompleted": 10,
    "progressPercent": 33,
    "createdAt": "2026-03-19T10:00:00.000Z"
  },
  "meta": { "requestId": "uuid", "timestamp": "..." }
}

curl

curl -X GET https://spkros.com
/api/v1/enrollments/ENROLLMENT_ID \
  -H "Authorization: Bearer prsnai_live_YOUR_KEY"

GET/api/v1/keys

List all API keys for the authenticated speaker. Requires Clerk session (UI only).

Response

{
  "data": [
    {
      "id": "uuid",
      "name": "Zapier integration",
      "prefix": "prsnai_live_a1b2",
      "scopes": ["read", "write"],
      "createdAt": "2026-04-01T09:00:00.000Z",
      "lastUsedAt": "2026-04-06T08:30:00.000Z",
      "revokedAt": null
    }
  ],
  "meta": { "requestId": "uuid", "timestamp": "..." }
}

curl

# Key management requires a Clerk session — use the UI at /settings/api-keys

Webhooks

Configure a webhook URL on any lecture at /lectures/:id. Events are delivered as signed POST requests.

enrollment.created

Fired when an attendee enrolls via QR code.

{ "enrollmentId": "uuid", "userId": "clerk_user_id", "lectureId": "uuid" }

day.completed

Fired when an attendee marks a day as complete.

{ "enrollmentId": "uuid", "userId": "clerk_user_id", "dayNumber": 7, "lectureId": "uuid" }

journey.completed

Fired when an attendee completes Day 30.

{ "enrollmentId": "uuid", "userId": "clerk_user_id", "dayNumber": 30, "lectureId": "uuid" }

Verifying signatures

// Node.js example
const { createHmac } = require("crypto");

function verifyWebhook(secret, body, headers) {
  const timestamp = headers["x-webhook-timestamp"];
  const expected = createHmac("sha256", secret)
    .update(timestamp + "." + body)
    .digest("hex");
  return headers["x-webhook-signature"] === "sha256=" + expected;
}

Rate Limits

Endpoint	Limit	Window
/api/v1/*	100 requests	Per minute, per key
/api/chat	20 requests	Per hour, per user
/api/enrollments	10 requests	Per minute, per IP

Rate limit headers: X-RateLimit-Remaining, X-RateLimit-Reset

Get your API key →