API overview

SpeculaPro has an HTTP API that speaks JSON. The web app uses it, and so do your systems: to ask for real-time decisions before a payment goes ahead, to send customers, accounts, transactions, FX rates and account events, to manage rules, to work alerts and cases, and to manage designations, suppressions and lists.

Integrating your systems?

Start with Sending data to SpeculaPro. It explains every field, response and error of the ingest API, with worked examples.

Full reference coming soon

The API is being built alongside the platform. A complete, generated endpoint reference will be published here once it settles. Until then, every running SpeculaPro server describes its own API exactly (see below), and that description is always correct for the version you are running.

The API describes itself

Each SpeculaPro server publishes an OpenAPI 3.1 description of every endpoint, request and response it supports:

Address	What you get
/api/openapi.json	The OpenAPI description, in JSON. Import it into Postman, Insomnia, or a code generator to build a client
/api/openapi.yaml	The same, in YAML
/api/docs	Interactive documentation in the browser: browse endpoints and try them out

These are switched on automatically in development. On other environments they are off by default; set SP_HTTP_API_DOCS=true to switch them on. See the configuration reference.

The interactive docs page needs internet access

/api/docs loads its viewer from unpkg.com. On an isolated network, download /api/openapi.json and open it with a local OpenAPI tool instead.

Basics

Base path	/api/v1 on your SpeculaPro address, for example https://speculapro.example.com/api/v1
Format	JSON request and response bodies (Content-Type: application/json)
Errors	Problem Details (application/problem+json): a JSON object with status, title and detail explaining what went wrong. See Errors
Request size	At most 1 MiB per request by default (SP_HTTP_MAX_BODY_BYTES); 8 MiB for the ingest endpoints (SP_INGEST_MAX_BODY_BYTES). Larger requests get 413
Caching	Every /api/ response carries Cache-Control: no-store, so monitoring data is never kept in shared caches
Versioning	The v1 in the path changes only for incompatible changes

Errors

Every error has the same shape:

{
  "status": 409,
  "title": "Conflict",
  "detail": "only open alerts can be closed"
}

Status	Meaning
400, 422	The request is malformed or invalid. detail (and, for 422, an errors list) says exactly what to fix. Don’t retry unchanged
401	Not signed in, or a missing or invalid API key
403	Signed in, but not allowed: a missing permission, or a four-eyes rule (for example approving your own work). On the hosted service, code: workspace_suspended means the provider has suspended the workspace, and code: support_session is a support session’s refusal
404	No such record in your workspace. Another workspace’s records always look like this
421	On a multi-region service: the workspace or API key belongs to another region (wrong_region). The answer gives the base URL to use. See Regions for integrators
409	The action doesn’t fit the record’s current state
428	The change needs a second person’s approval in this workspace and no reason was given. Send it again with an X-Change-Reason header; the answer is then 202 with a change request. See Change requests API
413	The request body is too large
503 with Retry-After	On a multi-region service, while a workspace is being moved to another region: changes are refused (decisions included), so your system needs its own fallback. See Regions for integrators
5xx	Something failed inside SpeculaPro. Try again after a short wait; for an action (closing a case, approving), first check whether it took effect. See below

When the server fails: the reference

When something goes wrong on the server’s side (a 500, 502, 503 or similar), the response never includes internal details such as database messages or file paths. Instead, detail gives you a reference:

{
  "status": 500,
  "title": "Internal Server Error",
  "detail": "Something went wrong on our side. Reference: api-7/Jx3kQpL9aB-000042"
}

The full error is written to the server’s log under that reference.

How to report it. Note the time and copy the reference exactly, everything after Reference:. Send both to your SpeculaPro support contact (on SaaS) or to your operations team (self-hosted). The reference lets them find your exact request.

How self-hosters find it. Search the logs of the processes running the api role for the reference. It appears as the req_id field on a line with the message http: internal error, together with the status, the path and the underlying error (errs):

level=ERROR msg="http: internal error" status=500 path=/api/v1/cases req_id=api-7/Jx3kQpL9aB-000042 errs=…

Bring your own request ID

If your system sends an X-Request-Id header, SpeculaPro uses that value as the reference, so the same ID appears in your logs and in SpeculaPro’s.

Authentication

There are two ways to call the API. Which one you use depends on who is calling.

Who is calling	Method
A person using the web app	A session cookie, set when they sign in
Your systems (core banking, payment switch, scripts)	An API key, sent as Authorization: Bearer spk_…

See Authentication for both, including how to create, store and revoke API keys. A signed-in request that changes something must carry Origin (browsers add it); see Requests that change something.

What is available today

Area	Status
Sign-in (password with a code or a recovery code, or a passkey), sign-out, password change, two-factor set-up, recovery codes and passkeys. See Authentication	Available
API key management (list, create, rotate, revoke)	Available
System health and version	Available
Ingestion of customers, accounts, transactions, FX rates and account events (ingest:write). See Sending data	Available (needs the ingest role running)
Rule packs and rules: install, upgrade (with a per-rule report), load signed pack files, list, draft (also with the visual builder’s field catalog), test on sample data, approve, deploy, enable, and run scheduled rules on a timetable (signed-in users). See Rules API	Available
Alerts and cases: queue, dispositions, cases (search, priority and team-queue filters and paging), escalation, team queues, evidence files, four-eyes closing, summary (signed-in users). Each alert has a kind (aml or fraud). See Alerts and cases API	Available
Customers: search and full profile, with audited access to protected fields (signed-in users). See Customers API	Available
Transactions: search the last 1 to 90 days, with the rules that hit each one (signed-in users). See Transactions API	Available
File imports: load customers or transactions from a CSV or JSON file (signed-in administrators). See Imports API	Available
Designations: add PEP, sanctions and other flags with supporting evidence, and revoke them (signed-in users). See Designations API	Available
Suppressions: propose, approve, reject with a reason, list, withdraw or end early (signed-in users), including suppressions for one counterparty. See Suppressions API	Available
Lists: create, rename, delete, add and remove values, give values an end date, see which rules use them (signed-in users). See Lists API	Available
Command center figures: today’s value, 24-hour flow, alert heatmap, rule performance, latest transactions (signed-in users). See Dashboard API	Available
Workspace settings: name, time zone, language, two-factor requirement, closure approvals, case deadlines, decision policy (signed-in administrators). See Workspace settings API	Available
Webhooks: register endpoints, read deliveries, resend, rotate signing secrets (signed-in users with webhooks.manage). See Webhooks API and Receiving webhooks	Available (deliveries need the worker role running)
Your own notification settings, including confirming a WhatsApp number (signed-in users); administrators also read the WhatsApp channel’s status and send themselves a test message. See also WhatsApp through GOWA. See Notifications	Available
Real-time decisions: ask before a payment goes ahead (decide key), report outcomes (decide or ingest:write key), and read the decision log, statistics and per-rule outcomes, and label decisions (signed-in users). See Decisions API	Available (asking needs the decision role running)
Jurisdictions: each country’s reporting format and codes, cash thresholds, identifier formats, FATF lists and recommended packs; the workspace’s own is changed in the workspace settings. See Jurisdictions API	Available
Data sources: Kafka topic mappings, SFTP / S3 file drops and change data capture sources with their mappings, their connection tests, runs, file history and results (signed-in users with datasources.manage). See Data sources API	Available (collection needs the connector role)
Data protection: retention and the purge, legal holds, data subject requests with their deadlines and exports, the registers and the breach register (signed-in users with privacy.view, privacy.manage or dsr.handle). See Privacy API	Available (the purge, scheduled erasures and reminders need the worker role)
Sanctions and PEP screening: settings, lists and versions, re-screens, on-demand screening, potential matches, providers, list imports (signed-in users with screening.view / screening.manage). See Screening API	Available (fetching and automatic screening need the worker role; reviewing potential matches needs screening.review)
Analytics figures by month: volume, typologies, rule performance, alert outcomes, decision outcomes, over up to 24 months with the analytics store and 3 without (signed-in users). See Analytics API	Available
Risk models: the registry, training, shadow, proposing a model for live, retiring, the retraining schedule, model cards and drift (signed-in users with models.view / models.manage). See Risk models API	Available (training and drift need the worker role; going live always needs a second person)
Regions on a multi-region service: which region an address is, and the workspace look-up at the global sign-in address. API keys carry their region, and a key sent to the wrong region gets 421 with the base URL to use. See Regions for integrators	Available (a single installation answers mode: single and nothing else changes)
Licence (self-hosted): state, install, signed usage report (signed-in administrators). See Licensing	Available
Approvals and custom roles: change requests (list, approve, reject, withdraw, collect a one-time secret), the approval policy, the permission catalogue, custom roles, and the audit log (signed-in users). See Change requests API	Available
Single sign-on: settings, email domains, break-glass administrators and connection tests (signed-in users with sso.manage), and the browser sign-in endpoints. See Single sign-on API	Available
SCIM 2.0 provisioning: an identity provider creates, updates and deactivates people and pushes groups, with a per-workspace bearer token. See SCIM API	Available (no bulk, sort, ETags or password changes)
AI assistant: its settings (key, provider and model), asking the service provider for more calls, asking for or reading its advice on an open alert, asking for or reading its summary of a case and suggestion, asking about many alerts or cases in a batch, asking for or reading its draft of a report’s narrative, and asking for or reading its tuning suggestions for a rule (signed-in users; asking needs cases.work and entities.view, or reports.draft and entities.view_pii for a narrative; a rule’s tuning suggestions are read with rules.view and asked for with rules.author; changing settings needs settings.manage). See AI assistant API	Available (off for every workspace until switched on)
Teams and escalation policies: who shares a case queue, and where each kind of case starts, which team takes each level and how long each level has (signed-in users; changing needs settings.manage). See Escalation API	Available
Support access and service notices (hosted service): requests from the provider’s support staff, approving, denying and revoking them, the policy, and the notices in force (signed-in users; deciding needs support_access.manage). See Support access API	Available (a self-hosted installation has no provider, so there is nothing to approve)
Provider console (hosted service): a separate API on its own listener for the provider’s staff, with no API keys. See Provider API	Available (off unless SP_PROVIDER_CONSOLE_ENABLED is set)
Backtests: replay a rule version, other parameter values or an unsaved rule over up to 180 days of history and compare it with the live version, or simulate a scheduled rule’s schedule and compare it with what the rule raised (signed-in users). See Backtesting API	Available (runs need the worker role)
Regulatory reports: the register, STRs drafted from cases, four-eyes approval, goAML XML or CENTIF declaration archive (UEMOA, Guinea) export and download, the record of submission and the FIU’s answer, and the reporting settings (signed-in users with entities.view_pii and a reporting permission). See Reports API	Available (CTR drafts need the worker role)

Health checks

These are meant for load balancers and monitoring:

Endpoint	Returns
GET /healthz	204 No Content while the process is running. No authentication
GET /readyz	204 when Postgres, Redis and Kafka are all reachable; 503 otherwise. No authentication
GET /api/v1/system/health	200 with {"status": "ok"}, or 503 with {"status": "degraded"}. No authentication; signed-in administrators also see which dependency failed

GET /api/v1/system/version returns the server’s version and commit, for signed-in users.

Tip

Point load balancer health checks at /readyz, so traffic is only sent to servers that can actually serve it. Point “is it alive?” restarts (for example a Kubernetes liveness probe) at /healthz, so a database outage doesn’t trigger a restart loop.

Ingest endpoints

Endpoint	Sends	Guide
POST /api/v1/ingest/customers	Customers, created or updated by version	Customers
POST /api/v1/ingest/accounts	Accounts, created or updated by version	Accounts
POST /api/v1/ingest/transactions	Transactions, idempotent by external_id	Transactions
POST /api/v1/ingest/fx-rates	Exchange rates into the base currency	FX rates
POST /api/v1/ingest/events	Account events: sign-ins, failed one-time codes and PINs, SIM swaps, profile changes	Account events

All five take {"items": [ … ]} with up to 500 records (a hard ceiling; more fails with 422), need an API key with ingest:write, and return a status for every record. See Responses and statuses.

Decision endpoints

Asking for a decision and reporting outcomes are for your systems, with an API key. Reading the decision log and labelling decisions are for signed-in people, and are what the Decisions screen uses. See the Decisions API for every field and error, and Calling the decision API for a step-by-step integration.

Endpoint	Does	Needs
POST /api/v1/decisions	Ask for allow, step up, review or block before a payment goes ahead	API key with decide
POST /api/v1/feedback	Report how a decided payment turned out: its final status, fraud or legitimate, and whether a step-up was passed	API key with decide or ingest:write
GET /api/v1/decisions, GET /api/v1/decisions/{id}	The decision log and one decision	alerts.view
GET /api/v1/decisions/stats	Counts and timings for the Decisions screen	alerts.view
GET /api/v1/decisions/rule-outcomes	How often each real-time rule’s decisions turned out to be fraud	rules.view
POST /api/v1/decisions/{id}/label	Label a decision as fraud or legitimate	cases.work

The first two are served by the decision role and the rest by the api role, so a load balancer in front of separate servers must route /api/v1/decisions by method as well as path. See Running roles.

Rules endpoints

Rule management is for signed-in people, not API keys: every change is attributed to a named user and checked against the four-eyes rule. Most people use the Rules screens, which call these same endpoints; see Managing rules. Fields, examples and error messages for each endpoint are in the Rules API reference.

Endpoint	Does	Permission	Success
GET /api/v1/rule-packs	List the built-in packs and which are installed	rules.view	200
POST /api/v1/rule-packs/{key}/install	Install a pack; its rules arrive disabled	rules.approve	200 {"added": n}
POST /api/v1/rule-packs/{key}/upgrade	Move an installed pack to the newest version: new rules arrive stopped, changed rules get a version awaiting approval with your tuning carried over	rules.approve	200 with a per-rule report
GET /api/v1/rules/{id}/runs	A scheduled rule’s timetable, next run and latest runs	rules.view	200
PUT /api/v1/rules/{id}/schedule	Change when a scheduled rule runs	rules.approve	204
GET /api/v1/rules/catalog	The fields, aggregates and windows the visual builder offers	rules.view	200
POST /api/v1/rules/test	Try a rule on sample data without saving it	rules.view	200
POST /api/v1/backtests	Queue a backtest	rules.backtest	202 {"id": …}
GET /api/v1/backtests, GET /api/v1/backtests/{id}	List runs; one run with progress and results	rules.view	200
POST /api/v1/backtests/{id}/cancel	Stop a queued or running run	rules.backtest	200
GET /api/v1/backtests/{id}/hits	The sample of hits	rules.backtest or alerts.view	200
GET /api/v1/rules	List rules with their active and shadow versions and 30-day hit counts	rules.view	200
GET /api/v1/rules/{id}	One rule with its full version history	rules.view	200
POST /api/v1/rules	Create a custom rule (key prefixed custom.), as draft version 1	rules.author	201 {"id": …}
POST /api/v1/rules/validate	Check a definition without saving it	rules.author	200 {"valid": …, "problems": […]}
POST /api/v1/rules/{id}/versions	Draft a new version; omitted fields are copied from the latest	rules.author	201 {"id": …}
POST /api/v1/rule-versions/{id}/submit	Send a draft for approval	rules.author	204
POST /api/v1/rule-versions/{id}/approve	Approve (never your own version)	rules.approve	204
POST /api/v1/rule-versions/{id}/reject	Reject	rules.approve	204
POST /api/v1/rules/{id}/deploy	Put an approved version in the active or shadow slot	rules.approve	204
DELETE /api/v1/rules/{id}/shadow	Stop the shadow version	rules.approve	204
POST /api/v1/rules/{id}/enable	Start running the rule	rules.approve	204
POST /api/v1/rules/{id}/disable	Stop running the rule	rules.approve	204

Errors: 422 with every validation problem listed, 403 when approving your own version or missing a permission, 404 for unknown ids or packs, 409 when the action doesn’t fit the version’s state (for example deploying a draft).

Alerts and cases endpoints

Like rules, the investigation workflow is for signed-in people: each action is attributed to a named user, checked against their permissions and the four-eyes rules, and audited.

Endpoint	Does	Permission
GET /api/v1/summary	Queue and case counts	alerts.view
GET /api/v1/alerts, GET /api/v1/alerts/{id}	The alert queue and alert details	alerts.view
POST /api/v1/alerts/{id}/close	Dismiss an open alert	cases.work
POST /api/v1/alerts/close	Dismiss up to 100 open alerts with one disposition and one reason; sanctions, critical and PEP or sanctioned-subject alerts are left open	cases.work
POST /api/v1/alerts/{id}/case	Open a case from an alert	cases.work
GET /api/v1/cases, GET /api/v1/cases/{id}	List and read cases	cases.view
POST /api/v1/cases/{id}/comments, /assign, /team, /start, /escalate	Work a case	cases.work
POST /api/v1/cases/{id}/attachments, POST /api/v1/cases/{id}/attachments/{attachment_id}/remove	Add an evidence file (the file is the request body), or remove one with a reason	cases.work
GET /api/v1/cases/{id}/attachments/{attachment_id}	Download an evidence file. Every download is audited	cases.view and entities.view
POST /api/v1/cases/{id}/close	Close, or propose closure	cases.close
POST /api/v1/cases/{id}/approve, /reject, /reopen	Second-person decisions	cases.approve

| GET /api/v1/teams, GET /api/v1/escalation-policies | Teams and their members; escalation policies in the order they are tried | cases.view, settings.view or settings.manage | | POST /api/v1/teams, PUT /api/v1/teams/{id}, DELETE /api/v1/teams/{id} | Create, change or delete a team | settings.manage | | POST /api/v1/escalation-policies, PUT /api/v1/escalation-policies/{id}, DELETE /api/v1/escalation-policies/{id} | Create, change or delete an escalation policy. May need a second person’s approval (202) | settings.manage |

See the Alerts and cases API and the Escalation API for every field, status code and example.

Webhook endpoints

Webhooks are managed by signed-in people with webhooks.manage (by default, administrators), usually under Settings → Webhooks. Each change is audited. See the Webhooks API for fields and errors, and Receiving webhooks for checking signatures on your side.

Endpoint	Does
GET /api/v1/webhooks/event-types	The events an endpoint can subscribe to
GET /api/v1/webhooks, POST /api/v1/webhooks	List endpoints, or register one (its signing secret is returned once)
PATCH /api/v1/webhooks/{id}, DELETE /api/v1/webhooks/{id}	Change, switch off or on, or delete an endpoint
POST /api/v1/webhooks/{id}/rotate-secret	Issue a new signing secret
POST /api/v1/webhooks/{id}/test	Send a test event
GET /api/v1/webhooks/{id}/deliveries, GET /api/v1/webhook-deliveries/{id}	The delivery log, and one delivery with its exact payload
POST /api/v1/webhook-deliveries/{id}/resend	Send a delivery again

Reporting endpoints

Every one needs entities.view_pii as well as the permission shown, because reports carry identity in full. See the Reports API for fields and errors, and Regulatory reporting for the workflow.

Endpoint	Does	Permission
GET /api/v1/reports, GET /api/v1/reports/counts, GET /api/v1/reports/{id}	The register, its counts, one report	Any reporting permission
POST /api/v1/cases/{id}/reports/str	Draft an STR from a case, or return the one in progress	reports.draft
PATCH /api/v1/reports/{id}, POST /api/v1/reports/{id}/request-approval	Edit a draft; send it for approval	reports.draft
POST /api/v1/reports/{id}/return, POST /api/v1/reports/{id}/approve	Send back to draft; approve (never your own)	reports.approve
POST /api/v1/reports/{id}/void	Void a report that must not be filed, with a reason	reports.approve
POST /api/v1/reports/{id}/export, GET /api/v1/reports/{id}/download	Make the report’s file once (goAML XML, or a CENTIF declaration archive); download it	reports.approve or reports.submit
GET /api/v1/reports/{id}/package	Download the filing package: a ZIP of the export as recorded, the evidence files chosen for the report and a manifest of their SHA-256	reports.approve or reports.submit
POST /api/v1/reports/{id}/submission, POST /api/v1/reports/{id}/outcome	Record that the report was filed with the FIU (the upload to goAML, for that format); record the FIU’s answer	reports.submit
GET /api/v1/settings/reporting, PUT /api/v1/settings/reporting	Read or change the reporting settings	Read: any reporting permission. Change: settings.manage or reports.approve

Jurisdiction endpoint

Endpoint	Does	Permission
GET /api/v1/jurisdictions	Jurisdiction definitions and the workspace’s current one	settings.manage or settings.view

Data source endpoints

All need datasources.manage (by default, administrators). See the Data sources API.

Endpoint	Does
GET /api/v1/data-sources/options	The kinds, formats and limits the form offers
GET /api/v1/data-sources, POST /api/v1/data-sources	List data sources, or add one
PUT /api/v1/data-sources/{id}, DELETE /api/v1/data-sources/{id}	Change (including pause and resume) or delete one
POST /api/v1/data-sources/{id}/test	Test the connection
POST /api/v1/data-sources/{id}/run	Collect now (202)
GET, PUT /api/v1/data-sources/{id}/mapping	A change data capture source’s mapping and its versions
GET /api/v1/data-sources/{id}/cdc, POST …/cdc/resync, POST …/cdc/drop-slot	Change capture status, read everything again, drop the replication slot
GET /api/v1/cdc/templates, GET /api/v1/cdc/fields, POST /api/v1/cdc/test	Example mappings, the fields a mapping can fill, and a mapping test
GET /api/v1/data-sources/{id}/files, GET /api/v1/data-source-files/{id}	File history, and one file with its per-line errors
GET /api/v1/data-source-files/{id}/results	Download a file’s results (CSV)

Data protection endpoints

All are for signed-in people. Reading needs privacy.view (requests also accept dsr.handle); changes need privacy.manage, and requests dsr.handle. See the Privacy API for fields and errors.

Endpoint	Does
GET /api/v1/privacy/reference	The law table, retention categories and choice lists
GET, PUT /api/v1/privacy/settings	Jurisdictions, hosting, DPO and registration
GET, PUT /api/v1/privacy/retention; POST /api/v1/privacy/retention/dry-run; PUT /api/v1/privacy/retention/purge; GET /api/v1/privacy/runs	Retention periods, the dry run, the purge switch and run history
GET, POST /api/v1/privacy/holds; POST /api/v1/privacy/holds/{id}/release	Legal holds
GET, POST /api/v1/privacy/requests; GET, PATCH /api/v1/privacy/requests/{id}; POST …/mlro-review, …/clock/pause, …/clock/resume, …/complete, …/erase; GET …/export	Data subject requests
/api/v1/privacy/activities, /lawful-bases, /transfers	The registers
GET, POST /api/v1/privacy/breaches; GET, PUT …/{id}; POST …/notifications/{nid}; POST, PUT …/tasks; GET …/export	The breach register

Screening endpoints

Reading needs screening.view, reviewing potential matches screening.review, and changes screening.manage. Screening one customer or counterparty on demand, and sending a name to a screening provider, also need screening.manage. See the Screening API.

Endpoint	What it does
GET, PUT /api/v1/screening/settings	What is screened, the match threshold and the lists
GET /api/v1/screening/sources, GET /api/v1/screening/sources/{key}/versions	The installation’s lists and the workspace’s own, and a list’s versions
POST /api/v1/screening/sources/{key}/import	Import a file as one of the workspace’s own lists, import:<name>
POST /api/v1/screening/bundles	Import a signed list bundle into the installation’s lists (self-hosted only; may need approval)
POST /api/v1/screening/rescreen, GET /api/v1/screening/runs	Queue a full re-screen (202); recent re-screens
POST /api/v1/screening/screen	Screen a name on demand, storing nothing; audited with a keyed fingerprint of the name. With "providers": true it needs screening.manage
POST /api/v1/screening/subjects/{type}/{id}	Screen one customer or counterparty now (screening.manage)
GET /api/v1/screening/hits, GET /api/v1/screening/hits/{id}	Potential matches
GET /api/v1/screening/hit-filters	What the queue can be filtered by, and who a match can be assigned to
POST /api/v1/screening/hits/{id}/assign, /comments, /resolve	Assign, comment on, and resolve a potential match as a true match or a false positive (may need approval)
GET, PUT /api/v1/screening/providers, DELETE /api/v1/screening/providers/{id}	Screening providers

Risk model endpoints

Reading needs models.view; everything else needs models.manage. See the Risk models API.

Endpoint	What it does
GET /api/v1/models, GET /api/v1/models/options, GET /api/v1/models/{id}	The registry, the training limits and standard features, and one version with its card, metrics and drift
POST /api/v1/models	Queue a training (202)
POST /api/v1/models/{id}/cancel, DELETE /api/v1/models/{id}	Cancel a training; delete a version that never trained
POST /api/v1/models/{id}/shadow, /unshadow	Move a draft to shadow, or back
POST /api/v1/models/{id}/promote	Propose going live: always a change request (428, then 202)
POST /api/v1/models/{id}/retire	Retire a model (the live one may need approval)
GET /api/v1/models/schedule, PUT /api/v1/models/schedule	Read or set the retraining schedule: off, weekly or monthly. It trains drafts only

Region endpoints

Public, no authentication. See Regions for integrators.

Endpoint	What it does
GET /api/v1/cell	What this address is: single, one region (cell) with its key, name and addresses, or the global sign-in address (directory)
POST /api/v1/directory/resolve	At the global sign-in address only: the region a workspace slug signs in at. Rate-limited; an unknown slug gets an answer of the same shape

Licence and signed pack endpoints

Endpoint	Does	Permission
GET /api/v1/license	The licence state, limits, usage and installation fingerprint	settings.manage
PUT /api/v1/license	Install a licence: {"license": "<file contents>"}. 422 if it isn’t valid, 409 on SaaS	settings.manage
GET /api/v1/license/usage-report?from=YYYY-MM&to=YYYY-MM	Download a signed usage report	settings.manage
POST /api/v1/rule-packs/bundles	Import a signed rule-pack bundle: {"bundle": "…", "force": false}. 409 on a conflict or downgrade, 403 while the licence has lapsed	rules.approve; force also needs settings.manage

Approval endpoints

When your workspace requires approval for a change, the endpoint that makes it answers 428 without an X-Change-Reason header, and 202 Sent for approval with one; the change applies when someone else approves it. See the Change requests API for which endpoints are gated.

Endpoint	Does	Permission
GET /api/v1/change-requests, GET /api/v1/change-requests/{id}	List requests (view=inbox, mine or all); one request with its before and after	Any signed-in person; you see what you may
GET /api/v1/change-requests/counts	How many wait for you, and how many of yours wait	Any signed-in person
POST /api/v1/change-requests/{id}/approve, /reject	Decide someone else’s request	The kind’s ….approve permission
POST /api/v1/change-requests/{id}/withdraw, /secret	Withdraw your own; collect its one-time secret once applied	The maker
GET /api/v1/approvals/policy, PUT /api/v1/approvals/policy	Which changes need approval	Read: anyone. Change: settings.manage
GET /api/v1/permissions	Every permission, in plain language	Any signed-in person
GET /api/v1/roles; POST /api/v1/roles; PUT, DELETE /api/v1/roles/{key}	Roles; create, change or delete a custom role	Read: users.manage or settings.view. Change: users.manage
GET /api/v1/audit	The audit log, newest first	audit.view

Single sign-on settings

Changes need sso.manage (by default, administrators); settings.view can read. See the Single sign-on API for fields, errors and the browser sign-in endpoints.

Endpoint	Does
GET /api/v1/settings/sso, PUT /api/v1/settings/sso	Read or change the connection, group mapping, multi-factor rules and enforcement
POST /api/v1/settings/sso/metadata/refresh	Fetch the SAML identity provider’s metadata again
POST /api/v1/settings/sso/domains, POST /api/v1/settings/sso/domains/{id}/verify, DELETE /api/v1/settings/sso/domains/{id}	Claim, verify or remove an email domain
PUT /api/v1/settings/sso/break-glass	Choose the break-glass administrators
POST /api/v1/settings/sso/test, GET /api/v1/settings/sso/test/{id}	Start a connection test and read its result
GET /api/v1/settings/sso/scim, POST /api/v1/settings/sso/scim/tokens, DELETE /api/v1/settings/sso/scim/tokens/{id}, PUT /api/v1/settings/sso/scim/privileged-roles	SCIM provisioning: the base URL, creating (shown once; may need approval) and revoking its tokens, and whether SCIM may give privileged roles. See the SCIM API
GET, POST /api/v1/auth/sso/saml/{workspace}/slo	The SAML single logout URL, called by the identity provider; no session needed

SCIM endpoints

Called by your identity provider with a SCIM bearer token, not a session or an API key. See the SCIM API.

Endpoint	What it does
GET /scim/v2/ServiceProviderConfig, /ResourceTypes, /Schemas	What is supported
GET, POST /scim/v2/Users; GET, PUT, PATCH, DELETE /scim/v2/Users/{id}	List, create, read, change and deactivate people. DELETE deactivates; nobody is deleted
GET, POST /scim/v2/Groups; GET, PUT, PATCH, DELETE /scim/v2/Groups/{id}	The groups whose names give roles through the single sign-on group mapping

Support access and service notices

On the hosted service. See the Support access API.

Endpoint	Does	Permission
GET /api/v1/settings/support-access	Requests from the provider’s support staff, the access running now, the history and the policy	support_access.manage, settings.manage or settings.view
POST /api/v1/settings/support-access/{id}/approve, …/deny, …/revoke	Approve or deny a waiting request, or end a running access at once	support_access.manage
GET /api/v1/settings/support-access/policy, PUT /api/v1/settings/support-access/policy	Read or replace the policy. Loosening it may need a second person’s approval (202)	As the first row to read; support_access.manage to change
GET /api/v1/notices	Service notices in force for this workspace	Any signed-in person

The provider’s own staff use a separate API, on its own listener and with no API keys: see the Provider API.

Dashboard and notification settings

Endpoint	Does	Permission
GET /api/v1/dashboard	The Command center’s figures	alerts.view
GET /api/v1/analytics/volume, /typologies, /rules, /alerts, /decisions	The Analytics page’s month-by-month figures (?months=1..24). See the Analytics API	alerts.view
GET /api/v1/me/notifications, PUT /api/v1/me/notifications	Read or change your own email, SMS and WhatsApp settings	Any signed-in person
POST /api/v1/me/notifications/whatsapp/code, POST /api/v1/me/notifications/whatsapp/verify, DELETE /api/v1/me/notifications/whatsapp	Confirm your WhatsApp number with a code, or remove it	Any signed-in person
GET /api/v1/settings/notifications/whatsapp, POST /api/v1/settings/notifications/whatsapp/test	The WhatsApp channel’s status; a test message to yourself	settings.manage

See the Dashboard API and Notifications.

Related

• Alerts and cases API
• Rules API
• Dashboard API
• Decisions API
• Webhooks API
• Privacy API
• Change requests API
• Managing rules
• Sending data to SpeculaPro
• Authentication
• Configuration reference
• Architecture: ingestion