REST API

A small, Bearer-authenticated JSON API for SaaSPilot: list your pilots and actions, run actions and read their run history.

Pointing an AI agent at this API?

Hand it the LLM-ready Markdown version — self-contained instructions an agent can follow with just a URL and an API key.

Open /docs/llm/api.md

Getting started

Base URL

All endpoints live under `https://saaspilot.app/api/v1`. `https://saaspilot.app` is the origin you were given (scheme + host, e.g. `https://example.com`). Do not add a trailing slash.

Authentication

Every endpoint requires an API key sent as a Bearer token: `Authorization: Bearer sk_your_key_here`. Keys always start with `sk_`. A missing or invalid key returns `401 { "error": "Invalid or missing API key" }`. Create keys in the app under Profile → API Keys.

Content type

Responses are JSON unless noted (file download returns raw bytes). Request bodies are JSON (`Content-Type: application/json`) except file upload, which is `multipart/form-data`.

Rate limiting

Requests are rate limited per API key. When you exceed a limit you get `429` (or `403` if the limit is configured to block) with an `error` message and, when applicable, a `Retry-After` header (seconds). Back off and retry.

Published endpoints are separate

Actions you publish get their own public URL `https://saaspilot.app/api/p/<slug>` (GET with query params as input, or POST a JSON object). Those are NOT part of this API and do not use `sk_` keys: depending on the endpoint they are open, password-protected (HTTP Basic or `?key=`) or use a per-endpoint key (`X-API-Key: spk_...`). Their output format (json/csv/html/xml/md/text) is chosen per endpoint and can be overridden with `?format=`.

Site bots

Site bots are embeddable AI chat bots whose skills run on the host site. Manage bot projects, bots, skills, resources, secrets (write-only) and members under `/api/v1/bot-projects` and `/api/v1/bots` with your `sk_` key. A host site's backend mints visitor session tokens with the PROJECT secret key (`spb_sk_...`) at `POST /api/v1/bots/:id/sessions`. The browser widget protocol (`/bot/<publicKey>.js`, `/api/bot/<publicKey>/*`) is not part of this API — the complete integration guide is `https://saaspilot.app/docs/llm/site-bots.md`.

Errors

Errors are JSON with an `error` string and a matching HTTP status (`400` bad input, `401` unauthenticated, `403` forbidden, `404` not found, `413` payload too large, `429` rate limited, `500` server error).

Your base URL is https://saaspilot.app. Create API keys under Profile → API Keys.

Endpoints

GET
/api/v1/health

Health check

Confirms the API is up and your key is valid. Handy as a first call to verify credentials and connectivity.

Auth: Bearer tokenAccess: Any valid API key.

Request

curl https://saaspilot.app/api/v1/health \
  -H "Authorization: Bearer sk_your_key_here"

Response

{
  "status": "healthy",
  "timestamp": "2026-07-19T12:00:00.000Z",
  "uptime": 1234.56,
  "version": "1.0.0",
  "apiKey": "My key",
  "userId": "usr_...",
  "message": "API is running successfully"
}
GET
/api/v1/stats

Account & API usage stats

Returns the calling user together with API-usage counters (requests today / this week / this month, error rate, API-key count).

Auth: Bearer tokenAccess: Any valid API key (scoped to the key owner).

Request

curl https://saaspilot.app/api/v1/stats \
  -H "Authorization: Bearer sk_your_key_here"

Response

{
  "user": { "id": "usr_...", "email": "you@example.com", "name": "You", "role": "user", "createdAt": "..." },
  "apiStats": {
    "totalApiKeys": 2,
    "requestsToday": 14,
    "requestsThisWeek": 98,
    "requestsThisMonth": 412,
    "errorRate": "1.20%",
    "errorCount": 5
  },
  "meta": { "timestamp": "...", "apiKey": "My key" }
}
GET
/api/v1/users

List users

Lists users. A regular key returns only its own user record; an admin key returns all users with pagination.

Auth: Bearer tokenAccess: Any valid API key (admin keys see all users; others see themselves).
NameInTypeReq.Description
limitqueryintegernoPage size, 1–100 (default 10). Admin only; ignored for non-admins.
offsetqueryintegernoRows to skip (default 0). Admin only.

Request

curl "https://saaspilot.app/api/v1/users?limit=20&offset=0" \
  -H "Authorization: Bearer sk_your_key_here"

Response

{
  "users": [
    { "id": "usr_...", "email": "you@example.com", "name": "You", "role": "user", "emailVerified": null, "createdAt": "..." }
  ],
  "meta": { "limit": 20, "offset": 0, "total": 1, "apiKey": "My key" }
}
POST
/api/v1/users

Create user (scaffold)

Admin-only endpoint scaffold for creating a user. Ships as a stub in this starter — it validates input and echoes it back rather than persisting. Fill in real creation logic before relying on it.

Auth: Bearer tokenAccess: Admin API keys only (others get 403).
NameInTypeReq.Description
emailbodystringyesNew user email.
namebodystringyesNew user display name.
rolebodystringno'user' (default) or 'admin'.

Request

curl -X POST https://saaspilot.app/api/v1/users \
  -H "Authorization: Bearer sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email":"new@example.com","name":"New User","role":"user"}'

Response

{
  "message": "User creation endpoint - implementation needed",
  "requestedData": { "email": "new@example.com", "name": "New User", "role": "user" },
  "apiKey": "My key"
}
  • This is a template stub — no user is actually created yet.
POST
/api/v1/files

Upload a file

Uploads a file and stores its raw bytes. Use this instead of a form/Server Action for any real upload (Server Actions cap the body at ~1MB; this endpoint does not). Send `multipart/form-data` with a single `file` field.

Auth: Bearer tokenAccess: Any valid API key (the file is owned by the key owner).
NameInTypeReq.Description
fileformfileyesThe file to upload (multipart field name must be "file").

Request

curl -X POST https://saaspilot.app/api/v1/files \
  -H "Authorization: Bearer sk_your_key_here" \
  -F "file=@./photo.png"

Response

{
  "id": "fil_...",
  "filename": "photo.png",
  "url": "/api/v1/files/fil_..."
}
  • Default max size is 100MB (configurable via MAX_FILE_SIZE). Oversized uploads return 413.
  • The returned `url` is the Bearer-gated download endpoint below.
GET
/api/v1/files/:id

Download / preview a file

Streams the raw file bytes with the stored Content-Type. Because it is Bearer-gated you cannot put it directly in an `<img src>`; fetch it with the token and build an object URL client-side.

Auth: Bearer tokenAccess: Any valid API key.
NameInTypeReq.Description
idpathstringyesFile id returned by the upload endpoint.

Request

curl https://saaspilot.app/api/v1/files/fil_your_file_id \
  -H "Authorization: Bearer sk_your_key_here" \
  --output downloaded-file

Response

Raw binary body with the stored `Content-Type` and `Content-Disposition: inline; filename="..."`. Returns `404 { "error": "File not found" }` if unknown.
DELETE
/api/v1/files/:id

Delete a file

Deletes a file owned by the calling key.

Auth: Bearer tokenAccess: Any valid API key (only the owner may delete).
NameInTypeReq.Description
idpathstringyesFile id to delete.

Request

curl -X DELETE https://saaspilot.app/api/v1/files/fil_your_file_id \
  -H "Authorization: Bearer sk_your_key_here"

Response

{ "deleted": true }   // { "deleted": false } with status 404 if not found / not owned
GET
/api/v1/pilots

List pilots

A pilot is one target website/SaaS you drive with SaaSPilot. Returns every pilot visible to the key: the key owner's own pilots (or its tenant's in multi-tenant mode) plus pilots other people shared with the key owner. Each has an action count, the caller's `role` (`owner` | `admin` | `editor` | `user`), `shared` and `sharedBy` (the owner's e-mail for shared pilots). Every role can read pilots/actions/runs and run actions through this API. Stored site credentials are never returned — only `hasCredentials`.

Auth: Bearer tokenAccess: Any valid API key (the key owner's pilots, tenant pilots and pilots shared with them).

Request

curl https://saaspilot.app/api/v1/pilots \
  -H "Authorization: Bearer sk_your_key_here"

Response

{
  "pilots": [
    {
      "id": "k2j4h5...",
      "name": "Acme Shop",
      "baseUrl": "https://shop.acme.test/",
      "description": "Our supplier's web shop",
      "hasCredentials": true,
      "actionCount": 3,
      "role": "owner",
      "shared": false,
      "sharedBy": null,
      "createdAt": "2026-10-03T10:00:00.000Z",
      "updatedAt": "2026-10-03T10:00:00.000Z"
    },
    {
      "id": "p9q8r7...",
      "name": "Partner portal",
      "baseUrl": "https://portal.partner.test/",
      "description": "",
      "hasCredentials": true,
      "actionCount": 1,
      "role": "user",
      "shared": true,
      "sharedBy": "owner@partner.test",
      "createdAt": "2026-10-02T09:00:00.000Z",
      "updatedAt": "2026-10-02T09:00:00.000Z"
    }
  ]
}
GET
/api/v1/pilots/:id

Get a pilot with its actions

One pilot (owned, tenant or shared with the key owner — with `role`, `shared`, `sharedBy` as in the list) plus all of its actions (same shape as `GET /api/v1/actions/:id`).

Auth: Bearer tokenAccess: Any valid API key (owned, tenant or shared pilots — any pilot role).
NameInTypeReq.Description
idpathstringyesPilot id.

Request

curl https://saaspilot.app/api/v1/pilots/PILOT_ID \
  -H "Authorization: Bearer sk_your_key_here"

Response

{ "pilot": { "id": "...", "name": "Acme Shop", "role": "editor", "shared": true, "sharedBy": "owner@acme.test", ... }, "actions": [ { "id": "...", "name": "Search products", ... } ] }
// 404 { "error": "Pilot not found" }
GET
/api/v1/actions

List actions

An action is one automation on a pilot's site (e.g. "search products for {query}"), written by AI as a versioned recipe of validated steps. `status` is `authoring` | `ready` | `failed` | `broken` | `repairing`; only actions with an `activeVersion` can run. `health` reflects the daily health check (`unknown` | `passed` | `failed` | `repaired` | `broken`). Includes the actions of pilots shared with the key owner.

Auth: Bearer tokenAccess: Any valid API key (owned, tenant or shared pilots — any pilot role).
NameInTypeReq.Description
pilotIdquerystringnoOnly actions of this pilot.

Request

curl "https://saaspilot.app/api/v1/actions?pilotId=PILOT_ID" \
  -H "Authorization: Bearer sk_your_key_here"

Response

{
  "actions": [
    {
      "id": "a8d9f0...",
      "pilotId": "k2j4h5...",
      "name": "Search products",
      "goal": "Search the shop for {query} and list name, price, stock and URL",
      "mode": "auto",
      "inputFields": [ { "name": "query", "type": "string", "required": true } ],
      "status": "ready",
      "activeVersion": 2,
      "latestVersion": 2,
      "needsBrowser": false,
      "health": { "status": "passed", "checkedAt": "2026-10-03T06:00:00.000Z", "message": "Health check passed." },
      "job": { "id": "job_...", "kind": "refine", "status": "completed", "error": null, "startedAt": "2026-10-03T10:01:00.000Z" },
      "lastRunAt": "2026-10-03T10:05:00.000Z",
      "createdAt": "...",
      "updatedAt": "..."
    }
  ]
}
GET
/api/v1/actions/:id

Get an action

One action (see `GET /api/v1/actions` for the fields).

Auth: Bearer tokenAccess: Any valid API key (owned, tenant or shared pilots — any pilot role).
NameInTypeReq.Description
idpathstringyesAction id.

Request

curl https://saaspilot.app/api/v1/actions/ACTION_ID \
  -H "Authorization: Bearer sk_your_key_here"

Response

{ "action": { "id": "a8d9f0...", "name": "Search products", "status": "ready", ... } }
// 404 { "error": "Action not found" }
POST
/api/v1/actions/:id/run

Run an action

Runs the action now (synchronously — usually seconds, browser-mode actions up to ~2 minutes) with the given input and returns the run with its data and per-step validation results. Stored pilot credentials are added to the input server-side. Pass `format` to get the data rendered as csv/html/xml/md/text instead of the JSON run object.

Auth: Bearer tokenAccess: Any valid API key with any role on the action's pilot (owner, admin, editor or user — running is allowed for every role). Rate limited per key (`pilot.api.run`).
NameInTypeReq.Description
idpathstringyesAction id.
inputbodyobjectnoInput fields as declared in the action's `inputFields`, e.g. `{"query":"shoes"}`.
versionbodynumbernoRun a specific recipe version instead of the active one.
formatbodystringno`json` (default: the run object) or `csv` | `html` | `xml` | `md` | `text` (just the rendered data).

Request

curl -X POST https://saaspilot.app/api/v1/actions/ACTION_ID/run \
  -H "Authorization: Bearer sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"input":{"query":"shoes"}}'

Response

{
  "run": {
    "id": "r1x...",
    "actionId": "a8d9f0...",
    "trigger": "api",
    "status": "passed",
    "version": 2,
    "input": { "query": "shoes" },
    "data": [ { "name": "Trail Runner", "price": 89.95, "inStock": true, "url": "https://shop.acme.test/p/1001" } ],
    "steps": [ { "id": "fetch_page", "ok": true, "errors": [], "ms": 412 }, { "id": "parse_items", "ok": true, "errors": [], "ms": 38 } ],
    "failedStep": null,
    "error": null,
    "durationMs": 450,
    "createdAt": "2026-10-03T10:05:00.000Z"
  }
}
// 502 with the same body and "status": "failed" when a step fails its validator
// 409 { "error": "This action is still being authored — ..." } when it has no version yet
GET
/api/v1/actions/:id/runs

List recent runs of an action

Newest first; includes runs from the dashboard, the API, published endpoints, webhooks and assistants (`trigger`).

Auth: Bearer tokenAccess: Any valid API key (owned, tenant or shared pilots — any pilot role).
NameInTypeReq.Description
idpathstringyesAction id.
limitquerynumberno1–100, default 20.
dataquerystringno`0` to omit the `data` payloads.

Request

curl "https://saaspilot.app/api/v1/actions/ACTION_ID/runs?limit=5&data=0" \
  -H "Authorization: Bearer sk_your_key_here"

Response

{ "runs": [ { "id": "r1x...", "trigger": "endpoint", "status": "passed", "version": 2, "steps": [ ... ], "durationMs": 450, "createdAt": "..." } ] }
GET
/api/v1/bot-projects

List bot projects

A bot project is one site or product: site URLs, allowed origins, resources, secrets, members, keys and one or more site bots. Returns the key owner's projects (or its tenant's) plus projects shared with them, each with the caller's `role` (`owner` | `admin` | `editor` | `user`). Keys are never returned — only `secretKey.hint` / `webhookSecret.hint`.

Auth: Bearer tokenAccess: Any valid API key.

Request

curl https://saaspilot.app/api/v1/bot-projects \
  -H "Authorization: Bearer sk_your_key_here"

Response

{
  "projects": [
    {
      "id": "bpr_9Qx...",
      "name": "Acme shop",
      "siteUrls": ["https://shop.acme.test/"],
      "allowedOrigins": ["https://shop.acme.test"],
      "httpHosts": ["api.acme.test"],
      "defaultMode": "frontend",
      "webhookUrl": "https://api.acme.test/saaspilot/skills",
      "secretKey": { "hint": "spb_sk_…Xy3Z", "createdAt": "2026-10-19T08:00:00.000Z" },
      "webhookSecret": { "hint": "whsec_sb_…a1B2" },
      "role": "owner", "shared": false, "sharedBy": null,
      "createdAt": "...", "updatedAt": "..."
    }
  ]
}
POST
/api/v1/bot-projects

Create a bot project

Creates a project owned by the key owner. When `allowedOrigins` is omitted it is filled in from `siteUrls`.

Auth: Bearer tokenAccess: Any valid API key. Rate limited per key (`bot.write`).
NameInTypeReq.Description
namebodystringyesProject name (max 80).
siteUrlsbodystring[]noSite URLs (http/https).
allowedOriginsbodystring[]noOrigins the widget may run on, e.g. `https://www.example.com` or `https://*.example.com`.
httpHostsbodystring[]noExtra hosts `http` skills may call (`api.example.com`, `*.example.net`).
defaultModebodystringno`frontend` (default) or `backend` — the mode of new bots.

Request

curl -X POST https://saaspilot.app/api/v1/bot-projects \
  -H "Authorization: Bearer sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme shop","siteUrls":["https://shop.acme.test"]}'

Response

{ "project": { "id": "bpr_9Qx...", "name": "Acme shop", "allowedOrigins": ["https://shop.acme.test"], "role": "owner", ... } }   // 201
GET
/api/v1/bot-projects/:id

Get a bot project

One project (same shape as the list) with the caller's `role`.

Auth: Bearer tokenAccess: Any project role.
NameInTypeReq.Description
idpathstringyesProject id.

Request

curl https://saaspilot.app/api/v1/bot-projects/PROJECT_ID \
  -H "Authorization: Bearer sk_your_key_here"

Response

{ "project": { "id": "bpr_9Qx...", "name": "Acme shop", "role": "editor", ... } }
// 404 { "error": "Project not found" }
PATCH
/api/v1/bot-projects/:id

Update a bot project

Change name, site URLs, allowed origins, http hosts, default mode or the webhook URL (must be a public http(s) URL). Keys are rotated in the dashboard (Access tab) and shown once.

Auth: Bearer tokenAccess: Project admins and the owner.
NameInTypeReq.Description
idpathstringyesProject id.
name / siteUrls / allowedOrigins / httpHosts / defaultModebodysee POSTnoAny field of the create body.
webhookUrlbodystring|nullnoWhere `server` skills are POSTed (signed). `null` clears it.

Request

curl -X PATCH https://saaspilot.app/api/v1/bot-projects/PROJECT_ID \
  -H "Authorization: Bearer sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"webhookUrl":"https://api.acme.test/saaspilot/skills"}'

Response

{ "project": { ... } }
// 400 { "error": "Webhook URL: The URL points to a private network address" }
// 403 { "error": "Only project admins can do that — ask the owner or an admin." }
DELETE
/api/v1/bot-projects/:id

Delete a bot project

Deletes the project and its bots (their scripts stop working).

Auth: Bearer tokenAccess: The owner only.
NameInTypeReq.Description
idpathstringyesProject id.

Request

curl -X DELETE https://saaspilot.app/api/v1/bot-projects/PROJECT_ID \
  -H "Authorization: Bearer sk_your_key_here"

Response

{ "deleted": true }
GET
/api/v1/bot-projects/:id/bots

List the bots of a project

Every bot with its look, prompt, skills, mode and `embedUrl` (the `<script src>`).

Auth: Bearer tokenAccess: Any project role.
NameInTypeReq.Description
idpathstringyesProject id.

Request

curl https://saaspilot.app/api/v1/bot-projects/PROJECT_ID/bots \
  -H "Authorization: Bearer sk_your_key_here"

Response

{
  "bots": [
    {
      "id": "bot_R2...",
      "projectId": "bpr_9Qx...",
      "name": "Support bot",
      "publicKey": "sb_pub_Kq...",
      "enabled": true,
      "mode": "frontend",
      "look": { "display": "floating", "theme": "light", "title": "Ask us anything", "light": { "primary": "#4f46e5", ... }, ... },
      "customCss": "",
      "instructions": "You help shoppers...",
      "greeting": "Hi! How can I help you today?",
      "starterPrompts": ["What can you do?"],
      "aiProfile": "default",
      "resourceIds": ["brs_..."],
      "actionIds": [],
      "skills": [ { "name": "create_widget", "description": "...", "runs": "client", "confirm": false, "enabled": true, "parameters": { ... } } ],
      "embedUrl": "https://saaspilot.app/bot/sb_pub_Kq....js",
      "createdAt": "...", "updatedAt": "..."
    }
  ]
}
POST
/api/v1/bot-projects/:id/bots

Create a bot

Creates a bot (public key `sb_pub_…`) in the project. Any bot field may be passed and is validated like `PATCH /api/v1/bots/:id`.

Auth: Bearer tokenAccess: Project editors, admins and the owner.
NameInTypeReq.Description
idpathstringyesProject id.
namebodystringyesBot name (only shown to you).
modebodystringno`frontend` or `backend` (default: the project's defaultMode).
…bodyany bot fieldnolook, customCss, instructions, greeting, starterPrompts, aiProfile, resourceIds, actionIds, skills, enabled.

Request

curl -X POST https://saaspilot.app/api/v1/bot-projects/PROJECT_ID/bots \
  -H "Authorization: Bearer sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name":"Support bot","instructions":"Help shoppers find products.","look":{"display":"inline","title":"Shop help"}}'

Response

{ "bot": { "id": "bot_R2...", "publicKey": "sb_pub_Kq...", "embedUrl": "https://saaspilot.app/bot/sb_pub_Kq....js", ... } }   // 201
GET
/api/v1/bots/:id

Get a bot

One bot (see the list for the fields).

Auth: Bearer tokenAccess: Any project role.
NameInTypeReq.Description
idpathstringyesBot id.

Request

curl https://saaspilot.app/api/v1/bots/BOT_ID \
  -H "Authorization: Bearer sk_your_key_here"

Response

{ "bot": { "id": "bot_R2...", "name": "Support bot", ... } }
PATCH
/api/v1/bots/:id

Update a bot

Change any of: `name`, `enabled`, `mode` (`frontend` | `backend`), `look` (display floating|inline|button, theme auto|light|dark, light/dark colours primary, primaryText, background, text, userBubble, userText, botBubble, botText, border; radius, font, fontSize, width, height, position, offsetX, offsetY, launcherIcon chat|spark|question|custom, launcherImage, launcherLabel, buttonLabel, avatarUrl, title, subtitle, placeholder, poweredBy — admins only), `customCss` (≤ 20 KB), `instructions`, `greeting`, `starterPrompts` (≤ 6), `aiProfile` (GluedEasy profile; `cc` only by app admins), `resourceIds`, `actionIds` (SaaSPilot actions you can edit — each becomes a `saaspilot` skill) and `skills` (the whole array, see the skills endpoint).

Auth: Bearer tokenAccess: Project editors, admins and the owner. Rate limited per key (`bot.write`).
NameInTypeReq.Description
idpathstringyesBot id.
…bodybot fieldsnoOnly the fields you send change.

Request

curl -X PATCH https://saaspilot.app/api/v1/bots/BOT_ID \
  -H "Authorization: Bearer sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"greeting":"Hi! Ask me about pricing.","look":{"theme":"auto","light":{"primary":"#0f766e"}}}'

Response

{ "bot": { ... } }
// 400 { "error": "Skills are not valid: skills[0].name must match ...", "issues": [ { "path": "skills[0].name", "message": "..." } ] }
// 403 { "error": "Only admins can pick the cc profile" }
DELETE
/api/v1/bots/:id

Delete a bot

Its script stops working on every site. Chats are kept.

Auth: Bearer tokenAccess: Project editors, admins and the owner.
NameInTypeReq.Description
idpathstringyesBot id.

Request

curl -X DELETE https://saaspilot.app/api/v1/bots/BOT_ID \
  -H "Authorization: Bearer sk_your_key_here"

Response

{ "deleted": true }
GET
/api/v1/bots/:id/skills

Get a bot's skills

The whole skill array (the same JSON the builder's Skills tab imports/exports).

Auth: Bearer tokenAccess: Any project role.
NameInTypeReq.Description
idpathstringyesBot id.

Request

curl https://saaspilot.app/api/v1/bots/BOT_ID/skills \
  -H "Authorization: Bearer sk_your_key_here"

Response

{ "skills": [ { "name": "create_widget", "description": "Create a pricing widget", "runs": "client", "confirm": true, "enabled": true, "parameters": { "type": "object", "properties": { "name": { "type": "string" } }, "required": ["name"] } } ] }
PUT
/api/v1/bots/:id/skills

Replace a bot's skills

Body: the whole JSON array (or `{ "skills": [...] }`). Each skill: `name` (`^[a-z][a-z0-9_]{0,63}$`, unique), `description`, `runs` (`client` = the page runs it; `server` = signed POST to the project webhook, backend mode; `http` = SaaSPilot calls `http: {method, url, headers?, body?}` with `{{args.x}}` / `{{secret:NAME}}` templates, backend mode, allowlisted hosts only; `saaspilot` = runs the SaaSPilot action `action`), `confirm` (visitor confirms first), `enabled`, `parameters` (a JSON Schema object, ≤ 16 KB). At most 80 skills. Invalid input → 400 with `issues`.

Auth: Bearer tokenAccess: Project editors, admins and the owner.
NameInTypeReq.Description
idpathstringyesBot id.

Request

curl -X PUT https://saaspilot.app/api/v1/bots/BOT_ID/skills \
  -H "Authorization: Bearer sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '[{"name":"get_status","description":"Live order status","runs":"http","http":{"method":"GET","url":"https://api.acme.test/orders/{{args.id}}","headers":{"Authorization":"Bearer {{secret:API_KEY}}"}},"parameters":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}}]'

Response

{ "skills": [ ... ] }
// 400 { "error": "Skills are not valid: ...", "issues": [ { "path": "skills[0].http.url", "message": "must be an http(s) URL template" } ] }
GET
/api/v1/bot-projects/:id/resources

List resources

Resources are reference material put into the bot's instructions: `site` (a URL, optionally linked to a SaaSPilot pilot), `doc` (a URL fetched as text when saved — max 200 KB — or pasted text) and `note` (free text). Together they are cut to a ~60 K character budget with a clear marker; `usage` shows how much of it all resources would use.

Auth: Bearer tokenAccess: Any project role.
NameInTypeReq.Description
idpathstringyesProject id.

Request

curl https://saaspilot.app/api/v1/bot-projects/PROJECT_ID/resources \
  -H "Authorization: Bearer sk_your_key_here"

Response

{ "resources": [ { "id": "brs_...", "kind": "doc", "name": "API docs", "url": "https://docs.acme.test/api", "source": "url", "pilotId": null, "chars": 18240, "fetchedAt": "...", "fetchError": null, "preview": "..." } ], "usage": { "used": 18300, "budget": 60000 } }
POST
/api/v1/bot-projects/:id/resources

Add a resource

A doc with `source: "url"` is fetched now (SSRF-guarded, max 200 KB); `fetchError` tells you when that failed.

Auth: Bearer tokenAccess: Project editors, admins and the owner.
NameInTypeReq.Description
idpathstringyesProject id.
kindbodystringyes`site` | `doc` | `note`.
namebodystringyesShown to the model as the section title.
urlbodystringnoRequired for `site` and for a `doc` with `source: "url"`.
sourcebodystringnoDoc only: `url` (fetch) or `text` (pasted `content`).
contentbodystringnoNote text / pasted doc text / site description.
pilotIdbodystringnoSite only: link a SaaSPilot pilot ("drive with SaaSPilot").

Request

curl -X POST https://saaspilot.app/api/v1/bot-projects/PROJECT_ID/resources \
  -H "Authorization: Bearer sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"kind":"note","name":"Opening hours","content":"Mon–Fri 9–17 CET"}'

Response

{ "resource": { "id": "brs_...", "kind": "note", "name": "Opening hours", "content": "Mon–Fri 9–17 CET", ... } }   // 201
GET
/api/v1/bot-projects/:id/resources/:resourceId

Get a resource

One resource including its full cached text (`content`).

Auth: Bearer tokenAccess: Any project role.
NameInTypeReq.Description
idpathstringyesProject id.
resourceIdpathstringyesResource id.

Request

curl https://saaspilot.app/api/v1/bot-projects/PROJECT_ID/resources/RESOURCE_ID \
  -H "Authorization: Bearer sk_your_key_here"

Response

{ "resource": { "id": "brs_...", "content": "...", ... } }
PATCH
/api/v1/bot-projects/:id/resources/:resourceId

Update a resource

Same fields as POST (the kind cannot change). `{ "refetch": true }` fetches a doc URL again.

Auth: Bearer tokenAccess: Project editors, admins and the owner.
NameInTypeReq.Description
idpathstringyesProject id.
resourceIdpathstringyesResource id.

Request

curl -X PATCH https://saaspilot.app/api/v1/bot-projects/PROJECT_ID/resources/RESOURCE_ID \
  -H "Authorization: Bearer sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"refetch":true}'

Response

{ "resource": { ... } }
DELETE
/api/v1/bot-projects/:id/resources/:resourceId

Delete a resource

Bots stop reading it.

Auth: Bearer tokenAccess: Project editors, admins and the owner.
NameInTypeReq.Description
idpathstringyesProject id.
resourceIdpathstringyesResource id.

Request

curl -X DELETE https://saaspilot.app/api/v1/bot-projects/PROJECT_ID/resources/RESOURCE_ID \
  -H "Authorization: Bearer sk_your_key_here"

Response

{ "deleted": true }
GET
/api/v1/bot-projects/:id/secrets

List secrets (names only)

Secrets are write-only: you get each name and a `••••1234` hint, never the value. They are used ONLY server-side as `{{secret:NAME}}` in `http` skills — never sent to the model or a browser.

Auth: Bearer tokenAccess: Project admins and the owner.
NameInTypeReq.Description
idpathstringyesProject id.

Request

curl https://saaspilot.app/api/v1/bot-projects/PROJECT_ID/secrets \
  -H "Authorization: Bearer sk_your_key_here"

Response

{ "secrets": [ { "name": "API_KEY", "hint": "••••9f2c", "updatedAt": "..." } ] }
POST
/api/v1/bot-projects/:id/secrets

Create or replace a secret

Names use A–Z, 0–9 and `_` and start with a letter. The value (≤ 8 KB) is encrypted at rest and never returned.

Auth: Bearer tokenAccess: Project admins and the owner.
NameInTypeReq.Description
idpathstringyesProject id.
namebodystringyese.g. `API_KEY`.
valuebodystringyesThe secret value.

Request

curl -X POST https://saaspilot.app/api/v1/bot-projects/PROJECT_ID/secrets \
  -H "Authorization: Bearer sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name":"API_KEY","value":"sk_live_..."}'

Response

{ "secret": { "name": "API_KEY", "hint": "••••9f2c" } }   // 201
PUT
/api/v1/bot-projects/:id/secrets/:name

Replace a secret value

Write-only, like POST.

Auth: Bearer tokenAccess: Project admins and the owner.
NameInTypeReq.Description
idpathstringyesProject id.
namepathstringyesSecret name.
valuebodystringyesThe new value.

Request

curl -X PUT https://saaspilot.app/api/v1/bot-projects/PROJECT_ID/secrets/API_KEY \
  -H "Authorization: Bearer sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"value":"sk_live_new..."}'

Response

{ "secret": { "name": "API_KEY", "hint": "••••a8b1" } }
DELETE
/api/v1/bot-projects/:id/secrets/:name

Delete a secret

`http` skills that use it fail with "unknown secret" until you add it again.

Auth: Bearer tokenAccess: Project admins and the owner.
NameInTypeReq.Description
idpathstringyesProject id.
namepathstringyesSecret name.

Request

curl -X DELETE https://saaspilot.app/api/v1/bot-projects/PROJECT_ID/secrets/API_KEY \
  -H "Authorization: Bearer sk_your_key_here"

Response

{ "deleted": true }   // 404 { "error": "Secret not found" }
GET
/api/v1/bot-projects/:id/members

List members

The owner plus every member. Roles as for pilots: `user` = chat/test only, `editor` = edit bots/skills/resources and read chats, `admin` = also secrets, access and members.

Auth: Bearer tokenAccess: Any project role.
NameInTypeReq.Description
idpathstringyesProject id.

Request

curl https://saaspilot.app/api/v1/bot-projects/PROJECT_ID/members \
  -H "Authorization: Bearer sk_your_key_here"

Response

{ "owner": { "email": "owner@acme.test", "name": "Olivia" }, "members": [ { "id": "bpm_...", "email": "ed@acme.test", "name": "Ed", "userId": "...", "role": "editor", "status": "active", "invitedAt": "..." } ] }
POST
/api/v1/bot-projects/:id/members

Invite a member

An existing account gets access at once; an unknown address gets a pending invitation e-mail (it can sign up even when signup is closed).

Auth: Bearer tokenAccess: Project admins and the owner. Rate limited (`bot.members.invite`).
NameInTypeReq.Description
idpathstringyesProject id.
emailbodystringyesE-mail address.
rolebodystringyes`user` | `editor` | `admin`.

Request

curl -X POST https://saaspilot.app/api/v1/bot-projects/PROJECT_ID/members \
  -H "Authorization: Bearer sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email":"ed@acme.test","role":"editor"}'

Response

{ "member": { "email": "ed@acme.test", "changed": true, "invitedNewUser": false, "emailed": true } }   // 201
PATCH
/api/v1/bot-projects/:id/members/:memberId

Change a member's role

The owner is implicit and cannot be changed.

Auth: Bearer tokenAccess: Project admins and the owner.
NameInTypeReq.Description
idpathstringyesProject id.
memberIdpathstringyesMember id.
rolebodystringyes`user` | `editor` | `admin`.

Request

curl -X PATCH https://saaspilot.app/api/v1/bot-projects/PROJECT_ID/members/MEMBER_ID \
  -H "Authorization: Bearer sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"role":"admin"}'

Response

{ "updated": true }
DELETE
/api/v1/bot-projects/:id/members/:memberId

Remove a member (or leave)

Admins remove anyone; any member can remove themself.

Auth: Bearer tokenAccess: Project admins and the owner, or the member themself.
NameInTypeReq.Description
idpathstringyesProject id.
memberIdpathstringyesMember id.

Request

curl -X DELETE https://saaspilot.app/api/v1/bot-projects/PROJECT_ID/members/MEMBER_ID \
  -H "Authorization: Bearer sk_your_key_here"

Response

{ "deleted": true }
POST
/api/v1/bots/:id/sessions

Mint a site-bot session token (backend mode)

Called by the HOST SITE'S BACKEND for a signed-in user, with the bot project's secret key (`spb_sk_…`, created/rotated in the dashboard's Access tab and shown once) — never from a browser. Returns an opaque, signed token bound to this bot, this user and the project's allowed origins. Pass it to the widget (`data-token` or `SaaSPilotBot.setToken()`); in backend mode chat requests without a valid token are rejected, the verified `user` goes into the model context and into every webhook call, and `server` / `http` skills become available. Rotating the project key revokes all tokens.

Auth: Bot project secret key (spb_sk_…, server-side only)Access: The bot's project secret key. Rate limited per project (`bot.session.mint`).
NameInTypeReq.Description
idpathstringyesBot id (not the public key).
userbodyobjectyes`{ id, name?, email?, roles?: string[] }` — the user as YOUR backend knows them.
contextbodyobjectnoTrusted extra context (≤ 8 KB), e.g. `{ "plan": "pro" }`; reaches the model and every webhook call.
ttlSecondsbodynumberno60–86400, default 3600.

Request

curl -X POST https://saaspilot.app/api/v1/bots/BOT_ID/sessions \
  -H "Authorization: Bearer spb_sk_your_project_key" \
  -H "Content-Type: application/json" \
  -d '{"user":{"id":"42","name":"Ann","email":"ann@acme.test","roles":["customer"]},"context":{"plan":"pro"},"ttlSeconds":3600}'

Response

{ "token": "sbt_3kq...", "expiresAt": "2026-10-19T13:00:00.000Z" }
// 401 { "error": "Invalid project key for this bot" }
// 400 { "error": "user.id is required" }
  • Keep `spb_sk_` keys on your server. The widget-side protocol and webhook format are in /docs/llm/site-bots.md.
GET
/api/v1/bots/:id/conversations

List a bot's conversations

Newest first. Builder-preview chats are left out unless `preview=1`.

Auth: Bearer tokenAccess: Project editors, admins and the owner.
NameInTypeReq.Description
idpathstringyesBot id.
limitquerynumberno1–100, default 20.
previewquerystringno`1` to include builder-preview chats.

Request

curl "https://saaspilot.app/api/v1/bots/BOT_ID/conversations?limit=10" \
  -H "Authorization: Bearer sk_your_key_here"

Response

{ "conversations": [ { "id": "sbc_...", "botId": "bot_R2...", "visitorId": "v_...", "user": { "id": "42", "name": "Ann" }, "origin": "https://shop.acme.test", "pageUrl": "https://shop.acme.test/pricing", "preview": false, "offered": ["create_widget"], "messageCount": 4, "lastMessageAt": "...", "createdAt": "..." } ] }
GET
/api/v1/bots/:id/conversations/:cid

Get a conversation transcript

Every message in order: `visitor`, `bot`, `skill_call` (data: callId, skill, args, runs, confirm) and `skill_result` (data: callId, skill, ok, result | error).

Auth: Bearer tokenAccess: Project editors, admins and the owner.
NameInTypeReq.Description
idpathstringyesBot id.
cidpathstringyesConversation id.

Request

curl https://saaspilot.app/api/v1/bots/BOT_ID/conversations/CONVERSATION_ID \
  -H "Authorization: Bearer sk_your_key_here"

Response

{
  "conversation": { "id": "sbc_...", ... },
  "messages": [
    { "id": "bm_1", "role": "visitor", "content": "Create a widget called Pro", "data": null, "createdAt": "..." },
    { "id": "bm_2", "role": "skill_call", "content": "create_widget {\"name\":\"Pro\"}", "data": { "callId": "call_...", "skill": "create_widget", "args": { "name": "Pro" }, "runs": "client", "confirm": false }, "createdAt": "..." },
    { "id": "bm_3", "role": "skill_result", "content": "{\"ok\":true}", "data": { "callId": "call_...", "skill": "create_widget", "ok": true, "result": "{\"ok\":true}" }, "createdAt": "..." },
    { "id": "bm_4", "role": "bot", "content": "Done — the **Pro** widget is ready.", "data": null, "createdAt": "..." }
  ]
}