/health, authenticated:
This API is served by
webhook.coinversa.ai, not the data API at api.coinversa.ai. It takes Authorization: Bearer, not X-API-Key, and it is not in the data API’s OpenAPI spec. REST auth failures are 403 on the data API; here a missing or invalid key is 401.Authentication
One header, the same key as REST and the WebSocket:401. An auth-backend outage is 503, never anonymous access — treat a 503 as temporarily unavailable and retry, not as a bad key.
Summary
Every authenticated row takes the Bearer header above.Definitions
GET /v1/subscriptions/definitions → { "types": [...], "filterLogic": "and" }.
Only the types permitted by your tier are listed, so Free sees the Free-tier types even though its subscription allowance is zero: feed access and subscription allowance are separate checks. The same declarations drive validation and event field extraction — this is not an arbitrary query interface. Each type carries:
minItems and maxItems on user mean it accepts one address or an array of 1 to 1,000 (one wallet or many). Read the endpoint rather than maintaining a client-side list.
Create a subscription
POST /v1/subscriptions
args selects and configures the source independently of the optional filters. The original top-level user spelling is still accepted, but do not send user both at the top level and inside args.
One wallet or many
On the four by-user typesargs.user is one address string or an array of 1 to 1,000 addresses; the definitions advertise minItems: 1 and maxItems: 1000 on the argument. The top-level user spelling accepts either form too.
- One array is one subscription against your allowance and one underlying processor feed; it does not change the type’s minimum plan.
- Addresses are lowercased; arrays are sorted and deduplicated. The 1,000 limit is checked before deduplication.
- An empty array, an invalid address or more than 1,000 entries is a
400. Creation bodies are limited to 64 KiB. - In create and list responses a one-element array — including one left after deduplication — is returned as a string; the legacy top-level
userappears only for a single-wallet scope. - Matching events from every listed wallet in a source block arrive together, in source order, in one delivery’s
data, with the same filters applied to each. Non-wallet arguments stay single-valued.
Cohort bias types
The four cohort bias types takecoin and, depending on the type, a cohort, a second cohort, a direction or a number of points. One body per type, with every required argument:
coinis required on all four, matched case-insensitively, and can be a qualified symbol such asxyz:GOLD.tierTypeis optional on all four:pnl(default),size,pnl_recentorsize_recent. AcohortorotherCohortmust belong to that classification — a cohort from the other one is a400— andcohortBiasOppositionneeds two different cohorts.directiononcohortBiasFlipislong,shortorboth(default): the side the cohort flips to.pointsoncohortBiasMoveis a positive decimal string, at most200: percentage points of net bias.cohortBias,cohortBiasFlipandcohortBiasMoveaccept thenetBias,longNotional,shortNotionalandaccountCountfilters;cohortBiasOppositionaccepts none.
Liquidation risk types
The four liquidation risk types take either one wallet or one market, and a threshold. One body per type, with every required argument:useronliquidationRiskCrossandliquidationRiskis exactly one wallet — a string or a one-element array. A second address is a400. There is nocoinargument: every open position on record for the wallet is checked.liquidationDistancePctonliquidationRiskCrossis a positive decimal string in percent ("5"is 5%);directionisabove,beloworboth(default), andbelowis closer to liquidation.pointsonliquidationRiskis a positive decimal string — percentage points of distance, with no upper limit. It is the one type of the four that takes a filter:liquidationDistancePct.coinonliquidationExposureandliquidationMapis matched case-insensitively and can be a qualified symbol such asxyz:GOLD.priceMovePctonliquidationExposureis a decimal string above0and at most100;minNotionalis a positive decimal string in quote units.directionisdown,uporboth(default).resetNotionalis optional, positive and at mostminNotional, and defaults to it.priceChangePctonliquidationMapis a positive decimal string.bucketsandrangeare optional integer strings:"1"to"200"(default"50") and"1"to"100"(default"30").
type, the normalised args, the saved filters, its id, deliveryMode, url and disabled status — and, on creation of an http subscription only, the whsec_… signing secret. List responses never include it; read it later with GET /v1/subscriptions/{id}/secret.
Inbox delivery
Send"deliveryMode": "inbox" and no url, and matching frames are stored in your account’s one inbox instead of being POSTed — the same types, args and filters, one of the same subscription slots, no signing secret, and 403 on Free. Read them with the three inbox routes below. The full contract is on Inbox delivery.
priceCross crossing state and a cohort bias or liquidation risk subscription’s state. If activating the underlying feed fails, creation rolls back and answers 503 rather than leaving a saved subscription behind.
Errors: 400 (invalid format, unknown type, argument, filter or operator, impossible range, an empty or over-1,000 user array or an invalid address in it, a cohort outside the chosen tierType, points outside its range, more than one wallet on a liquidation risk type, priceMovePct above 100, resetNotional above minNotional, buckets or range that is not an integer string in its range, a body over 64 KiB — checked before anything is saved), 403 (the type is not permitted by your tier, or an inbox subscription on Free), 429 (your account is at its subscription allowance), 503 (auth, storage or feed unavailable).
Tier checks are creation-time checks, not continuous re-authorisation of saved subscriptions after an account change.
List subscriptions
GET /v1/subscriptions → this account’s subscriptions, each with its type, args, filters, id, deliveryMode ("http" or "inbox"), url (HTTP subscriptions) and disabled status. No secrets.
Delete a subscription
DELETE /v1/subscriptions/{id} deletes one subscription you own. For priceCross, the cohort bias types and the liquidation risk types it also removes the stored baseline or state and any pending deliveries in the outbox. Deleting an inbox subscription stops collection but does not delete the messages it already stored — acknowledge those on the inbox.
Delete all subscriptions
DELETE /v1/subscriptions deletes every subscription on the account.
Re-enable a subscription
POST /v1/subscriptions/{id}/enable re-enables a subscription that a 410 from your URL disabled. It is idempotent. It answers 429 if the account is already at its subscription allowance — a disabled subscription does not count toward it, so enabling one is a creation-time check again.
Read the signing secret
GET /v1/subscriptions/{id}/secret returns the subscription’s whsec_… signing secret — the one returned at creation. There is one secret per subscription and no rotation; see Signatures and delivery. An inbox subscription has no secret, and this route answers 400 for it.
Inbox
Three routes read the account’s one inbox; the semantics are on Inbox delivery.
A message is the delivery envelope plus
inboxId (msg_ + 32 hex) and receivedAt (the message).
Health
GET /health needs no key and answers 200 while the service is up. The body is a JSON object of counts — subscriptions (saved subscriptions), feeds (active feed subscriptions), queued (fresh deliveries waiting), retrying (retries waiting) and outbox (pending outbox rows). Treat the status code as the health signal and the body as informative: a build may answer 200 with an empty body, so accept both. It does not check auth or feed readiness.
Delivery semantics
What a delivery looks like is on Signatures and delivery. The status codes your URL returns mean:Errors
Error bodies are plain text, not JSON —
Unauthorized, unknown webhook type, endpoint must be a public HTTPS URL, invalid subscription JSON, filter "sz" has an impossible range — so match on the status code and show the text. The tentative subscription allowances per plan are on Plan limits.
