API reference
Generated from the OpenAPI description of the API. Every route, its parameters, answers and error codes.
Authentication: apiKey: API key in the Authorization header, as Bearer.
Account
The account, the plan, usage and coins.
GET /v1/account
The account, the plan and the calling key.
Responses
| Status | Description | Error codes |
|---|---|---|
200 | The account, the plan and the calling key. | |
503 | The channel is closed for this account, or the private beta does not include the account. | See the list |
Also 400, 401, 402, 403, 429 and 500, as in common answers.
GET /v1/usage
Calls, previews, notes and the credit balance for this month and today.
Responses
| Status | Description | Error codes |
|---|---|---|
200 | Calls, previews, notes and the credit balance for this month and today. | |
503 | The channel is closed for this account, or the private beta does not include the account. | See the list |
Also 400, 401, 402, 403, 429 and 500, as in common answers.
GET /v1/assets
Coins the feed covers. No prices.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
query | query | string | No | 1 to 40 characters. Omit it for every active coin, up to 500. With it, up to 5 matches. |
Responses
| Status | Description | Error codes |
|---|---|---|
200 | Coins the feed covers. No prices. | |
400 | query must be 1 to 40 characters when you send it. | See the list |
503 | The channel is closed for this account, or the private beta does not include the account. | See the list |
Also 401, 402, 403, 429 and 500, as in common answers.
Rules
Rules, a preview of a condition, and the record of what the price did later.
GET /v1/rules
Every rule that is not archived, oldest first.
Responses
| Status | Description | Error codes |
|---|---|---|
200 | Every rule that is not archived, oldest first. | |
503 | The channel is closed for this account, or the private beta does not include the account. | See the list |
Also 400, 401, 402, 403, 429 and 500, as in common answers.
POST /v1/rules
Create a rule. The coin is added to the watchlist.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | Yes | Required. 1 to 255 printable ASCII characters. The same value and the same request returns the stored answer and does not run the work again. |
Request body (required)
The rule to create.
| Name | Type | Required | Description |
|---|---|---|---|
kind | string: price_above, price_below, percent_change, volume_spike, unusual_move | Yes | |
scope | string: symbol, watchlist | No | Default symbol. watchlist is for percent, volume and unusual kinds. |
symbol | string or null | No | An active coin. Required for symbol scope. Absent or null for a watchlist. |
condition | object, see the schema | Yes | Public condition names for the rule's kind. Defaults fill optional fields. Read-only extras are refused. |
cooldown_seconds | integer: 900, 1800, 3600, 14400, 43200, 86400, 604800 | No | Default 3600, or 14400 for unusual_move. |
note_mode | string: auto, on_request, off | No | Default auto. |
destination_ids | array of integer or null | No | Null, the default, sends to every active destination except bot webhooks. |
name | string | No |
Responses
| Status | Description | Error codes |
|---|---|---|
201 | Create a rule. The coin is added to the watchlist. | |
400 | A field is wrong, a read-only condition extra was sent, or Idempotency-Key is missing or not printable ASCII. | See the list |
402 | The plan's active rules are full (limit rules), the coin would pass the watchlist limit (limit coins), or a block of calls cannot be paid. | See the list |
409 | The same condition already exists (reason duplicate_rule, with rule_id), this Idempotency-Key was used for a different request (idempotency_key_reused), or the first request is still running (in_progress). | See the list |
429 | The key, the account, or the account's rule changes (60 a minute) are over the limit. | See the list |
503 | The channel is closed for this account, or the private beta does not include the account. | See the list |
Also 401, 403 and 500, as in common answers.
GET /v1/rules/{id}
One rule.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | A positive integer below 2^31. Anything else, or another account's id, is not found. |
Responses
| Status | Description | Error codes |
|---|---|---|
200 | One rule. | |
404 | No rule with that id belongs to this account. | See the list |
503 | The channel is closed for this account, or the private beta does not include the account. | See the list |
Also 400, 401, 402, 403, 429 and 500, as in common answers.
PATCH /v1/rules/{id}
Change a rule. A new condition, kind, scope or coin clears its state.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | A positive integer below 2^31. Anything else, or another account's id, is not found. |
Idempotency-Key | header | string | No | Optional. When you send it, 1 to 255 printable ASCII characters. The same value and the same request returns the stored answer. |
Request body (required)
Fields to change.
| Name | Type | Required | Description |
|---|---|---|---|
kind | string: price_above, price_below, percent_change, volume_spike, unusual_move | No | |
scope | string: symbol, watchlist | No | Default symbol. watchlist is for percent, volume and unusual kinds. |
symbol | string or null | No | An active coin. Required for symbol scope. Absent or null for a watchlist. |
condition | object, see the schema | No | Public condition names for the rule's kind. Defaults fill optional fields. Read-only extras are refused. |
cooldown_seconds | integer: 900, 1800, 3600, 14400, 43200, 86400, 604800 | No | Default 3600, or 14400 for unusual_move. |
note_mode | string: auto, on_request, off | No | Default auto. |
destination_ids | array of integer or null | No | Null, the default, sends to every active destination except bot webhooks. |
name | string | No |
Responses
| Status | Description | Error codes |
|---|---|---|
200 | Change a rule. A new condition, kind, scope or coin clears its state. | |
400 | A field is wrong, or the body is empty. | See the list |
402 | The plan's active rules are full, the coin would pass the watchlist limit, or a block of calls cannot be paid. | See the list |
404 | No rule with that id belongs to this account. | See the list |
409 | duplicate_rule, idempotency_key_reused, in_progress, use_subscription (change the subscription instead), or rule_backs_service (the rule backs a service). | See the list |
429 | The key, the account, or the account's rule changes (60 a minute) are over the limit. | See the list |
503 | The channel is closed for this account, or the private beta does not include the account. | See the list |
Also 401, 403 and 500, as in common answers.
DELETE /v1/rules/{id}
Delete a rule. Its alerts stay for the record, and leave this account's feed.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | A positive integer below 2^31. Anything else, or another account's id, is not found. |
Idempotency-Key | header | string | No | Optional. When you send it, 1 to 255 printable ASCII characters. The same value and the same request returns the stored answer. |
Responses
| Status | Description | Error codes |
|---|---|---|
200 | Delete a rule. Its alerts stay for the record, and leave this account's feed. | |
404 | No rule with that id belongs to this account. | See the list |
409 | idempotency_key_reused, in_progress, use_subscription, or rule_backs_service. | See the list |
429 | The key, the account, or the account's rule changes (60 a minute) are over the limit. | See the list |
503 | The channel is closed for this account, or the private beta does not include the account. | See the list |
Also 400, 401, 402, 403 and 500, as in common answers.
POST /v1/rules/{id}/pause
Pause a rule. Pausing a paused rule leaves it paused.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | A positive integer below 2^31. Anything else, or another account's id, is not found. |
Idempotency-Key | header | string | Yes | Required. 1 to 255 printable ASCII characters. The same value and the same request returns the stored answer and does not run the work again. |
Request body
Empty object, or no body.
An empty JSON object.
Responses
| Status | Description | Error codes |
|---|---|---|
200 | Pause a rule. Pausing a paused rule leaves it paused. | |
404 | No rule with that id belongs to this account. | See the list |
409 | idempotency_key_reused, in_progress, use_subscription, or rule_backs_service. | See the list |
429 | The key, the account, or the account's rule changes (60 a minute) are over the limit. | See the list |
503 | The channel is closed for this account, or the private beta does not include the account. | See the list |
Also 400, 401, 402, 403 and 500, as in common answers.
POST /v1/rules/{id}/resume
Resume a rule. active_since becomes now when it was paused.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | A positive integer below 2^31. Anything else, or another account's id, is not found. |
Idempotency-Key | header | string | Yes | Required. 1 to 255 printable ASCII characters. The same value and the same request returns the stored answer and does not run the work again. |
Request body
Empty object, or no body.
An empty JSON object.
Responses
| Status | Description | Error codes |
|---|---|---|
200 | Resume a rule. active_since becomes now when it was paused. | |
402 | The plan's active rules are full (limit rules), or a block of calls cannot be paid. | See the list |
404 | No rule with that id belongs to this account. | See the list |
409 | idempotency_key_reused, in_progress, use_subscription, or rule_backs_service. | See the list |
429 | The key, the account, or the account's rule changes (60 a minute) are over the limit. | See the list |
503 | The channel is closed for this account, or the private beta does not include the account. | See the list |
Also 400, 401, 403 and 500, as in common answers.
POST /v1/rules/preview
How often a condition would have been met over the last 30 days. Nothing is saved.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | Yes | Required. 1 to 255 printable ASCII characters. The same value and the same request returns the stored answer and does not run the work again. |
Request body (required)
The condition to preview.
| Name | Type | Required | Description |
|---|---|---|---|
kind | string: price_above, price_below, percent_change, volume_spike, unusual_move | Yes | |
scope | string: symbol, watchlist | No | Default symbol. watchlist is for percent, volume and unusual kinds. |
symbol | string or null | No | An active coin. Required for symbol scope. Absent or null for a watchlist. |
condition | object, see the schema | Yes | Public condition names for the rule's kind. Defaults fill optional fields. Read-only extras are refused. |
cooldown_seconds | integer: 900, 1800, 3600, 14400, 43200, 86400, 604800 | No | Default 3600, or 14400 for unusual_move. |
Responses
| Status | Description | Error codes |
|---|---|---|
200 | How often a condition would have been met over the last 30 days. Nothing is saved. | |
400 | A field is wrong, or Idempotency-Key is missing or not printable ASCII. | See the list |
402 | The day's previews are used and the charge is refused (credits_required or quota_exceeded), or a block of calls cannot be paid. | See the list |
409 | idempotency_key_reused or in_progress. A key that already paid stays used. | See the list |
429 | The key, the account, or the preview limit (reason previews, Retry-After 5). The preview queue uses the same reason. | See the list |
503 | The channel is closed for this account, or the private beta does not include the account. | See the list |
Also 401, 403 and 500, as in common answers.
GET /v1/rules/{id}/record
What the price did after each alert of one rule.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | A positive integer below 2^31. Anything else, or another account's id, is not found. |
limit | query | integer | No | Most alerts in one page. |
before | query | integer | No | An alert id. The page holds alerts with a lower id. |
Responses
| Status | Description | Error codes |
|---|---|---|
200 | What the price did after each alert of one rule. | |
400 | limit must be 1 to 200, and before must be an alert id. | See the list |
404 | No rule with that id belongs to this account. | See the list |
503 | The channel is closed for this account, or the private beta does not include the account. | See the list |
Also 401, 402, 403, 429 and 500, as in common answers.
Events
Alerts as they are recorded, one alert, and a measured note for a coin.
GET /v1/events
The account's alerts in the order they were recorded.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
cursor | query | string | No | A next_cursor from an earlier answer. Read events after that point. |
start | query | string: latest, earliest | No | Used only when cursor is omitted. latest reads alerts recorded from now on. earliest reads from the oldest alert kept, 7 days back. |
wait | query | integer | No | Seconds to keep the request open when no event is ready. |
limit | query | integer | No | Most events in one answer. |
rule_id | query | integer | No | Only this rule's events. The cursor still moves past the account's other alerts. |
Responses
| Status | Description | Error codes |
|---|---|---|
200 | The account's alerts in the order they were recorded. | |
400 | A query parameter is wrong. cursor must be a cursor this API issued. | See the list |
402 | The answer had events, and a block of calls cannot be paid. The cursor does not move. | See the list |
404 | rule_id is not a rule of this account. | See the list |
429 | The key or the account is over its calls per minute, the key has too many open long-polls (reason long_polls), or this process is full (reason server_busy). | See the list |
503 | The channel is closed for this account, or the private beta does not include the account. | See the list |
Also 401, 403 and 500, as in common answers.
GET /v1/alerts/{id}
One alert, including alerts the person's own channels held, inside the plan's history.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | A positive integer below 2^31. Anything else, or another account's id, is not found. |
Responses
| Status | Description | Error codes |
|---|---|---|
200 | One alert, including alerts the person's own channels held, inside the plan's history. | |
404 | No alert with that id belongs to this account, or it is older than the plan's history. | See the list |
503 | The channel is closed for this account, or the private beta does not include the account. | See the list |
Also 400, 401, 402, 403, 429 and 500, as in common answers.
POST /v1/explain
A measured note for one coin over one window. Facts are returned even when a note cannot be written.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | Yes | Required. 1 to 255 printable ASCII characters. The same value and the same request returns the stored answer and does not run the work again. |
Request body (required)
The coin and the window.
| Name | Type | Required | Description |
|---|---|---|---|
symbol | string | Yes | An active coin. |
window | string: 15m, 1h, 4h, 24h | Yes |
Responses
| Status | Description | Error codes |
|---|---|---|
200 | A measured note for one coin over one window. Facts are returned even when a note cannot be written. | |
400 | symbol or window is wrong, or Idempotency-Key is missing or not printable ASCII. | See the list |
402 | A block of calls cannot be paid. The note's own charge never answers 402: the facts come back instead. | See the list |
409 | idempotency_key_reused or in_progress. | See the list |
503 | The channel is closed for this account, or the private beta does not include the account. | See the list |
Also 401, 403, 429 and 500, as in common answers.
Destinations
Where alerts are sent, including webhooks your software receives.
GET /v1/destinations
Every destination, oldest first.
Responses
| Status | Description | Error codes |
|---|---|---|
200 | Every destination, oldest first. | |
503 | The channel is closed for this account, or the private beta does not include the account. | See the list |
Also 400, 401, 402, 403, 429 and 500, as in common answers.
POST /v1/destinations
Add a webhook destination. The signing secret is in this answer only.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | Yes | Required. 1 to 255 printable ASCII characters. The same value and the same request returns the stored answer and does not run the work again. |
Request body (required)
The webhook to add.
| Name | Type | Required | Description |
|---|---|---|---|
kind | webhook | Yes | |
format | string: terminal, template, preset | Yes | |
url | string | No | A public https URL with no credentials. Required for terminal, template, and the cryptohopper preset. |
preset | string: 3commas_signal_bot, cryptohopper | No | Required when format is preset. |
inputs | object, see the schema | No | Values for the preset fields, or the template input names. |
secrets | object, see the schema | No | Values for secret fields. Returned only as names afterwards. |
template | object, see the schema | No | |
retries | boolean | No | Template only. Default false. |
label | string | No |
Responses
| Status | Description | Error codes |
|---|---|---|
201 | Add a webhook destination. The signing secret is in this answer only. | |
400 | A field is wrong, a field belongs to another format, the preset is not released, or Idempotency-Key is missing or not printable ASCII. | See the list |
402 | The plan has no webhooks or its webhook count is full (limit webhook_destinations), the account already has 20 destinations (limit destinations), or a block of calls cannot be paid. | See the list |
409 | idempotency_key_reused or in_progress. | See the list |
503 | The channel is closed, the private beta does not include the account, or webhooks are switched off (reason feature_off). | See the list |
Also 401, 403, 429 and 500, as in common answers.
GET /v1/destinations/presets
Bot presets a destination can use.
Responses
| Status | Description | Error codes |
|---|---|---|
200 | Bot presets a destination can use. | |
503 | The channel is closed for this account, or the private beta does not include the account. | See the list |
Also 400, 401, 402, 403, 429 and 500, as in common answers.
GET /v1/destinations/{id}
One destination.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | A positive integer below 2^31. Anything else, or another account's id, is not found. |
Responses
| Status | Description | Error codes |
|---|---|---|
200 | One destination. | |
404 | No destination with that id belongs to this account. | See the list |
503 | The channel is closed for this account, or the private beta does not include the account. | See the list |
Also 400, 401, 402, 403, 429 and 500, as in common answers.
PATCH /v1/destinations/{id}
Change the label, pause, or, for a terminal webhook, the URL.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | A positive integer below 2^31. Anything else, or another account's id, is not found. |
Idempotency-Key | header | string | No | Optional. When you send it, 1 to 255 printable ASCII characters. The same value and the same request returns the stored answer. |
Request body (required)
Fields a key may change.
| Name | Type | Required | Description |
|---|---|---|---|
label | string | No | Cannot be emptied. |
paused | boolean | No | Cannot clear unverified. Only a test can. |
url | string | No | Terminal format only. Changing it makes the destination unverified again. |
Responses
| Status | Description | Error codes |
|---|---|---|
200 | Change the label, pause, or, for a terminal webhook, the URL. | |
400 | A field is wrong, or the label is emptied. | See the list |
403 | The key lacks destinations:write, or the field changes only in the signed-in app (required_scope session). | See the list |
404 | No destination with that id belongs to this account. | See the list |
409 | idempotency_key_reused or in_progress. | See the list |
503 | The channel is closed for this account, or the private beta does not include the account. | See the list |
Also 401, 402, 429 and 500, as in common answers.
DELETE /v1/destinations/{id}
Delete a webhook destination and its delivery log.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | A positive integer below 2^31. Anything else, or another account's id, is not found. |
Idempotency-Key | header | string | No | Optional. When you send it, 1 to 255 printable ASCII characters. The same value and the same request returns the stored answer. |
Responses
| Status | Description | Error codes |
|---|---|---|
200 | Delete a webhook destination and its delivery log. | |
403 | The key lacks destinations:write, or the destination is not a webhook (required_scope session). | See the list |
404 | No destination with that id belongs to this account. | See the list |
409 | idempotency_key_reused or in_progress. | See the list |
503 | The channel is closed for this account, or the private beta does not include the account. | See the list |
Also 400, 401, 402, 429 and 500, as in common answers.
POST /v1/destinations/{id}/test
Queue a test send. The result shows up on last_test.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | A positive integer below 2^31. Anything else, or another account's id, is not found. |
Idempotency-Key | header | string | Yes | Required. 1 to 255 printable ASCII characters. The same value and the same request returns the stored answer and does not run the work again. |
Request body
Empty, or no body, for a terminal webhook. confirm true for a template or a preset.
| Name | Type | Required | Description |
|---|---|---|---|
confirm | boolean | No | Required, and true, for a template or a preset. A test sends the body an alert would send, and a bot may act on it. |
Responses
| Status | Description | Error codes |
|---|---|---|
202 | Queue a test send. The result shows up on last_test. | |
400 | confirm is missing for a template or a preset, or Idempotency-Key is missing or not printable ASCII. | See the list |
402 | The plan does not include webhooks (limit webhook_destinations), or a block of calls cannot be paid. | See the list |
404 | No destination with that id belongs to this account. | See the list |
409 | The destination is revoked or paused (reason destination_off), or the Idempotency-Key clashes. | See the list |
429 | The key, the account, or test sends (reason tests, 10 a minute) are over the limit. | See the list |
503 | The channel is closed for this account, or the private beta does not include the account. | See the list |
Also 401, 403 and 500, as in common answers.
Exchange
Profiles, services built from rules, subscriptions, records, earnings and sales. Answers 503 (exchange_closed) while the exchange is not open for the account, except reading, ending and reporting a subscription and reading earnings.
GET /v1/profile
Your profile, with handle_locked.
Responses
| Status | Description | Error codes |
|---|---|---|
200 | Your profile, with handle_locked. | |
404 | The account has no profile yet. | See the list |
503 | The channel is closed for this account, or the exchange is not open for it (reason exchange_closed). | See the list |
Also 400, 401, 402, 403, 429 and 500, as in common answers.
PUT /v1/profile
Create or change your profile. 201 when it is new.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | Yes | Required. 1 to 255 printable ASCII characters. The same value and the same request returns the stored answer and does not run the work again. |
Request body (required)
The profile.
| Name | Type | Required | Description |
|---|---|---|---|
handle | string | Yes | |
name | string | Yes | |
bio | string | No |
Responses
| Status | Description | Error codes |
|---|---|---|
200 | Create or change your profile. 201 when it is new. | |
201 | The profile was created. | |
400 | A field is wrong, or the text has a link, a contact or trading words (fields). | See the list |
409 | handle_taken, handle_reserved, handle_locked, profile_suspended, idempotency_key_reused or in_progress. | See the list |
503 | The channel is closed for this account, or the exchange is not open for it (reason exchange_closed). | See the list |
Also 401, 402, 403, 429 and 500, as in common answers.
GET /v1/profiles/{handle}
One profile.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
handle | path | string | Yes | A profile's handle, such as terminal. |
Responses
| Status | Description | Error codes |
|---|---|---|
200 | One profile. | |
404 | No profile with that handle. | See the list |
503 | The channel is closed for this account, or the exchange is not open for it (reason exchange_closed). | See the list |
Also 400, 401, 402, 403, 429 and 500, as in common answers.
GET /v1/services
The catalogue of listed services.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
kind | query | string: feed, call | No | feed (events) or call (one answer per API request). |
symbol | query | string | No | Only services that watch this coin. |
seller | query | string | No | Only this seller's services, by handle. |
price | query | string: free, paid | No | free, or paid. Plan-included offers are neither. |
max_price_cents | query | integer | No | Only services with an offer at or below this price per unit. |
complete | query | boolean | No | True keeps services whose record status is a complete record: no gap, old enough, enough events, anchored. This is stricter than the record field complete, which only says the numbers have no gap. False or absent applies no filter: it does not select incomplete records. When both this and the deprecated query field are sent, this one decides. |
verified | query | boolean | No | The query field verified is deprecated. Use complete. |
limit | query | integer | No | Most services in one page. |
cursor | query | string | No | A next_cursor from an earlier page. It keeps the first page's time, so the order holds across pages. |
Responses
| Status | Description | Error codes |
|---|---|---|
200 | The catalogue of listed services. | |
400 | A query parameter is wrong, or cursor is not one this API issued. | See the list |
503 | The channel is closed for this account, or the exchange is not open for it (reason exchange_closed). | See the list |
Also 401, 402, 403, 429 and 500, as in common answers.
POST /v1/services
Create a feed service from your rules. It starts recording.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | Yes | Required. 1 to 255 printable ASCII characters. The same value and the same request returns the stored answer and does not run the work again. |
Request body (required)
The service.
| Name | Type | Required | Description |
|---|---|---|---|
slug | string | Yes | 3 to 48 characters: a-z, 0-9 and hyphens. Unique among the profile's services. |
name | string | Yes | |
description | string | No | |
rule_ids | array of integer | Yes | Your active one-coin rules, each waiting at least 900 seconds between alerts, not backing another service. |
offer | object, see the schema | Yes |
Responses
| Status | Description | Error codes |
|---|---|---|
201 | Create a feed service from your rules. It starts recording. | |
400 | A field is wrong, or the text has a link, a contact or trading words (fields). | See the list |
409 | profile_required, profile_suspended, email_unverified, service_limit, rule_not_eligible (fields names each rule), slug_taken, idempotency_key_reused or in_progress. | See the list |
503 | The channel is closed for this account, or the exchange is not open for it (reason exchange_closed). | See the list |
Also 401, 402, 403, 429 and 500, as in common answers.
GET /v1/services/{id}
One service. The seller sees rule_ids, fees and reasons too.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | A positive integer below 2^31. Anything else, or another account's id, is not found. |
Responses
| Status | Description | Error codes |
|---|---|---|
200 | One service. The seller sees rule_ids, fees and reasons too. | |
404 | No service with that id, or another seller's service that is recording or was retired before it was listed. | See the list |
503 | The channel is closed for this account, or the exchange is not open for it (reason exchange_closed). | See the list |
Also 400, 401, 402, 403, 429 and 500, as in common answers.
PATCH /v1/services/{id}
Change the name or the description.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | A positive integer below 2^31. Anything else, or another account's id, is not found. |
Idempotency-Key | header | string | No | Optional. When you send it, 1 to 255 printable ASCII characters. The same value and the same request returns the stored answer. |
Request body (required)
name, description, or both.
| Name | Type | Required | Description |
|---|---|---|---|
name | string | No | |
description | string | No |
Responses
| Status | Description | Error codes |
|---|---|---|
200 | Change the name or the description. | |
400 | A field is wrong, or the body is empty. | See the list |
404 | No service with that id belongs to this account's profile. | See the list |
409 | profile_suspended, service_retired, idempotency_key_reused or in_progress. | See the list |
503 | The channel is closed for this account, or the exchange is not open for it (reason exchange_closed). | See the list |
Also 401, 402, 403, 429 and 500, as in common answers.
GET /v1/services/{id}/record
A service's numbered events and what the price did after each. This is a price record, not a recommendation.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | A positive integer below 2^31. Anything else, or another account's id, is not found. |
limit | query | integer | No | Most alerts in one page. |
before | query | integer | No | A seq. The page holds events with a lower seq. |
Responses
| Status | Description | Error codes |
|---|---|---|
200 | A service's numbered events and what the price did after each. This is a price record, not a recommendation. | |
400 | limit must be 1 to 200, and before must be a seq. | See the list |
404 | No service with that id, or another seller's service that is recording or was retired before it was listed. | See the list |
503 | The channel is closed for this account, or the exchange is not open for it (reason exchange_closed). | See the list |
Also 401, 402, 403, 429 and 500, as in common answers.
GET /v1/me/services
Your services in every state, in the seller's view.
Responses
| Status | Description | Error codes |
|---|---|---|
200 | Your services in every state, in the seller's view. | |
503 | The channel is closed for this account, or the exchange is not open for it (reason exchange_closed). | See the list |
Also 400, 401, 402, 403, 429 and 500, as in common answers.
POST /v1/services/{id}/offer
Replace the offer with a new price. Subscribers keep their price for 30 days when it goes up.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | A positive integer below 2^31. Anything else, or another account's id, is not found. |
Idempotency-Key | header | string | Yes | Required. 1 to 255 printable ASCII characters. The same value and the same request returns the stored answer and does not run the work again. |
Request body (required)
The new offer.
| Name | Type | Required | Description |
|---|---|---|---|
kind | string: free, per_event | Yes | |
price_cents | integer | Yes | 0 for free. 5 to 100 for per_event, in steps of 5. |
Responses
| Status | Description | Error codes |
|---|---|---|
200 | Replace the offer with a new price. Subscribers keep their price for 30 days when it goes up. | |
400 | kind or price_cents is wrong. | See the list |
404 | No service with that id belongs to this account's profile. | See the list |
409 | offer_change_too_soon (retry_after), profile_suspended, service_retired, idempotency_key_reused or in_progress. | See the list |
503 | The channel is closed for this account, or the exchange is not open for it (reason exchange_closed). | See the list |
Also 401, 402, 403, 429 and 500, as in common answers.
POST /v1/services/{id}/list
Put the service in the catalogue. Charges the listing fee for the current 30 days when it is not paid.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | A positive integer below 2^31. Anything else, or another account's id, is not found. |
Idempotency-Key | header | string | Yes | Required. 1 to 255 printable ASCII characters. The same value and the same request returns the stored answer and does not run the work again. |
Request body
Empty object, or no body.
An empty JSON object.
Responses
| Status | Description | Error codes |
|---|---|---|
200 | Put the service in the catalogue. Charges the listing fee for the current 30 days when it is not paid. | |
402 | The credits do not cover the listing fee (credits_required, with balance_cents, price_cents, and buy_url while credit packs are on sale). | See the list |
404 | No service with that id belongs to this account's profile. | See the list |
409 | not_listable (missing), profile_suspended, service_retired, idempotency_key_reused or in_progress. | See the list |
503 | The channel is closed for this account, or the exchange is not open for it (reason exchange_closed). | See the list |
Also 400, 401, 403, 429 and 500, as in common answers.
POST /v1/services/{id}/unlist
Take the service out of the catalogue. Subscribers keep receiving events.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | A positive integer below 2^31. Anything else, or another account's id, is not found. |
Idempotency-Key | header | string | Yes | Required. 1 to 255 printable ASCII characters. The same value and the same request returns the stored answer and does not run the work again. |
Request body
Empty object, or no body.
An empty JSON object.
Responses
| Status | Description | Error codes |
|---|---|---|
200 | Take the service out of the catalogue. Subscribers keep receiving events. | |
404 | No service with that id belongs to this account's profile. | See the list |
409 | service_not_listed, service_retired, profile_suspended, idempotency_key_reused or in_progress. | See the list |
503 | The channel is closed for this account, or the exchange is not open for it (reason exchange_closed). | See the list |
Also 400, 401, 402, 403, 429 and 500, as in common answers.
POST /v1/services/{id}/retire
Retire the service for good. Subscriptions end. The record stays readable.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | A positive integer below 2^31. Anything else, or another account's id, is not found. |
Idempotency-Key | header | string | Yes | Required. 1 to 255 printable ASCII characters. The same value and the same request returns the stored answer and does not run the work again. |
Request body
Empty object, or no body.
An empty JSON object.
Responses
| Status | Description | Error codes |
|---|---|---|
200 | Retire the service for good. Subscriptions end. The record stays readable. | |
404 | No service with that id belongs to this account's profile. | See the list |
409 | idempotency_key_reused or in_progress. | See the list |
503 | The channel is closed for this account, or the exchange is not open for it (reason exchange_closed). | See the list |
Also 400, 401, 402, 403, 429 and 500, as in common answers.
GET /v1/subscriptions
Your subscriptions, newest first.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
status | query | string: active, paused, paused_unpaid, paused_cap, paused_plan, ended | No | Only subscriptions with this status. |
Responses
| Status | Description | Error codes |
|---|---|---|
200 | Your subscriptions, newest first. | |
400 | status is not a subscription status. | See the list |
503 | The channel is closed for this account. This route works while the exchange is closed, so you can stop and report what you pay for. | See the list |
Also 401, 402, 403, 429 and 500, as in common answers.
POST /v1/subscriptions
Subscribe to a listed feed. Nothing is charged now. Each event is charged when it arrives.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | Yes | Required. 1 to 255 printable ASCII characters. The same value and the same request returns the stored answer and does not run the work again. |
Request body (required)
The service and the offer you read.
| Name | Type | Required | Description |
|---|---|---|---|
service_id | integer | Yes | |
offer_id | integer | Yes | The service's active offer, as you read it. Another one answers offer_changed. |
monthly_cap_cents | integer | No | Paid offers: 100 to 10000 cents a month, a multiple of 100. Default 500. Ignored on a free offer. |
destination_ids | array of integer or null | No | Null, or ids of your destinations. A template or preset webhook is refused (preset_not_allowed). |
name | string | No | The routing rule's name. Default: the service's name. |
Responses
| Status | Description | Error codes |
|---|---|---|
201 | Subscribe to a listed feed. Nothing is charged now. Each event is charged when it arrives. | |
400 | A field is wrong, the service answers one request at a time (service_id), or the offer is not a credits offer (offer_id). | See the list |
402 | The plan's active rules are full (limit rules). A subscription counts as one of your alerts. | See the list |
404 | No listed service with that id. | See the list |
409 | service_not_listed, own_service, already_subscribed, offer_changed (offer), preset_not_allowed, idempotency_key_reused or in_progress. | See the list |
429 | The key or the account is over its calls per minute, or the account started 20 subscriptions today (reason subscriptions_limit). | See the list |
503 | The channel is closed for this account, or the exchange is not open for it (reason exchange_closed). | See the list |
Also 401, 403 and 500, as in common answers.
GET /v1/subscriptions/{id}
One subscription.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | A positive integer below 2^31. Anything else, or another account's id, is not found. |
Responses
| Status | Description | Error codes |
|---|---|---|
200 | One subscription. | |
404 | No subscription with that id belongs to this account. | See the list |
503 | The channel is closed for this account. This route works while the exchange is closed, so you can stop and report what you pay for. | See the list |
Also 400, 401, 402, 403, 429 and 500, as in common answers.
PATCH /v1/subscriptions/{id}
Change the cap, the destinations or the name. A higher cap resumes a subscription paused at its cap when there is room.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | A positive integer below 2^31. Anything else, or another account's id, is not found. |
Idempotency-Key | header | string | No | Optional. When you send it, 1 to 255 printable ASCII characters. The same value and the same request returns the stored answer. |
Request body (required)
Fields to change.
| Name | Type | Required | Description |
|---|---|---|---|
monthly_cap_cents | integer | No | Paid offers: 100 to 10000 cents a month, a multiple of 100. Default 500. Ignored on a free offer. |
destination_ids | array of integer or null | No | Null, or ids of your destinations. A template or preset webhook is refused (preset_not_allowed). |
name | string | No |
Responses
| Status | Description | Error codes |
|---|---|---|
200 | Change the cap, the destinations or the name. A higher cap resumes a subscription paused at its cap when there is room. | |
400 | A field is wrong, or the body is empty. | See the list |
404 | No subscription with that id belongs to this account. | See the list |
409 | ended, preset_not_allowed, idempotency_key_reused or in_progress. | See the list |
503 | The channel is closed for this account, or the exchange is not open for it (reason exchange_closed). | See the list |
Also 401, 402, 403, 429 and 500, as in common answers.
DELETE /v1/subscriptions/{id}
End a subscription. Ending an ended one keeps its first end_reason.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | A positive integer below 2^31. Anything else, or another account's id, is not found. |
Idempotency-Key | header | string | No | Optional. When you send it, 1 to 255 printable ASCII characters. The same value and the same request returns the stored answer. |
Responses
| Status | Description | Error codes |
|---|---|---|
200 | End a subscription. Ending an ended one keeps its first end_reason. | |
404 | No subscription with that id belongs to this account. | See the list |
409 | idempotency_key_reused or in_progress. | See the list |
503 | The channel is closed for this account. This route works while the exchange is closed, so you can stop and report what you pay for. | See the list |
Also 400, 401, 402, 403, 429 and 500, as in common answers.
POST /v1/subscriptions/{id}/pause
Pause. Events while paused are not delivered and not charged.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | A positive integer below 2^31. Anything else, or another account's id, is not found. |
Idempotency-Key | header | string | Yes | Required. 1 to 255 printable ASCII characters. The same value and the same request returns the stored answer and does not run the work again. |
Request body
Empty object, or no body.
An empty JSON object.
Responses
| Status | Description | Error codes |
|---|---|---|
200 | Pause. Events while paused are not delivered and not charged. | |
404 | No subscription with that id belongs to this account. | See the list |
409 | ended, idempotency_key_reused or in_progress. | See the list |
503 | The channel is closed for this account, or the exchange is not open for it (reason exchange_closed). | See the list |
Also 400, 401, 402, 403, 429 and 500, as in common answers.
POST /v1/subscriptions/{id}/resume
Resume from paused, paused_unpaid or paused_cap. Delivery starts from the next event.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | A positive integer below 2^31. Anything else, or another account's id, is not found. |
Idempotency-Key | header | string | Yes | Required. 1 to 255 printable ASCII characters. The same value and the same request returns the stored answer and does not run the work again. |
Request body
Empty object, or no body.
An empty JSON object.
Responses
| Status | Description | Error codes |
|---|---|---|
200 | Resume from paused, paused_unpaid or paused_cap. Delivery starts from the next event. | |
402 | The credits do not cover one event (credits_required), a cap has no room (quota_exceeded, limit subscription_monthly or exchange_monthly), or the plan's active rules are full (limit rules). | See the list |
404 | No subscription with that id belongs to this account. | See the list |
409 | ended, paused_plan, service_retired, idempotency_key_reused or in_progress. | See the list |
503 | The channel is closed for this account, or the exchange is not open for it (reason exchange_closed). | See the list |
Also 400, 401, 403, 429 and 500, as in common answers.
POST /v1/subscriptions/{id}/accept-offer
Accept the service's new price at once.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | A positive integer below 2^31. Anything else, or another account's id, is not found. |
Idempotency-Key | header | string | Yes | Required. 1 to 255 printable ASCII characters. The same value and the same request returns the stored answer and does not run the work again. |
Request body (required)
The offer you were shown.
| Name | Type | Required | Description |
|---|---|---|---|
offer_id | integer | Yes | pending_offer.id, the offer you were shown. |
monthly_cap_cents | integer | No | Paid offers: 100 to 10000 cents a month, a multiple of 100. Default 500. Ignored on a free offer. |
Responses
| Status | Description | Error codes |
|---|---|---|
200 | Accept the service's new price at once. | |
400 | offer_id or monthly_cap_cents is wrong. | See the list |
404 | No subscription with that id belongs to this account. | See the list |
409 | offer_changed (offer), ended, service_retired, idempotency_key_reused or in_progress. | See the list |
503 | The channel is closed for this account, or the exchange is not open for it (reason exchange_closed). | See the list |
Also 401, 402, 403, 429 and 500, as in common answers.
POST /v1/subscriptions/{id}/report
Report a subscription. It ends, and charges still on hold come back as credits.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | A positive integer below 2^31. Anything else, or another account's id, is not found. |
Idempotency-Key | header | string | Yes | Required. 1 to 255 printable ASCII characters. The same value and the same request returns the stored answer and does not run the work again. |
Request body (required)
Why.
| Name | Type | Required | Description |
|---|---|---|---|
reason | string: not_as_described, did_not_subscribe, spam, other | Yes | |
note | string | No |
Responses
| Status | Description | Error codes |
|---|---|---|
200 | Report a subscription. It ends, and charges still on hold come back as credits. | |
400 | reason is not one of the listed values, or note is too long. | See the list |
404 | No subscription with that id belongs to this account. | See the list |
409 | already_reported, report_window_passed, idempotency_key_reused or in_progress. | See the list |
429 | The key or the account is over its calls per minute, or the account sent 3 reports this month (reason reports_limit). | See the list |
503 | The channel is closed for this account. This route works while the exchange is closed, so you can stop and report what you pay for. | See the list |
Also 401, 402, 403 and 500, as in common answers.
GET /v1/earnings
What you are owed as a seller, with the last 50 rows.
Responses
| Status | Description | Error codes |
|---|---|---|
200 | What you are owed as a seller, with the last 50 rows. | |
503 | The channel is closed for this account. This route works while the exchange is closed, so you can stop and report what you pay for. | See the list |
Also 400, 401, 402, 403, 429 and 500, as in common answers.
POST /v1/earnings/to-credits
Move available earnings into credits, up to the room left under the credit balance cap.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | Yes | Required. 1 to 255 printable ASCII characters. The same value and the same request returns the stored answer and does not run the work again. |
Request body (required)
The amount.
| Name | Type | Required | Description |
|---|---|---|---|
cents | integer | Yes | At least 100, at most available_cents. |
Responses
| Status | Description | Error codes |
|---|---|---|
200 | Move available earnings into credits, up to the room left under the credit balance cap. | |
400 | cents is not a whole number, or is below 100, or Idempotency-Key is missing. | See the list |
409 | insufficient_earnings (available_cents), balance_cap (cap_cents, balance_cents, room_cents: the balance is at its cap), idempotency_key_reused or in_progress. | See the list |
503 | The channel is closed for this account, or the exchange is not open for it (reason exchange_closed). | See the list |
Also 401, 402, 403, 429 and 500, as in common answers.
GET /v1/sales
Your sales as a seller and your purchases as a buyer, newest first.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
role | query | string: seller, buyer | No | seller for your sales, buyer for your purchases. Omit it for both. |
before | query | integer | No | A sale id. The page holds older sales. |
limit | query | integer | No | Most sales in one page. |
Responses
| Status | Description | Error codes |
|---|---|---|
200 | Your sales as a seller and your purchases as a buyer, newest first. | |
400 | role, before or limit is wrong. | See the list |
503 | The channel is closed for this account, or the exchange is not open for it (reason exchange_closed). | See the list |
Also 401, 402, 403, 429 and 500, as in common answers.
GET /v1/me/exchange
The account's monthly cap on all subscriptions, and this month's spend.
Responses
| Status | Description | Error codes |
|---|---|---|
200 | The account's monthly cap on all subscriptions, and this month's spend. | |
503 | The channel is closed for this account, or the exchange is not open for it (reason exchange_closed). | See the list |
Also 400, 401, 402, 403, 429 and 500, as in common answers.
PATCH /v1/me/exchange
Change the account's monthly cap.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | No | Optional. When you send it, 1 to 255 printable ASCII characters. The same value and the same request returns the stored answer. |
Request body (required)
The new cap.
| Name | Type | Required | Description |
|---|---|---|---|
monthly_cap_cents | integer | Yes |
Responses
| Status | Description | Error codes |
|---|---|---|
200 | Change the account's monthly cap. | |
400 | monthly_cap_cents must be 0 to 50000, a multiple of 100. | See the list |
409 | idempotency_key_reused or in_progress. | See the list |
503 | The channel is closed for this account, or the exchange is not open for it (reason exchange_closed). | See the list |
Also 401, 402, 403, 429 and 500, as in common answers.
Common answers
Most routes give these answers with the same meaning. A route that means something else by a status lists it in its own table.
| Status | Description | Error codes |
|---|---|---|
400 | The body is not one JSON object, or a field, a query parameter or a header is wrong. fields names each one. | See the list |
401 | No Authorization header, the scheme is not Bearer, or the key is malformed, unknown, revoked, or the account is gone. | See the list |
402 | Included calls for the month are used up, and the balance or a spend cap cannot pay for the next block of calls. | See the list |
403 | The key does not include the scope in x-scope. | See the list |
429 | The key or the account is over its calls per minute. Retry-After is whole seconds, at least 1. | See the list |
500 | Terminal failed while handling the request. Sending it again with the same Idempotency-Key is safe. | See the list |
Error codes
An error answer carries one of these in error.code. Branch on the code, not the message.
invalid_keyscope_missingterms_requiredcredits_requiredquota_exceededpayment_requiredrate_limitednot_foundconflictvalidation_failednot_availableserver_error