Loading the interactive API reference…

SigWise API reference

Send events about your objects, get typed answers back. Version 1.0.0. Also available as Markdown and as an OpenAPI 3.1 specification in JSON or YAML.

Objects

An object is anything you want answers about: a user, a listing, an order. It is identified by your own `object_id` and exists as soon as you send its first event.

GET /v1/overview Get tenant overview: Tenant-wide totals and per-signal value distributions, computed with SQL aggregates.
POST /v1/analyze Re-analyze every object: Schedules a re-analysis of every object the tenant has, typically after changing signal configuration. Jobs run at bulk priority, behind live traffic. Each analysis is billed.
GET /v1/objects List objects: Returns one page of objects with their latest analysis.
GET /v1/objects/{object_id} Get an object's analysis: Returns the latest answer for each signal computed for the object, plus the configured signals that have no answer yet (`pending`).
GET /v1/objects/{object_id}/state Get an object's compacted history: Older events are folded into a rolling summary so the analyzer gets a bounded payload while keeping long-term signal. This returns that summary and the compaction cursor.
POST /v1/objects/{object_id}/analyze Re-analyze an object: Schedules an immediate re-analysis without a new event, for example right after adding a signal. Runs at live priority; poll `GET /v1/objects/{object_id}` for the result. Returns `404` when the object has no events.

Events

Events and messages are the evidence an object's answers are computed from. Ingestion is asynchronous by default and returns `202`; set `wait: true` to score the object inline instead (direct moderation).

GET /v1/objects/{object_id}/events List an object's events: Returns up to the 200 most recent events and messages recorded for the object, newest first.
POST /v1/objects/{object_id}/events Ingest events: Records one or more events or messages about an object.
POST /v1/objects/{object_id}/ingest Ingest events (alias): An alias of `POST /v1/objects/{object_id}/events`. Use that path instead.

Signals

A signal is a question you ask about every object, such as "is this a scammer?" (`noul`), "how trustworthy is this user?" (`score`) or "what is their buyer intent?" (`choice`).

GET /v1/signals List signals
PUT /v1/signals/{key} Create or update a signal: Creates the signal, or replaces its definition. `instructions` and `criteria` are passed to the analyzer verbatim; the shape of `criteria` depends on `type`:
DELETE /v1/signals/{key} Delete a signal
GET /v1/signals/{key}/backfill Get backfill estimate and progress: Returns how many existing objects have no answer for the signal and what analyzing them would cost now, plus the progress of the most recent backfill (`null` if none was started).
POST /v1/signals/{key}/backfill Start a backfill: Re-analyzes, for this signal only, every existing object that has no answer for it. Jobs run at bulk priority so they never delay live ingest. Each analysis is billed. Returns `409` if the signal is disabled.

Webhooks

Webhook endpoints receive a signed `POST` for the event types they subscribe to: `analysis.completed` each time an analysis completes, and `rule.triggered` when a rule with a webhook action fires. Deliveries retry with backoff and land in a dead-letter queue you can replay.

GET /v1/webhooks List webhook endpoints
POST /v1/webhooks Register a webhook endpoint: Registers an endpoint and returns its signing secret. **The secret is shown only once**; store it to verify deliveries.
GET /v1/webhooks/{endpoint_id} Get a webhook endpoint
PATCH /v1/webhooks/{endpoint_id} Update a webhook endpoint: Omitted fields are left unchanged.
DELETE /v1/webhooks/{endpoint_id} Delete a webhook endpoint: Removes the endpoint and its deliveries.
GET /v1/webhook_deliveries List webhook deliveries: Recent deliveries, newest first. Filter with `status=dead` to inspect the dead-letter queue.
POST /v1/webhook_deliveries/{delivery_id}/replay Replay a delivery: Re-queues a delivery (for example one in the dead-letter queue) for another attempt.

Rules

A rule fires an action (email, Slack or webhook) when an object's signal values cross a line you care about, such as `is_scammer >= 90`.

GET /v1/rules List rules
POST /v1/rules Create a rule: The condition is validated against the tenant's signals, and a `webhook` action must reference a registered endpoint subscribed to `rule.triggered`.
GET /v1/rules/{rule_id} Get a rule
PATCH /v1/rules/{rule_id} Update a rule: Omitted fields are left unchanged. The resulting condition and action are re-validated.
DELETE /v1/rules/{rule_id} Delete a rule
GET /v1/rule_firings List rule firings: The audit log of rule firings and their action outcomes, newest first.

API keys

Create, rotate and revoke the keys your integrations sign requests with.

GET /v1/api_keys List API keys: Revoked keys are not listed. Secrets are never returned.
POST /v1/api_keys Create an API key: Mints a key ID and signing secret. **The secret is shown only once.**
PATCH /v1/api_keys/{key_id} Update an API key: Rename a key, or deactivate and reactivate it. Use `DELETE` to revoke.
DELETE /v1/api_keys/{key_id} Revoke an API key: The key stops authenticating immediately. Its ID is never reissued.
POST /v1/api_keys/{key_id}/rotate Rotate an API key's secret: Keeps the key ID and replaces the secret. The old secret stops working immediately; the new one is returned only once.

Billing

Prepaid balance, the billing ledger, and card top-ups.

GET /v1/billing Get the prepaid balance
GET /v1/billing/ledger List ledger entries: One page of the billing ledger, newest first. Pass the previous page's `next_cursor` as `cursor` to continue; it is empty on the last page.
POST /v1/billing/checkout Start a card top-up: Creates a hosted Stripe Checkout Session for the amount and returns its URL. The balance is credited only once Stripe confirms the payment. Returns `503` when card payments are not configured.
GET /v1/billing/checkout/{session_id} Get a top-up's status: Whether the Checkout Session's payment has been credited to the balance yet.

Usage

Analysis volume, spend and token usage over a date range.

GET /v1/usage Get usage: Analyses, spend and tokens over an inclusive UTC date range (at most 366 days), with a zero-filled daily series and breakdowns by model, source (`async` / `sync`) and signal. Defaults to the last 30 days.

Account

The authenticated principal and tenant settings.

GET /v1/me Get the current principal: Returns the tenant the credential belongs to. For console tokens it also returns the signed-in user and whether they finished onboarding.
GET /v1/settings Get tenant settings
PATCH /v1/settings Update tenant settings: Omitted fields are left unchanged.

Console

Endpoints used by the SigWise console for human sign-in and account management. They authenticate with a console token, not an API key, and are not part of the SDKs.

POST /auth/console/register Sign up: Self-service signup: provisions a new tenant and its first admin user, then signs in. New tenants get the signup credit and the default signals. Returns `403` when the deployment disables registration.
POST /auth/console/login Sign in: Verifies an email and password and returns a console token.
POST /auth/token Exchange a legacy key for a token: **Deprecated.** Exchanges a legacy API key and secret for a short-lived tenant token. Integrations now sign each request themselves; this path is kept for one release and logs a warning on every use.
POST /auth/console/password/forgot Request a password reset: Emails a single-use reset link valid for one hour. It answers `202` with the same body whether or not the email has an account, and is throttled per client IP and per email.
POST /auth/console/password/reset Reset a password: Sets a new password with a reset token. Every existing session is signed out.
GET /auth/console/oauth/providers List social sign-in providers
POST /auth/console/oauth/{provider}/authorize Get a provider authorization URL: Returns the provider's authorization URL for a `state` and a PKCE S256 `code_challenge`.
POST /auth/console/oauth/{provider} Sign in with a provider: Completes a social sign-in: exchanges the authorization code and PKCE verifier, then signs in the linked user, links a verified email to an existing user, or signs up a new tenant (`201`, `new_user: true`).
POST /v1/me/onboarded Mark onboarding complete
POST /v1/me/password Change password: Changes the signed-in user's password, signs out every other session, and returns a new console token.
GET /v1/me/mfa Get two-factor status: Whether two-factor authentication is on for the signed-in user, and how many recovery codes are left.
POST /v1/me/mfa/setup Start two-factor setup: Issues a new secret to add to an authenticator app. Two-factor stays off until `POST /v1/me/mfa/enable` confirms a code from it. Calling this again before enabling replaces the secret. Returns `409` when two-factor is already on.
POST /v1/me/mfa/enable Turn on two-factor: Confirms the secret from setup with a current code and turns two-factor on. Returns eight single-use recovery codes, **once**; each signs in once if the authenticator is lost.
POST /v1/me/mfa/disable Turn off two-factor: Needs the account password (when it has one) and a current code or an unused recovery code, so a stolen session alone can't remove it.
GET /v1/me/identities List sign-in methods
POST /v1/me/identities/{provider} Link a provider account
DELETE /v1/me/identities/{provider} Unlink a provider account: Refused with `409` when it is the user's last sign-in method.
GET /v1/me/notifications Get email preferences
PUT /v1/me/notifications Update email preferences: Maps an email event to whether the user wants it, e.g. `{"low_balance": false}`. Events left out keep their setting. Critical emails can't be turned off.

System

Health checks and this specification.

GET /healthz Liveness: Returns `200` as long as the process is serving. It does not check dependencies.
GET /metrics Prometheus metrics: Operational metrics in the Prometheus text format: request rates and latency by route, analysis outcomes, analyzer latency and throttling, queue depth and lag, and running jobs per tenant. For the operator of a deployment, not for integrations.
GET /readyz Readiness: Returns `200` only when the database is reachable, so load balancers stop routing traffic during an outage.
GET /openapi.yaml OpenAPI specification (YAML): This document, as served by the API you are talking to.
GET /openapi.json OpenAPI specification (JSON): This document as JSON.
POST /webhooks/stripe Stripe events: Receives Stripe events, verified against the `Stripe-Signature` header. A paid top-up Checkout Session is credited to the tenant exactly once. Called by Stripe, not by integrations.