Domains
Reserve hostnames, verify DNS and attach custom domains.
Reserve a custom domain for an app and get the DNS record the user must create at their DNS provider. ready is true once the domain is verified and holds a current certificate, so apps.domains.add can attach it. Members of the project's organization only.
Requires apps:write (Create, update, start, stop, restart and rebuild apps).
An API key from Account settings, e.g. kn_...
Project id
^[0-9a-fA-F]{24}$App id
^[0-9a-fA-F]{24}$Fully qualified domain name, e.g. app.example.com
^(?=.{4,253}$)(?!-)[a-z0-9-]{1,63}(?<!-)(\.(?!-)[a-z0-9-]{1,63}(?<!-))+$OK
The request body, query or headers are invalid (invalid_request, invalid_idempotency_key, ...)
The API key is missing, malformed, unknown, revoked or expired
The key lacks a required permission (insufficient_scope), is limited to other projects or to projects while the call acts on the organization (key_project_restricted), the caller's role on the resource is too low (forbidden), or the account is frozen
No such resource, or the caller cannot see it
The resource is in a state that does not allow the action, or an idempotency key was reused
The request body exceeds the limit given in the body
Too many requests; see the X-RateLimit-* headers and Retry-After
Something failed on our side; the request id is in the body
A service we depend on (the runtime, GitHub) did not answer; retry shortly
The feature is not enabled on this server (github_not_configured), or a service we depend on is down; retry later
A service we depend on did not answer in time; retry shortly
POST /v1/projects/{projectId}/apps/{appId}/domains/reserve HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 17
{
"domain": "text"
}{
"domain": "text",
"ready": true,
"dnsRecord": {
"type": "text",
"name": "text",
"value": "text"
},
"certificate": {
"notBefore": "2026-01-01T00:00:00.000Z",
"notAfter": "2026-01-01T00:00:00.000Z"
}
}Attach a custom domain to an app: verifies the DNS record from reserve, issues the certificate and redeploys the app with the domain. Until the record resolves this fails with domain_not_verified, carrying the record to create; retry after the user has created it. Attaching an already attached domain changes nothing. Members of the project's organization only.
Requires apps:write (Create, update, start, stop, restart and rebuild apps).
Errors specific to this operation:
409
domain_not_verified: The DNS record is not in place yet; dnsRecord says what to create, retry once it resolves400
grid_to_serverless: A grid app cannot move back to serverless400
no_suitable_machines: No machine can run the app's configuration429
grid_quota_exceeded: The grids the app targets have no room for it under their per-person app and instance quotas
An API key from Account settings, e.g. kn_...
Project id
^[0-9a-fA-F]{24}$App id
^[0-9a-fA-F]{24}$Fully qualified domain name, e.g. app.example.com
^(?=.{4,253}$)(?!-)[a-z0-9-]{1,63}(?<!-)(\.(?!-)[a-z0-9-]{1,63}(?<!-))+$Created
The request body, query or headers are invalid (invalid_request, invalid_idempotency_key, ...)
The API key is missing, malformed, unknown, revoked or expired
The key lacks a required permission (insufficient_scope), is limited to other projects or to projects while the call acts on the organization (key_project_restricted), the caller's role on the resource is too low (forbidden), or the account is frozen
No such resource, or the caller cannot see it
The resource is in a state that does not allow the action, or an idempotency key was reused
The request body exceeds the limit given in the body
Too many requests; see the X-RateLimit-* headers and Retry-After
Something failed on our side; the request id is in the body
A service we depend on (the runtime, GitHub) did not answer; retry shortly
The feature is not enabled on this server (github_not_configured), or a service we depend on is down; retry later
A service we depend on did not answer in time; retry shortly
POST /v1/projects/{projectId}/apps/{appId}/domains HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 17
{
"domain": "text"
}{
"domain": "text",
"domains": [
"text"
],
"defaultDomain": null
}Detach a custom domain from an app and redeploy it without the domain; a default domain that is removed falls back to the Kinesis-issued one. Members of the project's organization only.
Requires apps:write (Create, update, start, stop, restart and rebuild apps).
Errors specific to this operation:
400
grid_to_serverless: A grid app cannot move back to serverless400
no_suitable_machines: No machine can run the app's configuration429
grid_quota_exceeded: The grids the app targets have no room for it under their per-person app and instance quotas
An API key from Account settings, e.g. kn_...
Project id
^[0-9a-fA-F]{24}$App id
^[0-9a-fA-F]{24}$Fully qualified domain name, e.g. app.example.com
^(?=.{4,253}$)(?!-)[a-z0-9-]{1,63}(?<!-)(\.(?!-)[a-z0-9-]{1,63}(?<!-))+$OK
The request body, query or headers are invalid (invalid_request, invalid_idempotency_key, ...)
The API key is missing, malformed, unknown, revoked or expired
The key lacks a required permission (insufficient_scope), is limited to other projects or to projects while the call acts on the organization (key_project_restricted), the caller's role on the resource is too low (forbidden), or the account is frozen
No such resource, or the caller cannot see it
The resource is in a state that does not allow the action, or an idempotency key was reused
Too many requests; see the X-RateLimit-* headers and Retry-After
Something failed on our side; the request id is in the body
A service we depend on (the runtime, GitHub) did not answer; retry shortly
The feature is not enabled on this server (github_not_configured), or a service we depend on is down; retry later
A service we depend on did not answer in time; retry shortly
DELETE /v1/projects/{projectId}/apps/{appId}/domains/{domain} HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"domain": "text",
"domains": [
"text"
],
"defaultDomain": null,
"deleted": true
}Choose which domain the dashboard shows as the app's address: an attached custom domain, or null for the Kinesis-issued hostname.
Requires apps:write (Create, update, start, stop, restart and rebuild apps).
An API key from Account settings, e.g. kn_...
Project id
^[0-9a-fA-F]{24}$App id
^[0-9a-fA-F]{24}$An attached custom domain, or null for the Kinesis-issued hostname
^(?=.{4,253}$)(?!-)[a-z0-9-]{1,63}(?<!-)(\.(?!-)[a-z0-9-]{1,63}(?<!-))+$OK
The request body, query or headers are invalid (invalid_request, invalid_idempotency_key, ...)
The API key is missing, malformed, unknown, revoked or expired
The key lacks a required permission (insufficient_scope), is limited to other projects or to projects while the call acts on the organization (key_project_restricted), the caller's role on the resource is too low (forbidden), or the account is frozen
No such resource, or the caller cannot see it
The resource is in a state that does not allow the action, or an idempotency key was reused
The request body exceeds the limit given in the body
Too many requests; see the X-RateLimit-* headers and Retry-After
Something failed on our side; the request id is in the body
A service we depend on (the runtime, GitHub) did not answer; retry shortly
The feature is not enabled on this server (github_not_configured), or a service we depend on is down; retry later
A service we depend on did not answer in time; retry shortly
POST /v1/projects/{projectId}/apps/{appId}/domains/default HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 17
{
"domain": "text"
}{
"domains": [
"text"
],
"defaultDomain": null
}Was this helpful?