Ingress
Package ingress is your front door: automatic TLS certificates and hostname routing to any backend, changed live.
Package ingress is your front door: automatic TLS certificates and hostname routing to any backend, changed live.
| Base URL | https://api.hanzo.ai |
| Operations | 18 |
| Auth | Authorization: Bearer $HANZO_API_KEY |
ingress
GET /v1/ingress/middlewares/{id}
Returns one of the caller org's edge transforms by id.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID is the object to act on, from the path. |
PUT /v1/ingress/middlewares/{id}
Creates or replaces one edge transform and hot-applies it. POST mints an id when the body omits one; PUT takes the id from the URL, which wins over any id in the body. type must be one of redirectScheme, stripPrefix, addPrefix or headers, and stripPrefix/addPrefix each require their config key.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID identifies the transform within the org: [A-Za-z0-9-_.], at most 128 chars. |
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
config | object | — | Config is the transform's parameters: redirectScheme takes scheme (default https) and permanent ("true" ⇒ 301, else… |
id | string | — | ID identifies the transform within the org: [A-Za-z0-9-_.], at most 128 chars. |
type | string | — | Type is the transform: redirectScheme, stripPrefix, addPrefix or headers. |
DELETE /v1/ingress/middlewares/{id}
Removes one of the caller org's edge transforms and hot-applies the change. Routes still naming it stop being served (they compile as skipped) until they name a transform that exists. Answers 204; an id this org does not hold is 404.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID is the object to act on, from the path. |
GET /v1/ingress/middlewares
Returns every edge transform the caller's org has configured, ordered by id. A route names the ones it wants, in order.
POST /v1/ingress/middlewares
Creates or replaces one edge transform and hot-applies it. POST mints an id when the body omits one; PUT takes the id from the URL, which wins over any id in the body. type must be one of redirectScheme, stripPrefix, addPrefix or headers, and stripPrefix/addPrefix each require their config key.
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
config | object | — | Config is the transform's parameters: redirectScheme takes scheme (default https) and permanent ("true" ⇒ 301, else… |
id | string | — | ID identifies the transform within the org: [A-Za-z0-9-_.], at most 128 chars. |
type | string | — | Type is the transform: redirectScheme, stripPrefix, addPrefix or headers. |
GET /v1/ingress/routes/{id}
Returns one of the caller org's routing rules by id.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID is the object to act on, from the path. |
PUT /v1/ingress/routes/{id}
Creates or replaces one routing rule and hot-applies the new table — there is no config file and no restart. POST mints an id when the body omits one; PUT takes the id from the URL, which wins over any id in the body. A route's host is a GLOBALLY unique DNS claim: a host another org's route already holds is refused 409, so no tenant can hijack another's hostname.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID identifies the route within the org: [A-Za-z0-9-_.], at most 128 chars. |
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
host | string | — | Host is the exact hostname this route matches, lowercased with any trailing dot stripped. |
id | string | — | ID identifies the route within the org: [A-Za-z0-9-_.], at most 128 chars. |
middlewares | string[] | — | Middlewares are the ids of the edge transforms to apply, in this order, before the request reaches the service. |
pathPrefix | string | — | PathPrefix narrows the match to requests under this path; it must start with "/". |
priority | integer | — | Priority orders routes that share a host: higher wins, and equal priorities fall back to the longer PathPrefix. |
service | string | — | Service is the id of the backend pool this route dispatches to. |
tls | boolean | — | TLS asks the edge to terminate TLS for Host with an ACME-managed certificate. |
DELETE /v1/ingress/routes/{id}
Removes one of the caller org's routing rules and hot-applies the shrunken table, freeing its host for another claim. Answers 204; an id this org does not hold is 404.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID is the object to act on, from the path. |
GET /v1/ingress/routes
Returns every routing rule the caller's org has configured, ordered by id. A route maps an exact Host (and optional path prefix) to a service.
POST /v1/ingress/routes
Creates or replaces one routing rule and hot-applies the new table — there is no config file and no restart. POST mints an id when the body omits one; PUT takes the id from the URL, which wins over any id in the body. A route's host is a GLOBALLY unique DNS claim: a host another org's route already holds is refused 409, so no tenant can hijack another's hostname.
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
host | string | — | Host is the exact hostname this route matches, lowercased with any trailing dot stripped. |
id | string | — | ID identifies the route within the org: [A-Za-z0-9-_.], at most 128 chars. |
middlewares | string[] | — | Middlewares are the ids of the edge transforms to apply, in this order, before the request reaches the service. |
pathPrefix | string | — | PathPrefix narrows the match to requests under this path; it must start with "/". |
priority | integer | — | Priority orders routes that share a host: higher wins, and equal priorities fall back to the longer PathPrefix. |
service | string | — | Service is the id of the backend pool this route dispatches to. |
tls | boolean | — | TLS asks the edge to terminate TLS for Host with an ACME-managed certificate. |
GET /v1/ingress/services/{id}
Returns one of the caller org's backend pools by id.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID is the object to act on, from the path. |
PUT /v1/ingress/services/{id}
Creates or replaces one backend pool and hot-applies it. POST mints an id when the body omits one; PUT takes the id from the URL, which wins over any id in the body. A pool needs at least one backend and every backend URL must be http(s)://host[:port].
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID identifies the pool within the org: [A-Za-z0-9-_.], at most 128 chars. A create that omits it gets a generated one. |
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
backends | Backend[] | — | Backends are the upstream servers to balance across: 1..32 of them. |
id | string | — | ID identifies the pool within the org: [A-Za-z0-9-_.], at most 128 chars. A create that omits it gets a generated one. |
passHostHeader | boolean | — | PassHostHeader forwards the client's original Host header upstream instead of rewriting it to the backend's. |
DELETE /v1/ingress/services/{id}
Removes one of the caller org's backend pools and hot-applies the change. Routes still pointing at it stop being served (they compile as skipped) until they name a pool that exists. Answers 204; an id this org does not hold is 404.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID is the object to act on, from the path. |
GET /v1/ingress/services
Returns every backend pool the caller's org has configured, ordered by id. A service is the weighted round-robin target a route dispatches to.
POST /v1/ingress/services
Creates or replaces one backend pool and hot-applies it. POST mints an id when the body omits one; PUT takes the id from the URL, which wins over any id in the body. A pool needs at least one backend and every backend URL must be http(s)://host[:port].
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
backends | Backend[] | — | Backends are the upstream servers to balance across: 1..32 of them. |
id | string | — | ID identifies the pool within the org: [A-Za-z0-9-_.], at most 128 chars. A create that omits it gets a generated one. |
passHostHeader | boolean | — | PassHostHeader forwards the client's original Host header upstream instead of rewriting it to the backend's. |
GET /v1/ingress/status
Status reports the ingress edge's live posture: the role this instance runs in (app or edge), whether its listeners are bound and on which addresses, the ACME posture (staging flag and certificate cache directory), how many hosts the compiled route table currently serves, and how many the ACME HostPolicy will issue a certificate for.
GET /v1/ingress/tls
GetTLS returns the caller org's ACME intent together with the edge-wide TLS facts it lands in: which role this instance runs in, whether its listeners are bound, every host the ACME HostPolicy will issue a certificate for (the union across ALL orgs of TLS-marked routes and configured extraHosts, because one process holds one certificate cache), and the ACME directory and account email the process was started with.
PUT /v1/ingress/tls
PutTLS replaces the caller org's ACME intent and hot-applies what can be hot-applied. extraHosts are normalized and validated, then feed the ACME HostPolicy on the reload this op performs, alongside the per-route tls flags. acmeEmail and staging bind an ACME account for the lifetime of an edge process, so they only take effect when the edge (re)starts — the returned note says so.
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
acmeEmail | string | — | ACMEEmail is the ACME account email. It binds an account for the lifetime of an edge process, so it applies only when… |
extraHosts | string[] | — | ExtraHosts get certificates without owning a route — at most 256. |
staging | boolean | — | Staging issues from Let's Encrypt's staging directory (untrusted certs, high rate limits). |
How is this guide?