DEV3 Tolldeck REST API

Base URL /api/v1 · Authenticate with Authorization: Bearer n3k_… · OpenAPI 3.1 JSON

post/api/v1/edge/verifyscope: public

Verify 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
}
post/api/v1/edge/usagescope: public

Report 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
}
get/api/v1/mescope: read

The workspace this key belongs to

get/api/v1/productsscope: products:read

List API products

Parameters: status (query), page (query), limit (query)

post/api/v1/productsscope: products:write

Create 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
}
get/api/v1/products/{id}scope: products:read

Get an API product (secrets are never returned)

Parameters: id (path)

patch/api/v1/products/{id}scope: products:write

Update 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
}
delete/api/v1/products/{id}scope: products:write

Delete a product (archived instead when developers subscribed)

Parameters: id (path)

post/api/v1/products/{id}/rotate-edge-secretscope: products:write

Generate 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
}
get/api/v1/products/{id}/specsscope: docs:read

List spec versions of a product

Parameters: id (path)

post/api/v1/products/{id}/specsscope: docs:write

Import 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
}
get/api/v1/specs/{id}scope: docs:read

Spec version with its dereferenced document (?document=1)

Parameters: id (path), document (query)

patch/api/v1/specs/{id}scope: docs:write

Publish, 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
}
delete/api/v1/specs/{id}scope: docs:write

Delete a draft spec version

Parameters: id (path)

get/api/v1/plansscope: plans:read

List usage plans

Parameters: product_id (query), page (query), limit (query)

post/api/v1/plansscope: plans:write

Create 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
}
patch/api/v1/plans/{id}scope: plans:write

Edit 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
}
delete/api/v1/plans/{id}scope: plans:write

Delete a plan (archived instead when subscriptions use it)

Parameters: id (path)

get/api/v1/developersscope: developers:read

List developers (status, e-mail search)

Parameters: status (query), email (query), page (query), limit (query)

post/api/v1/developersscope: developers:write

Invite 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
}
patch/api/v1/developers/{id}scope: developers:write

Approve, 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
}
get/api/v1/appsscope: developers:read

List apps

Parameters: developer_id (query), page (query), limit (query)

patch/api/v1/apps/{id}scope: developers:write

Suspend 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
}
get/api/v1/keysscope: developers:read

List API keys (masked: prefix and last 4 only)

Parameters: app_id (query), status (query), page (query), limit (query)

post/api/v1/keys/{id}/revokescope: developers:write

Revoke a key at once

Parameters: id (path)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
post/api/v1/keys/{id}/rotatescope: developers:write

Rotate 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
}
get/api/v1/subscriptionsscope: developers:read

List subscriptions

Parameters: status (query), product_id (query), page (query), limit (query)

patch/api/v1/subscriptions/{id}scope: developers:write

Approve 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
}
get/api/v1/usagescope: usage:read

Usage rollups (group_by day|product|app|operation|status)

Parameters: group_by (query), from (query), to (query), product_id (query), app_id (query), env (query)

get/api/v1/invoicesscope: billing:read

List developer usage invoices

Parameters: status (query), developer_id (query), period (query), page (query), limit (query)

get/api/v1/invoices/{id}scope: billing:read

Invoice with lines

Parameters: id (path)

post/api/v1/invoices/{id}/refundscope: billing:write

Refund 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
}
get/api/v1/webhooksscope: webhooks

List outbound webhook endpoints

post/api/v1/webhooksscope: webhooks

Add 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
}
delete/api/v1/webhooks/{id}scope: webhooks

Remove a webhook endpoint

Parameters: id (path)