Server Data API

A separate, secret-key-authenticated surface for your backend to read data it owns — not for accepting submissions (that’s Submit a Form) and never called from a browser. The workspace is derived entirely from the key; you never pass a workspace ID.

npm install @raykoi/sdk

import { createAdminClient } from '@raykoi/sdk/admin';

const admin = createAdminClient({ apiKey: process.env.RAYKOI_SECRET_KEY });

Requires the Starter plan or above, and never runs in a browser — createAdminClient warns loudly to the console if it detects a window global. This is a deliberately separate entry point from the main SDK (@raykoi/sdk/admin, not @raykoi/sdk) specifically so a bundler can’t accidentally pull it into browser/embed code.

Authentication & scopes

Authorization: Bearer rk_live_..., same key format as everywhere else. Every route additionally requires a scope on that specific key:

Scope	Grants
`read`	List/get forms, submissions, analytics, file download URLs.
`admin`	Everything `read` grants, plus deleting submissions.

A key created with only submit scope (the default for a key meant to authenticate submissions) is rejected by every Server Data API route — read access has to be explicitly granted when you create the key.

Endpoints

List forms

const { forms, pagination } = await admin.forms.list({ limit: 50 });

GET /api/v1/server/forms — supports page, limit, search, sortBy.

Get a form

const form = await admin.forms.get('YOUR_PUBLIC_ID');

GET /api/v1/server/forms/:public_id

List submissions

const { submissions, pagination } = await admin.submissions.list('YOUR_PUBLIC_ID', {
  limit: 50,
  status: 'completed', // or 'spam' | 'suspicious'
});

GET /api/v1/server/forms/:public_id/submissions — supports page, limit, status, search, range (all | 7d | 30d | 90d).

object

Submitted field values, keyed the same way they were submitted.

string

completed, spam, or suspicious, decided server-side by Raykoi’s spam-scoring pipeline (honeypot, CAPTCHA, rate limiting, and repeated-failure signals).

Internal database primary keys and idempotency bookkeeping are never exposed here — id is always the submission’s public ID.

Get a submission

const submission = await admin.submissions.get('YOUR_PUBLIC_ID', submissionId);

GET /api/v1/server/forms/:public_id/submissions/:submission_id

Delete submissions

await admin.submissions.delete('YOUR_PUBLIC_ID', [submissionId1, submissionId2]);

DELETE /api/v1/server/forms/:public_id/submissions — requires admin scope. Up to 500 IDs per call.

Get analytics

const stats = await admin.analytics.get('YOUR_PUBLIC_ID');

GET /api/v1/server/forms/:public_id/analytics — views, starts, submissions, and completion rate, honoring your plan’s analytics retention window.

Get a file’s download URL

const url = await admin.files.getDownloadUrl('YOUR_PUBLIC_ID', filePath);

GET /api/v1/server/forms/:public_id/files/download — returns a short-lived signed URL, same model as the upload side. See File Uploads.

Rate limiting

Keyed per workspace (not per IP) — several backends legitimately calling from behind the same office IP, or one customer’s infrastructure calling from multiple regions, doesn’t cause them to compete for the same limit.

​Authentication & scopes

​Endpoints

​List forms

​Get a form

​List submissions

​Get a submission

​Delete submissions

​Get analytics

​Get a file’s download URL

​Rate limiting

Authentication & scopes

Endpoints

List forms

Get a form

List submissions

Get a submission

Delete submissions

Get analytics

Get a file’s download URL

Rate limiting