# Schemas

Every object the Ceryx API accepts and returns.

## Error

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | Yes |  |

## RouteSettings

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enforce_https` | boolean | Yes | Redirect HTTP requests to HTTPS. A route created without it gets `CERYX_ROUTE_SETTINGS_DEFAULT_ENFORCE_HTTPS` (false unless set). |
| `mode` | string | Yes | `proxy` forwards requests to the target; `redirect` redirects to it. |
| `certificate_path` | string or null | Yes | Path of a certificate file inside the container. |
| `key_path` | string or null | Yes | Path of the matching private key file. |
| `mtls_require_client_certificate` | boolean | Yes | Require clients to present a certificate signed by `mtls_trusted_ca`; others get 403, and requests sent on a TLS connection opened for another hostname get 421. Requires `enforce_https`. A route created without it gets `CERYX_ROUTE_SETTINGS_DEFAULT_MTLS_REQUIRE_CLIENT_CERTIFICATE` (false unless set). |
| `mtls_trusted_ca` | string or null | Yes | Path of the CA bundle inside the container that client certificates must be signed by. When null, requests use `CERYX_MTLS_DEFAULT_TRUSTED_CA`. |
| `mtls_verify_depth` | integer or null, 0 or more | Yes | Maximum number of intermediate certificates between a client certificate and the CA. When null, requests use `CERYX_MTLS_DEFAULT_VERIFY_DEPTH`, or OpenSSL's limit. |

## RouteSettingsInput

Any subset of the route settings.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enforce_https` | boolean | No | Redirect HTTP requests to HTTPS. A route created without it gets `CERYX_ROUTE_SETTINGS_DEFAULT_ENFORCE_HTTPS` (false unless set). |
| `mode` | string | No | `proxy` forwards requests to the target; `redirect` redirects to it. |
| `certificate_path` | string or null | No | Path of a certificate file inside the container. |
| `key_path` | string or null | No | Path of the matching private key file. |
| `mtls_require_client_certificate` | boolean | No | Require clients to present a certificate signed by `mtls_trusted_ca`; others get 403, and requests sent on a TLS connection opened for another hostname get 421. Requires `enforce_https`. A route created without it gets `CERYX_ROUTE_SETTINGS_DEFAULT_MTLS_REQUIRE_CLIENT_CERTIFICATE` (false unless set). |
| `mtls_trusted_ca` | string | No | Path of the CA bundle inside the container that client certificates must be signed by. When null, requests use `CERYX_MTLS_DEFAULT_TRUSTED_CA`. |
| `mtls_verify_depth` | integer, 0 or more | No | Maximum number of intermediate certificates between a client certificate and the CA. When null, requests use `CERYX_MTLS_DEFAULT_VERIFY_DEPTH`, or OpenSSL's limit. |

## Route

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `source` | string | Yes | Hostname to match, or `$wildcard` for the catch-all route. |
| `target` | string | Yes | Upstream to proxy or redirect to. |
| `settings` | [RouteSettings](/docs/api/schemas#routesettings) | Yes |  |

## RouteCreate

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `source` | string | Yes | Hostname to match, or `$wildcard` for the catch-all route. |
| `target` | string | Yes | Upstream to proxy or redirect to. |
| `settings` | [RouteSettingsInput](/docs/api/schemas#routesettingsinput) | No | Any subset of the route settings. |

## RouteUpdate

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `source` | string | No | Optional; must equal the `host` in the URL. |
| `target` | string | No | Upstream to proxy or redirect to. |
| `settings` | [RouteSettingsInput](/docs/api/schemas#routesettingsinput) | No | Any subset of the route settings. |

## CertificateMeta

Free-form metadata. Ceryx adds `issued_at` (when not given) and `stored_at` on every write.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `vendor` | string | No |  |
| `san` | array of string | No |  |
| `issued_at` | string | No |  |
| `expires_at` | string | No |  |
| `stored_at` | integer | No |  |

Other fields are allowed too.

## Certificate

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | Yes | Optional; must equal the `domain` in the URL. |
| `has_certificate` | boolean | Yes |  |
| `has_chain` | boolean | Yes |  |
| `meta` | [CertificateMeta](/docs/api/schemas#certificatemeta) | No | Free-form metadata. Ceryx adds `issued_at` (when not given) and `stored_at` on every write. |

## CertificateListItem

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | Yes | Optional; must equal the `domain` in the URL. |
| `meta` | [CertificateMeta](/docs/api/schemas#certificatemeta) | No | Free-form metadata. Ceryx adds `issued_at` (when not given) and `stored_at` on every write. |

## CertificateCreate

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | Yes | Optional; must equal the `domain` in the URL. |
| `certificate` | string | Yes | PEM-encoded certificate. |
| `private_key` | string | Yes | PEM-encoded private key. |
| `chain` | string | No | PEM-encoded intermediate chain. |
| `meta` | [CertificateMeta](/docs/api/schemas#certificatemeta) | No | Free-form metadata. Ceryx adds `issued_at` (when not given) and `stored_at` on every write. |

## CertificateUpdate

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | No | Optional; must equal the `domain` in the URL. |
| `certificate` | string | No | PEM-encoded certificate; requires `private_key`. |
| `private_key` | string | No | PEM-encoded private key; requires `certificate`. |
| `chain` | string | No | Used only with a new `certificate`; omitting it clears the chain. |
| `meta` | [CertificateMeta](/docs/api/schemas#certificatemeta) | No | Free-form metadata. Ceryx adds `issued_at` (when not given) and `stored_at` on every write. |

`certificate` requires `private_key`.

`private_key` requires `certificate`.