DEV3 Tolldeck REST API
Base URL /api/v1 · Authenticate with Authorization: Bearer n3k_… · OpenAPI 3.1 JSON
/api/v1/edge/verifyscope: publicVerify an API key for the provider's own gateway (X-Tolldeck-Product + X-Tolldeck-Signature: t=..,v1=..)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"key": {
"type": "string"
},
"operation": {
"type": "string"
},
"ip": {
"type": "string"
},
"reserve": {
"type": "boolean"
},
"nonce": {
"type": "string"
}
},
"required": [
"key"
],
"additionalProperties": false
}/api/v1/edge/usagescope: publicReport a usage batch (idempotent by batch_id, at most 5,000 items, items older than 48 h are rejected)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"batch_id": {
"type": "string"
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"operation": {
"type": "string"
},
"status": {
"type": "number"
},
"at": {
"type": [
"string",
"number"
]
},
"latency_ms": {
"type": "number"
},
"reserved": {
"type": "boolean"
}
},
"required": [
"key",
"status",
"at"
],
"additionalProperties": false
}
}
},
"required": [
"batch_id",
"items"
],
"additionalProperties": false
}/api/v1/mescope: readThe workspace this key belongs to
/api/v1/productsscope: products:readList API products
Parameters: status (query), page (query), limit (query)
/api/v1/productsscope: products:writeCreate an API product (an edge-mode product returns its edge secret once)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"slug": {
"type": "string",
"maxLength": 48
},
"description": {
"type": "string",
"maxLength": 2000
},
"mode": {
"type": "string",
"enum": [
"gateway",
"edge"
]
},
"base_path": {
"type": "string",
"maxLength": 100
},
"visibility": {
"type": "string",
"enum": [
"public",
"partner",
"private"
]
},
"upstream": {
"type": "object",
"properties": {
"base_url": {
"type": "string",
"maxLength": 500
},
"timeout_ms": {
"type": "integer",
"minimum": 1000,
"maximum": 120000
},
"auth_kind": {
"type": "string",
"enum": [
"none",
"header",
"basic",
"bearer"
]
},
"auth_header_name": {
"type": "string",
"maxLength": 60
},
"secret": {
"type": "string",
"maxLength": 500
},
"forward_headers": {
"maxItems": 20,
"type": "array",
"items": {
"type": "string",
"maxLength": 60
}
}
},
"additionalProperties": false
},
"key_header": {
"type": "string",
"pattern": "^[A-Za-z0-9-]{1,40}$"
},
"key_query": {
"type": "boolean"
},
"cors_origins": {
"maxItems": 50,
"type": "array",
"items": {
"type": "string",
"maxLength": 200
}
},
"sandbox": {
"type": "object",
"properties": {
"mock": {
"type": "boolean"
},
"base_url": {
"type": "string",
"maxLength": 500
}
},
"additionalProperties": false
}
},
"required": [
"name"
],
"additionalProperties": false
}/api/v1/products/{id}scope: products:readGet an API product (secrets are never returned)
Parameters: id (path)
/api/v1/products/{id}scope: products:writeUpdate settings, upstream, CORS, sandbox or status (live needs an upstream and a published spec)
Parameters: id (path)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 120
},
"description": {
"type": "string",
"maxLength": 2000
},
"status": {
"type": "string",
"enum": [
"draft",
"live",
"deprecated",
"archived"
]
},
"visibility": {
"type": "string",
"enum": [
"public",
"partner",
"private"
]
},
"base_path": {
"type": "string",
"maxLength": 100
},
"key_header": {
"type": "string",
"pattern": "^[A-Za-z0-9-]{1,40}$"
},
"key_query": {
"type": "boolean"
},
"cors_origins": {
"maxItems": 50,
"type": "array",
"items": {
"type": "string",
"maxLength": 200
}
},
"upstream": {
"type": "object",
"properties": {
"base_url": {
"type": "string",
"maxLength": 500
},
"timeout_ms": {
"type": "integer",
"minimum": 1000,
"maximum": 120000
},
"auth_kind": {
"type": "string",
"enum": [
"none",
"header",
"basic",
"bearer"
]
},
"auth_header_name": {
"type": "string",
"maxLength": 60
},
"secret": {
"type": "string",
"maxLength": 500
},
"forward_headers": {
"maxItems": 20,
"type": "array",
"items": {
"type": "string",
"maxLength": 60
}
}
},
"additionalProperties": false
},
"sandbox": {
"type": "object",
"properties": {
"mock": {
"type": "boolean"
},
"base_url": {
"type": "string",
"maxLength": 500
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}/api/v1/products/{id}scope: products:writeDelete a product (archived instead when developers subscribed)
Parameters: id (path)
/api/v1/products/{id}/rotate-edge-secretscope: products:writeGenerate a new edge secret (returned once; the old one stops working)
Parameters: id (path)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
}/api/v1/products/{id}/specsscope: docs:readList spec versions of a product
Parameters: id (path)
/api/v1/products/{id}/specsscope: docs:writeImport an OpenAPI/Swagger spec (multipart file= or JSON {content}); external $refs are refused
Parameters: id (path)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"content": {
"type": "string"
},
"version": {
"type": "string",
"maxLength": 40
}
},
"additionalProperties": false
}/api/v1/specs/{id}scope: docs:readSpec version with its dereferenced document (?document=1)
Parameters: id (path), document (query)
/api/v1/specs/{id}scope: docs:writePublish, make default, deprecate (with sunset date), retire, or set operation weights
Parameters: id (path)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"publish",
"deprecate",
"retire",
"weights"
]
},
"make_default": {
"type": "boolean"
},
"sunset_at": {
"type": [
"string",
"null"
]
},
"weights": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number",
"minimum": 0,
"maximum": 100000
}
}
},
"required": [
"action"
],
"additionalProperties": false
}/api/v1/specs/{id}scope: docs:writeDelete a draft spec version
Parameters: id (path)
/api/v1/plansscope: plans:readList usage plans
Parameters: product_id (query), page (query), limit (query)
/api/v1/plansscope: plans:writeCreate a usage plan (prices in minor units)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"product_id": {
"type": "string",
"pattern": "^[0-9a-f]{24}$"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"slug": {
"type": "string",
"maxLength": 40
},
"public": {
"type": "boolean"
},
"price_month": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"currency": {
"type": "string",
"minLength": 3,
"maxLength": 3
},
"included_units": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"unit": {
"type": "string",
"enum": [
"request",
"weighted_unit"
]
},
"overage_per_block": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"block_size": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"hard_cap": {
"type": "boolean"
},
"rate": {
"type": "object",
"properties": {
"per_second": {
"type": "number",
"minimum": 0.1
},
"burst": {
"type": "number",
"minimum": 1
}
},
"additionalProperties": false
},
"trial_days": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"approval_required": {
"type": "boolean"
},
"operation_allowlist": {
"maxItems": 500,
"type": "array",
"items": {
"type": "string",
"maxLength": 120
}
},
"bill_upstream_errors": {
"type": "boolean"
},
"log_sample_pct": {
"type": "number",
"minimum": 0,
"maximum": 100
},
"body_cap_mb": {
"type": "number",
"minimum": 0.001,
"maximum": 100
}
},
"required": [
"product_id",
"name"
],
"additionalProperties": false
}/api/v1/plans/{id}scope: plans:writeEdit a plan: limits apply to existing subscriptions at once
Parameters: id (path)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"slug": {
"type": "string",
"maxLength": 40
},
"public": {
"type": "boolean"
},
"price_month": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"currency": {
"type": "string",
"minLength": 3,
"maxLength": 3
},
"included_units": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"unit": {
"type": "string",
"enum": [
"request",
"weighted_unit"
]
},
"overage_per_block": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"block_size": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"hard_cap": {
"type": "boolean"
},
"rate": {
"type": "object",
"properties": {
"per_second": {
"type": "number",
"minimum": 0.1
},
"burst": {
"type": "number",
"minimum": 1
}
},
"additionalProperties": false
},
"trial_days": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"approval_required": {
"type": "boolean"
},
"operation_allowlist": {
"maxItems": 500,
"type": "array",
"items": {
"type": "string",
"maxLength": 120
}
},
"bill_upstream_errors": {
"type": "boolean"
},
"log_sample_pct": {
"type": "number",
"minimum": 0,
"maximum": 100
},
"body_cap_mb": {
"type": "number",
"minimum": 0.001,
"maximum": 100
},
"status": {
"type": "string",
"enum": [
"active",
"archived"
]
}
},
"additionalProperties": false
}/api/v1/plans/{id}scope: plans:writeDelete a plan (archived instead when subscriptions use it)
Parameters: id (path)
/api/v1/developersscope: developers:readList developers (status, e-mail search)
Parameters: status (query), email (query), page (query), limit (query)
/api/v1/developersscope: developers:writeInvite a developer (active, no self sign-up)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email",
"pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
},
"name": {
"type": "string",
"maxLength": 200
},
"company": {
"type": "string",
"maxLength": 200
},
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2
}
},
"required": [
"email"
],
"additionalProperties": false
}/api/v1/developers/{id}scope: developers:writeApprove, suspend or reinstate a developer
Parameters: id (path)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"approve",
"suspend",
"reinstate"
]
}
},
"required": [
"action"
],
"additionalProperties": false
}/api/v1/appsscope: developers:readList apps
Parameters: developer_id (query), page (query), limit (query)
/api/v1/apps/{id}scope: developers:writeSuspend or reactivate an app, edit its IP allow-list
Parameters: id (path)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"active",
"suspended"
]
},
"ip_allowlist": {
"maxItems": 50,
"type": "array",
"items": {
"type": "string",
"maxLength": 64
}
},
"name": {
"type": "string",
"maxLength": 120
}
},
"additionalProperties": false
}/api/v1/keysscope: developers:readList API keys (masked: prefix and last 4 only)
Parameters: app_id (query), status (query), page (query), limit (query)
/api/v1/keys/{id}/revokescope: developers:writeRevoke a key at once
Parameters: id (path)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
}/api/v1/keys/{id}/rotatescope: developers:writeRotate a key: the new key is returned once, the old one stays valid for the grace period
Parameters: id (path)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
}/api/v1/subscriptionsscope: developers:readList subscriptions
Parameters: status (query), product_id (query), page (query), limit (query)
/api/v1/subscriptions/{id}scope: developers:writeApprove a pending subscription, change its plan, or cancel it
Parameters: id (path)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"approve",
"change_plan",
"cancel"
]
},
"plan_id": {
"type": "string",
"pattern": "^[0-9a-f]{24}$"
}
},
"required": [
"action"
],
"additionalProperties": false
}/api/v1/usagescope: usage:readUsage rollups (group_by day|product|app|operation|status)
Parameters: group_by (query), from (query), to (query), product_id (query), app_id (query), env (query)
/api/v1/invoicesscope: billing:readList developer usage invoices
Parameters: status (query), developer_id (query), period (query), page (query), limit (query)
/api/v1/invoices/{id}scope: billing:readInvoice with lines
Parameters: id (path)
/api/v1/invoices/{id}/refundscope: billing:writeRefund up to the paid amount (minor units)
Parameters: id (path)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"amount": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"reason": {
"type": "string",
"maxLength": 300
}
},
"required": [
"amount"
],
"additionalProperties": false
}/api/v1/webhooksscope: webhooksList outbound webhook endpoints
/api/v1/webhooksscope: webhooksAdd an outbound webhook endpoint (secret returned once)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"url": {
"type": "string",
"maxLength": 500,
"format": "uri"
},
"events": {
"maxItems": 20,
"type": "array",
"items": {
"type": "string"
}
},
"description": {
"type": "string",
"maxLength": 200
}
},
"required": [
"url"
],
"additionalProperties": false
}/api/v1/webhooks/{id}scope: webhooksRemove a webhook endpoint
Parameters: id (path)