Projects, keys and tokens
Create projects, ingest keys and API tokens on a self-hosted engine, manage keys and tokens anywhere, and read usage.
The engine knows three things about access: projects, ingest keys and API tokens. It has no users and no organizations. Those exist only in Sypnia Cloud, in the app, and have no public API at launch.
| You want to | Engine (self-hosted) | Sypnia Cloud |
|---|---|---|
| Create or delete a project | This API, with the root token | In the app |
| Create or revoke ingest keys and API tokens | This API, with the root token or an admin token of the project | This API with an admin token, or in the app |
| Invite people, change plan, see invoices | Does not exist | In the app |
The project object
Fields
-
idstring optionalprj_…. -
slugstring optionalA short name for URLs and commands. Lowercase letters, digits and hyphens, 2 to 40 characters. Cannot be changed.
-
namestring optionalThe name people see.
-
timezonestring optionalAn IANA time zone. Days, «today» and «yesterday» are cut in it.
-
environmentsarray of string optionalThe environments that sent data in the last 30 days.
-
settingsobject optional -
settings.allowed_originsarray of string, up to 50 itemsOrigins allowed to send browser data, such as
https://shop.example.com. A leading*.matches subdomains. Empty accepts any origin. -
settings.replayobjectRecording rules. The SDK reads them from the ingest’s config call.
-
settings.replay.enabledbooleanfalseswitches replay off for the project.Default:
true -
settings.replay.sample_ratenumber, 0 to 1The share of sessions recorded from their first moment. Sessions outside it are still recorded from 30 seconds before their first error, rage click or dead click.
Default:
0.1 -
settings.replay.mask_all_textbooleantruemasks every text on the page, not only what people type. What people type is always masked, and password, card and one-time-code fields can never be unmasked.Default:
false -
settings.replay.blocked_routesarray of string, up to 100 itemsRoutes where nothing is recorded and no snapshot is taken.
*matches any characters:/account/*. -
settings.replay.always_recordarray of object, up to 100 itemsPeople and accounts whose sessions are always recorded from the start, for example while you help a customer.
-
settings.snapshotsobject -
settings.snapshots.sample_ratenumber, 0 to 1The share of sessions that take page snapshots, for click maps.
Default:
0.5 -
settings.agentobject -
settings.agent.enabledbooleanfalseswitches the agent off for this project: no analysis, no weekly suggestions from a model. Nothing is sent to an AI provider.Default:
true -
settings.agent.languagestringThe language the agent writes in, as a BCP 47 tag (
en,es).Default:
en -
settings.agent.auto_pull_requestsstringSypnia Cloud only.
high_confidenceopens a pull request by itself when an analysis ishigh. One of:off,high_confidence.Default:
off -
created_attimestamp optional
The ingest key object
Fields
-
idstring optionalThe record’s id,
key_…. Use it to revoke the key. -
keystring optionalThe key itself,
spk_and 32 hex characters. Public: it goes in your app’s code. -
namestring optional -
rate_limit_per_minuteinteger optionalRequests per minute accepted from one address with this key.
-
created_attimestamp optional -
last_used_attimestamp or null optionalAccurate to the hour.
-
revoked_attimestamp or null optional
The API token object
Fields
-
idstring optionalThe record’s id,
tok_…. Use it to revoke the token. -
namestring optional -
prefixstring optionalThe first 12 characters of the secret.
-
scopesarray of string optionalOne of:
read,replay,admin. -
created_attimestamp optional -
last_used_attimestamp or null optionalAccurate to the hour.
-
expires_attimestamp or null optional -
revoked_attimestamp or null optional
List projects
/v1/projects EngineCloud With the root token, every project of the engine. With an API token, a list with the one project the token belongs to.
Query parameters
-
limitinteger, 1 to 200 optionalMost items to return.
Default:
50 -
cursorstring optionalThe
next_cursorof the previous page. Keep every other parameter the same.
Request
curl "https://sypnia.example.com/v1/projects" \
-H "Authorization: Bearer $SYPNIA_ROOT_TOKEN"Response200
{
"data": [
{
"id": "prj_5k2m9x4q7w1z",
"slug": "shop",
"name": "Shop",
"timezone": "UTC",
"environments": [
"production",
"development"
],
"settings": {
"allowed_origins": [
"https://shop.example.com"
],
"replay": {
"enabled": true,
"sample_rate": 0.1,
"mask_all_text": false,
"blocked_routes": [
"/account/cards"
],
"always_record": [
{
"person": "u_1042",
"note": "Reported the checkout bug",
"until": "2026-03-26T00:00:00Z"
}
]
},
"snapshots": {
"sample_rate": 0.5
},
"agent": {
"enabled": true,
"language": "en",
"auto_pull_requests": "off"
}
},
"created_at": "2026-02-02T09:15:00Z"
}
],
"next_cursor": null
}Create a project
/v1/projects Engine Creates a project and its first ingest key, which comes back in ingest_key. Self-hosted engines only: on
Sypnia Cloud projects are created in the app, where they belong to an organization and a plan, and this call
answers 403 cloud_managed.
Headers
-
Idempotency-Keystring, up to 255 characters optionalA value of your own, 1 to 255 characters, that makes the call safe to repeat. See idempotency.
Body
-
namestring, up to 80 characters requiredThe name people see.
-
slugstring optionalDefaults to the name in lowercase with hyphens.
-
timezonestring optionalAn IANA time zone, such as
America/Bogota.Default:
UTC -
settingsobject optional -
settings.allowed_originsarray of string, up to 50 itemsOrigins allowed to send browser data, such as
https://shop.example.com. A leading*.matches subdomains. Empty accepts any origin. -
settings.replayobjectRecording rules. The SDK reads them from the ingest’s config call.
-
settings.replay.enabledbooleanfalseswitches replay off for the project.Default:
true -
settings.replay.sample_ratenumber, 0 to 1The share of sessions recorded from their first moment. Sessions outside it are still recorded from 30 seconds before their first error, rage click or dead click.
Default:
0.1 -
settings.replay.mask_all_textbooleantruemasks every text on the page, not only what people type. What people type is always masked, and password, card and one-time-code fields can never be unmasked.Default:
false -
settings.replay.blocked_routesarray of string, up to 100 itemsRoutes where nothing is recorded and no snapshot is taken.
*matches any characters:/account/*. -
settings.replay.always_recordarray of object, up to 100 itemsPeople and accounts whose sessions are always recorded from the start, for example while you help a customer.
-
settings.snapshotsobject -
settings.snapshots.sample_ratenumber, 0 to 1The share of sessions that take page snapshots, for click maps.
Default:
0.5 -
settings.agentobject -
settings.agent.enabledbooleanfalseswitches the agent off for this project: no analysis, no weekly suggestions from a model. Nothing is sent to an AI provider.Default:
true -
settings.agent.languagestringThe language the agent writes in, as a BCP 47 tag (
en,es).Default:
en -
settings.agent.auto_pull_requestsstringSypnia Cloud only.
high_confidenceopens a pull request by itself when an analysis ishigh. One of:off,high_confidence.Default:
off
Request
curl -X POST "https://sypnia.example.com/v1/projects" \
-H "Authorization: Bearer $SYPNIA_ROOT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "Shop", "slug": "shop", "timezone": "UTC"}'Response201
{
"id": "prj_5k2m9x4q7w1z",
"slug": "shop",
"name": "Shop",
"timezone": "UTC",
"environments": [],
"settings": {
"allowed_origins": [],
"replay": {
"enabled": true,
"sample_rate": 0.1,
"mask_all_text": false,
"blocked_routes": [],
"always_record": []
},
"snapshots": {
"sample_rate": 0.5
},
"agent": {
"enabled": true,
"language": "en",
"auto_pull_requests": "off"
}
},
"created_at": "2026-02-02T09:15:00Z",
"ingest_key": {
"id": "key_3n8v2c6b1m4x",
"key": "spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e",
"name": "Default",
"rate_limit_per_minute": 600,
"created_at": "2026-02-02T09:15:00Z",
"last_used_at": null,
"revoked_at": null
}
}Errors
- 400
invalid_requestnameis missing,slughas characters other thana-z 0-9 -, ortimezoneis not an IANA name. - 403
cloud_managedThe request went to Sypnia Cloud. Create projects in the app.
- 403
forbiddenThe credential is not the root token.
- 409
conflictA project with this
slugexists.
Get a project
/v1/projects/{project_ref} EngineCloud One project with its settings.
Path parameters
-
project_refstring requiredThe project’s id (
prj_…) or slug.
Request
curl "https://api.sypnia.com/v1/projects/shop" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN"Response200
{
"id": "prj_5k2m9x4q7w1z",
"slug": "shop",
"name": "Shop",
"timezone": "UTC",
"environments": [
"production",
"development"
],
"settings": {
"allowed_origins": [
"https://shop.example.com"
],
"replay": {
"enabled": true,
"sample_rate": 0.1,
"mask_all_text": false,
"blocked_routes": [
"/account/cards"
],
"always_record": [
{
"person": "u_1042",
"note": "Reported the checkout bug",
"until": "2026-03-26T00:00:00Z"
}
]
},
"snapshots": {
"sample_rate": 0.5
},
"agent": {
"enabled": true,
"language": "en",
"auto_pull_requests": "off"
}
},
"created_at": "2026-02-02T09:15:00Z"
}Errors
- 404
not_foundNo such project, or the token belongs to another one.
Update a project
/v1/projects/{project_ref} EngineCloud Changes the fields you send and leaves the rest. settings is merged key by key: send only the settings you
want to change. Recording rules (settings.replay, settings.snapshots) reach browsers with their next
session, through the ingest’s config call; no deploy is needed.
Path parameters
-
project_refstring requiredThe project’s id (
prj_…) or slug.
Body
-
namestring, up to 80 characters optionalThe name people see.
-
timezonestring optionalAn IANA time zone. Past days are not recut.
-
settingsobject optional -
settings.allowed_originsarray of string, up to 50 itemsOrigins allowed to send browser data, such as
https://shop.example.com. A leading*.matches subdomains. Empty accepts any origin. -
settings.replayobjectRecording rules. The SDK reads them from the ingest’s config call.
-
settings.replay.enabledbooleanfalseswitches replay off for the project.Default:
true -
settings.replay.sample_ratenumber, 0 to 1The share of sessions recorded from their first moment. Sessions outside it are still recorded from 30 seconds before their first error, rage click or dead click.
Default:
0.1 -
settings.replay.mask_all_textbooleantruemasks every text on the page, not only what people type. What people type is always masked, and password, card and one-time-code fields can never be unmasked.Default:
false -
settings.replay.blocked_routesarray of string, up to 100 itemsRoutes where nothing is recorded and no snapshot is taken.
*matches any characters:/account/*. -
settings.replay.always_recordarray of object, up to 100 itemsPeople and accounts whose sessions are always recorded from the start, for example while you help a customer.
-
settings.snapshotsobject -
settings.snapshots.sample_ratenumber, 0 to 1The share of sessions that take page snapshots, for click maps.
Default:
0.5 -
settings.agentobject -
settings.agent.enabledbooleanfalseswitches the agent off for this project: no analysis, no weekly suggestions from a model. Nothing is sent to an AI provider.Default:
true -
settings.agent.languagestringThe language the agent writes in, as a BCP 47 tag (
en,es).Default:
en -
settings.agent.auto_pull_requestsstringSypnia Cloud only.
high_confidenceopens a pull request by itself when an analysis ishigh. One of:off,high_confidence.Default:
off
Request
curl -X PATCH "https://api.sypnia.com/v1/projects/shop" \
-H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"settings": {"replay": {"blocked_routes": ["/account/cards"]}}}'Response200
{
"id": "prj_5k2m9x4q7w1z",
"slug": "shop",
"name": "Shop",
"timezone": "UTC",
"environments": [
"production",
"development"
],
"settings": {
"allowed_origins": [
"https://shop.example.com"
],
"replay": {
"enabled": true,
"sample_rate": 0.1,
"mask_all_text": false,
"blocked_routes": [
"/account/cards"
],
"always_record": [
{
"person": "u_1042",
"note": "Reported the checkout bug",
"until": "2026-03-26T00:00:00Z"
}
]
},
"snapshots": {
"sample_rate": 0.5
},
"agent": {
"enabled": true,
"language": "en",
"auto_pull_requests": "off"
}
},
"created_at": "2026-02-02T09:15:00Z"
}Errors
- 400
invalid_requestA setting is out of range or unknown.
paramnames it, for examplesettings.replay.sample_rate. - 404
not_foundNo such project, or the token belongs to another one.
Delete a project
/v1/projects/{project_ref} Engine Deletes the project, its keys and tokens, and all of its data, for good. Ingest for its keys stops at once;
stored objects are removed within 24 hours. Self-hosted engines only. To confirm, send the project’s slug in
the confirm query parameter.
Path parameters
-
project_refstring requiredThe project’s id (
prj_…) or slug.
Query parameters
-
confirmstring requiredThe project’s slug, typed again.
Request
curl -X DELETE "https://sypnia.example.com/v1/projects/shop?confirm=shop" \
-H "Authorization: Bearer $SYPNIA_ROOT_TOKEN"Errors
- 400
invalid_requestconfirmis missing or is not the project’s slug. - 403
cloud_managedThe request went to Sypnia Cloud. Delete projects in the app.
- 404
not_foundNo such project.
List ingest keys
/v1/keys EngineCloud The project’s ingest keys, including revoked ones. An ingest key is public, so the list shows each key in full.
Query parameters
-
projectstring optionalThe project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is
403.
Request
curl "https://api.sypnia.com/v1/keys" \
-H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN"Response200
{
"data": [
{
"id": "key_3n8v2c6b1m4x",
"key": "spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e",
"name": "Web app",
"rate_limit_per_minute": 600,
"created_at": "2026-02-02T09:15:00Z",
"last_used_at": "2026-03-12T10:31:58Z",
"revoked_at": null
}
],
"next_cursor": null
}Create an ingest key
/v1/keys EngineCloud Creates another ingest key for the project. Give each app or platform its own key (web, mobile, server), so you can revoke one without stopping the others. A project has at most 20 keys that are not revoked.
Query parameters
-
projectstring optionalThe project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is
403.
Headers
-
Idempotency-Keystring, up to 255 characters optionalA value of your own, 1 to 255 characters, that makes the call safe to repeat. See idempotency.
Body
-
namestring, up to 80 characters requiredWhat the key is for.
-
rate_limit_per_minuteinteger, 10 to 6,000 optionalRequests per minute accepted from one address with this key. Raise it for a server that sends for many people from one address.
Default:
600
Request
curl -X POST "https://api.sypnia.com/v1/keys" \
-H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "Checkout API"}'Response201
{
"id": "key_8b5n2m7v4c1x",
"key": "spk_a3c9e1f7b5d2084c6e0a9f3b7d1c5e82",
"name": "Checkout API",
"rate_limit_per_minute": 600,
"created_at": "2026-03-12T10:40:00Z",
"last_used_at": null,
"revoked_at": null
}Errors
- 409
limit_reachedThe project already has 20 keys that are not revoked.
Revoke an ingest key
/v1/keys/{key_id} EngineCloud Revokes the key. Ingest with it answers 401 within one minute. The record stays in the list with revoked_at. Revoking cannot be undone; create a new key instead.
Path parameters
-
key_idstring requiredThe key’s record id (
key_…), not the key itself.
Query parameters
-
projectstring optionalThe project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is
403.
Request
curl -X DELETE "https://api.sypnia.com/v1/keys/key_8b5n2m7v4c1x" \
-H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN"Errors
- 404
not_foundNo key has this id in the project.
- 409
conflictIt is the project’s last key that is not revoked. Create another first, so your app is never without one.
List API tokens
/v1/tokens EngineCloud The project’s API tokens, including revoked and expired ones. The secret is never shown again; prefix is its first 12 characters, enough to recognise it.
Query parameters
-
projectstring optionalThe project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is
403.
Request
curl "https://api.sypnia.com/v1/tokens" \
-H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN"Response200
{
"data": [
{
"id": "tok_9r4t6y2u8i1o",
"name": "Cursor",
"prefix": "sps_4Kq9Zt2M",
"scopes": [
"read",
"replay"
],
"created_at": "2026-02-02T09:18:00Z",
"last_used_at": "2026-03-12T10:34:10Z",
"expires_at": null,
"revoked_at": null
}
],
"next_cursor": null
}Create an API token
/v1/tokens EngineCloud Creates an API token for the project. The secret is in token and is shown only in this answer: the
engine stores a hash of it. Give a token the fewest scopes that do the job:
| Scope | What it allows |
|---|---|
read | Read everything except replay content. Its only writes are reversible marks: resolve or reopen a problem, acknowledge an alert, set a suggestion’s status |
replay | Fetch replays and page snapshots. They show the page as the person saw it |
admin | Everything that changes the project: keys, tokens, settings, releases and source maps, uptime checks, alert rules, webhooks, ignoring a problem, deleting data |
Scopes do not include each other: a token that should read and manage needs read and admin.
Query parameters
-
projectstring optionalThe project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is
403.
Headers
-
Idempotency-Keystring, up to 255 characters optionalA value of your own, 1 to 255 characters, that makes the call safe to repeat. See idempotency.
Body
-
namestring, up to 80 characters requiredWho or what will use it. It appears in
resolved_byand in the audit of changes. -
scopesarray of string requiredWhat the token may do. One of:
read,replay,admin. -
expires_attimestamp optionalWhen the token stops working. Leave it out for a token that does not expire.
Request
curl -X POST "https://api.sypnia.com/v1/tokens" \
-H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "Cursor", "scopes": ["read", "replay"]}'Response201
{
"id": "tok_9r4t6y2u8i1o",
"name": "Cursor",
"prefix": "sps_4Kq9Zt2M",
"token": "sps_4Kq9Zt2MxV7bN1cR5wY8pL3dF6hJ0sA2gE4uT9iO",
"scopes": [
"read",
"replay"
],
"created_at": "2026-02-02T09:18:00Z",
"last_used_at": null,
"expires_at": null,
"revoked_at": null
}Errors
- 400
invalid_requestscopesis empty or has a value other thanread,replay,admin; orexpires_atis in the past. - 409
limit_reachedThe project already has 50 tokens that are not revoked.
Revoke an API token
/v1/tokens/{token_id} EngineCloud Revokes the token. Requests with it answer 401 within one minute. A token may revoke itself.
Path parameters
-
token_idstring requiredThe token’s record id (
tok_…), not the secret.
Query parameters
-
projectstring optionalThe project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is
403.
Request
curl -X DELETE "https://api.sypnia.com/v1/tokens/tok_9r4t6y2u8i1o" \
-H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN"Errors
- 404
not_foundNo token has this id in the project.
Get usage and limits
/v1/usage EngineCloud What the project used in the current period and what its limits are. A limit of null means no limit: that is
every limit on a self-hosted engine unless you set a quota in its configuration. On Sypnia Cloud the limits
are the plan’s and the period is the calendar month, in UTC. A plan’s limits belong to the organization and
are shared by its projects: used is this project’s part, organization_used is what all its projects used
together, and the limit is reached when organization_used reaches limit.
Counters are exact and updated as data arrives. dropped_over_limit is how many events or replays were
refused because a limit was reached: Sypnia never drops silently, it counts here and tells the SDK to slow
down.
| Counter | What counts as one |
|---|---|
events | An error, a trace (one request with its spans) or a performance sample (a page view with its vitals). Clicks, custom events and replay chunks do not count |
replays | A session that has a recording |
analyses | One run of the agent on one problem. Counted per day |
pull_requests | A pull request opened by Sypnia. Sypnia Cloud only |
Query parameters
-
projectstring optionalThe project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is
403. -
periodstring optionalA month as
YYYY-MM, to read a past period. Up to 12 months back.
Request
curl "https://api.sypnia.com/v1/usage" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN"Response200
{
"project": {
"id": "prj_5k2m9x4q7w1z",
"slug": "shop",
"name": "Shop"
},
"plan": "builder",
"period": {
"start": "2026-03-01T00:00:00Z",
"end": "2026-04-01T00:00:00Z"
},
"events": {
"used": 18240,
"organization_used": 21902,
"limit": 50000,
"dropped_over_limit": 0
},
"replays": {
"used": 212,
"organization_used": 240,
"limit": 500,
"dropped_over_limit": 0
},
"analyses": {
"used_today": 4,
"limit_per_day": 100,
"used_this_period": 37
},
"pull_requests": {
"used": 6,
"organization_used": 6,
"limit": 50,
"dropped_over_limit": 0
},
"uptime_checks": {
"used": 1,
"limit": 5
},
"retention_days": {
"events": 30,
"replays": 30
},
"slow_down": null,
"daily": [
{
"day": "2026-03-11",
"events": 1610,
"replays": 19,
"analyses": 2
},
{
"day": "2026-03-12",
"events": 702,
"replays": 9,
"analyses": 4
}
]
}The errors every endpoint can answer (401, 403, 429, 500, 503) are on Errors, limits, pagination.