API reference
Stable v1. Additive only: routes, methods, fields and codes are added, never removed or renamed. Error codes are listed under x-obhut-error-codes.
Base URL
Every path is relative to https://api.obhut.io, for example /v1/orgs. Requests and responses
are JSON. The machine form of this reference is the OpenAPI document at
https://api.obhut.io/v1/openapi.json.
Authentication
Send an API token in the Authorization header: Authorization: Bearer token_…. Create one on
the dashboard's API tokens page or with obhut tokens create; its secret shows once. A token acts
with the permissions of the role it was created for, within its organization, and each operation
names the permission it needs.
Idempotency
Mutations take an Idempotency-Key header, 16 to 64 characters of A-Z a-z 0-9 _ -. A retry with
the same key and request replays the recorded response instead of running again. The same key with
another request answers 422 idempotency_key_reused.
Errors
An error answers with its HTTP status and { "error": { "code", "message", "requestId", "details" } }.
The code is stable and listed under error codes; the message is for people and
may change. Quote the requestId when you contact support. Statuses: 400 invalid, 401
unauthenticated, 403 forbidden, 404 not found, 409 conflict, 413 body too large, 422
unprocessable, 429 rate limited, 503 unavailable, 500 internal.
Pagination
Lists take limit (1 to 100, default 50) and cursor, and answer { "items", "nextCursor" }.
Pass nextCursor as cursor for the next page; it is null on the last.
Zones
| Operation | Method and path |
|---|---|
| List the zones of the organization, alphabetical, with search and filters | GET/v1/orgs/{org}/zones |
| Add a domain | POST/v1/orgs/{org}/zones |
| Get a zone | GET/v1/orgs/{org}/zones/{zone} |
| Remove a zone and everything the edge serves for it | DELETE/v1/orgs/{org}/zones/{zone} |
| Look up the public DNS now and activate the zone if the delegation or verification is in place | POST/v1/orgs/{org}/zones/{zone}/check |
| List the names the edge serves for a zone | GET/v1/orgs/{org}/zones/{zone}/hostnames |
| Add a hostname to a zone | POST/v1/orgs/{org}/zones/{zone}/hostnames |
| Read one hostname with its projections | GET/v1/orgs/{org}/zones/{zone}/hostnames/{hostname} |
| Remove a hostname that serves nothing, against its reviewed revision | DELETE/v1/orgs/{org}/zones/{zone}/hostnames/{hostname} |
DNS
Certificates
| Operation | Method and path |
|---|---|
| The edge certificates of a zone, in creation order, paginated | GET/v1/orgs/{org}/zones/{zone}/certificates |
| Certificates being obtained, and orders the CA refused, paginated | GET/v1/orgs/{org}/zones/{zone}/certificates/orders |
| Retry a failed order now instead of after the cooling-off period | POST/v1/orgs/{org}/zones/{zone}/certificates/orders/{order}/retry |
Origins and routes
| Operation | Method and path |
|---|---|
| The origins of a zone, alphabetical, with search | GET/v1/orgs/{org}/zones/{zone}/origins |
| Add an origin | POST/v1/orgs/{org}/zones/{zone}/origins |
| Which hostnames an origin serves, counted and paginated | GET/v1/orgs/{org}/zones/{zone}/origins/{origin}/usage |
| Get an origin | GET/v1/orgs/{org}/zones/{zone}/origins/{origin} |
| Replace an origin | PUT/v1/orgs/{org}/zones/{zone}/origins/{origin} |
| Remove an origin no hostname routes to | DELETE/v1/orgs/{org}/zones/{zone}/origins/{origin} |
| Which origin each hostname of the zone goes to | GET/v1/orgs/{org}/zones/{zone}/routes |
| Which origin a hostname's traffic goes to | GET/v1/orgs/{org}/zones/{zone}/routes/{hostname} |
| Send a hostname's traffic to an origin | PUT/v1/orgs/{org}/zones/{zone}/routes/{hostname} |
| Stop sending a hostname's traffic anywhere | DELETE/v1/orgs/{org}/zones/{zone}/routes/{hostname} |
| Which origins send their traffic through a connector, counted and paginated | GET/v1/orgs/{org}/connectors/{connector}/origins |
Static hosting
Proxy
| Operation | Method and path |
|---|---|
| List the hostnames with their lifecycle summaries | GET/v1/orgs/{org}/zones/{zone}/proxy/hostnames |
| Read the hostname lifecycle status | GET/v1/orgs/{org}/zones/{zone}/hostnames/{hostname}/proxy |
| Request a lifecycle mode; accepted with an operation id, never completed inline | PUT/v1/orgs/{org}/zones/{zone}/hostnames/{hostname}/proxy |
| Read what deleting the zone would remove, against its revision | GET/v1/orgs/{org}/zones/{zone}/deletion-impact |
WAF
| Operation | Method and path |
|---|---|
| List the rules of the deployed rule sets an exception can skip | GET/v1/orgs/{org}/waf/rules |
| Read a zone's WAF settings | GET/v1/orgs/{org}/zones/{zone}/waf |
| Save a zone's WAF settings against the revision read | PUT/v1/orgs/{org}/zones/{zone}/waf |
| List the zone's hostnames that have WAF settings of their own | GET/v1/orgs/{org}/zones/{zone}/waf/hostnames |
| Read a hostname's own WAF settings | GET/v1/orgs/{org}/zones/{zone}/hostnames/{hostname}/waf |
| Save a hostname's own WAF settings against the revision read | PUT/v1/orgs/{org}/zones/{zone}/hostnames/{hostname}/waf |
| Remove a hostname's own WAF settings against the revision read | DELETE/v1/orgs/{org}/zones/{zone}/hostnames/{hostname}/waf |
| List what the WAF did in a zone, per hour, hostname, rule and action | GET/v1/orgs/{org}/zones/{zone}/waf/counts |
| List what the WAF did on a hostname, per hour, rule and action | GET/v1/orgs/{org}/zones/{zone}/hostnames/{hostname}/waf/counts |
Rulesets
| Operation | Method and path |
|---|---|
| Check a ruleset without saving it | POST/v1/orgs/{org}/rules/check |
| List current validated rulesets | GET/v1/orgs/{org}/rules |
| Create a validated ruleset | POST/v1/orgs/{org}/rules |
| Read the current validated ruleset version | GET/v1/orgs/{org}/rules/{ruleset} |
| Save a new immutable ruleset version against the reviewed revision | PUT/v1/orgs/{org}/rules/{ruleset} |
| Delete an unused ruleset against the reviewed revision | DELETE/v1/orgs/{org}/rules/{ruleset} |
| Read a zone's rate-limit ruleset and what its pool applied | GET/v1/orgs/{org}/zones/{zone}/rate-limits |
| Bind an exact rate-limit ruleset version as the zone's rate limits | PUT/v1/orgs/{org}/zones/{zone}/rate-limits |
| Remove the zone's rate limits against the reviewed revision | DELETE/v1/orgs/{org}/zones/{zone}/rate-limits |
Tunnels
| Operation | Method and path |
|---|---|
| List the live connectors of the organization | GET/v1/orgs/{org}/connectors |
| Get a connector | GET/v1/orgs/{org}/connectors/{connector} |
| Mint a one-time token that enrolls one agent | POST/v1/orgs/{org}/connectors/enrollment-tokens |
| Where an enrollment token stands: unused, or the connector it enrolled | GET/v1/orgs/{org}/connectors/enrollment-tokens/{token} |
| Revoke a connector | POST/v1/orgs/{org}/connectors/{connector}/revoke |
Access
AI gateway
Organizations
| Operation | Method and path |
|---|---|
| List the organizations the caller belongs to | GET/v1/orgs |
| Create an organization | POST/v1/orgs |
| Get an organization | GET/v1/orgs/{org} |
| Rename an organization | PATCH/v1/orgs/{org} |
| Delete the organization with all its data | DELETE/v1/orgs/{org} |
| What deleting the organization would remove | GET/v1/orgs/{org}/deletion-impact |
| List the members of an organization | GET/v1/orgs/{org}/members |
| Change a member's role | PATCH/v1/orgs/{org}/members/{user} |
| Remove a member from an organization | DELETE/v1/orgs/{org}/members/{user} |
| org management offers list | GET/v1/orgs/{org}/management/offers |
| org management offers create | POST/v1/orgs/{org}/management/offers |
| org management offers revoke | DELETE/v1/orgs/{org}/management/offers/{offer} |
| org management offers preview | POST/v1/management/offers/preview |
| org management links list | GET/v1/orgs/{org}/management/links |
| org management links approve | POST/v1/orgs/{org}/management/links |
| org management links get | GET/v1/orgs/{org}/management/links/{link} |
| org management links update | PATCH/v1/orgs/{org}/management/links/{link} |
| org management assignments list | GET/v1/orgs/{org}/management/links/{link}/assignments |
| org management assignments create | POST/v1/orgs/{org}/management/links/{link}/assignments |
| org management assignments replace | PUT/v1/orgs/{org}/management/links/{link}/assignments/{assignment} |
| org management assignments remove | DELETE/v1/orgs/{org}/management/links/{link}/assignments/{assignment} |
| org management links end_impact | GET/v1/orgs/{org}/management/links/{link}/end-impact |
| org management links end | POST/v1/orgs/{org}/management/links/{link}/end |
| org management links handover_review | PUT/v1/orgs/{org}/management/links/{link}/handover-review |
| org management customers list | GET/v1/orgs/{org}/management/customers |
| org organization_access list | GET/v1/me/organization-access |
Identity and tokens
Audit log
| Operation | Method and path |
|---|---|
| List audit log entries, newest first | GET/v1/orgs/{org}/audit-log |
| Read one audit log entry | GET/v1/orgs/{org}/audit-log/{entry} |
Limits
| Operation | Method and path |
|---|---|
| Get the platform caps, the same for every organization | GET/v1/orgs/{org}/limits |