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
GetMiddleware returns one of the caller org's edge transforms by id.
GET /v1/ingress/middlewares/{id}
GetMiddleware 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. |
PutMiddleware creates or replaces one edge transform and hot-applies it.
PUT /v1/ingress/middlewares/{id}
PutMiddleware 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 302) |
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. |
DeleteMiddleware removes one of the caller org's edge transforms and hot-applies the change.
DELETE /v1/ingress/middlewares/{id}
DeleteMiddleware 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. |
ListMiddlewares returns every edge transform the caller's org has configured, ordered by id.
GET /v1/ingress/middlewares
ListMiddlewares returns every edge transform the caller's org has configured, ordered by id. A route names the ones it wants, in order.
PutMiddleware creates or replaces one edge transform and hot-applies it.
POST /v1/ingress/middlewares
PutMiddleware 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 302) |
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. |
GetRoute returns one of the caller org's routing rules by id.
GET /v1/ingress/routes/{id}
GetRoute 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. |
PutRoute creates or replaces one routing rule and hot-applies the new table — there is no config file and no restart.
PUT /v1/ingress/routes/{id}
PutRoute 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. |
DeleteRoute removes one of the caller org's routing rules and hot-applies the shrunken table, freeing its host for another claim.
DELETE /v1/ingress/routes/{id}
DeleteRoute 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. |
ListRoutes returns every routing rule the caller's org has configured, ordered by id.
GET /v1/ingress/routes
ListRoutes 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.
PutRoute creates or replaces one routing rule and hot-applies the new table — there is no config file and no restart.
POST /v1/ingress/routes
PutRoute 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. |
GetService returns one of the caller org's backend pools by id.
GET /v1/ingress/services/{id}
GetService 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. |
PutService creates or replaces one backend pool and hot-applies it.
PUT /v1/ingress/services/{id}
PutService 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 | cloud_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. |
DeleteService removes one of the caller org's backend pools and hot-applies the change.
DELETE /v1/ingress/services/{id}
DeleteService 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. |
ListServices returns every backend pool the caller's org has configured, ordered by id.
GET /v1/ingress/services
ListServices 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.
PutService creates or replaces one backend pool and hot-applies it.
POST /v1/ingress/services
PutService 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 | cloud_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. |
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/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.
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.
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.
PutTLS replaces the caller org's ACME intent and hot-applies what can be hot-applied.
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 th |
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?