Postgres

A database is a resource of kind postgres: PostgreSQL on a machine of its own with its data on a volume, reachable only from the apps you attach it to, always over TLS. Every database can be branched (a copy-on-write copy on the same host, ready in seconds) or forked (a full copy from its archive, on any host, optionally from a moment in the past). See the guide Postgres.

The resource routes also accept kind: "redis"; the fields that only apply to Postgres say so.

Endpoints

• POST /v1/resources: Creates a database. The answer carries the connection URL with its password, and only this answer does
• GET /v1/resources: The organization’s databases, never a URL
• GET /v1/resources/:name: One database with its state
• PATCH /v1/resources/:name: Changes what can change later: the expiry of a copy, and the sleep policy
• DELETE /v1/resources/:name: Deletes the database, its machine and its volume, and detaches it from every app. It cannot be undone
• POST /v1/resources/:name/branch: Creates a copy-on-write branch of the database as it is now. Answers 202 with the branch in state restoring
• POST /v1/resources/:name/fork: Creates a full copy from the database’s archive, optionally as of a moment in the past. Answers 202
• POST /v1/resources/:name/restore: Puts the database back to a moment in time in place; the state before is kept as a branch
• POST /v1/resources/:name/url: Hands out the connection URL of a branch or fork exactly once

POST /v1/resources

Creates a database. The answer carries the connection URL with its password, and only this answer does.

Auth: API key with full access (a key with scopes cannot call this route). An agent token of class sandbox or twin may call it; class production is refused (agent-token-production-readonly).

Request body

JSON, the shape CreateResourceRequest of the contract.

Field	Type	Required	Description
name	string	required	The database’s name, like an app name. Unique across Rytiv.
kind	redis | postgres	required	postgres or redis.
memoryMb	integer	optional	Memory of the database’s machine. 128 to 16384.
persistent	boolean	optional	Whether the data lives on a volume. Default: yes for Postgres.
sizeGb	integer	optional	Size of the data volume in GB. 1 to 500.
flushIntervalS	integer	optional	How often the volume is copied to durable storage. 15 to 86400.
durability	standard | host-redundant | zone-redundant	optional	standard: one machine. host-redundant: a standby on a second host. Postgres only; zone-redundant is in the shape but refused at creation.
locale	string	optional	The ICU locale for sorting and comparing text. Fixed once the database exists. Postgres only.
suspendPolicy	object	optional	When the database sleeps. Postgres only; {"mode": "off"} keeps it always on.
suspendPolicy.mode	suspend | stop | off	optional	suspend keeps the memory and resumes fast (machines up to 2048 MB; larger ones stop instead), stop shuts down, off never sleeps. default "suspend".
suspendPolicy.idleSeconds	integer	optional	Seconds without requests and without CPU load before the machine sleeps. 10 to 86400, default 300.
suspendPolicy.stopAfterSeconds	integer	optional	Second stage: after this many seconds since the last activity a suspended machine is stopped (its memory snapshot dropped, its disk kept). Only with mode: "suspend", and greater than idleSeconds. 10 to 604800.

Example request

curl -X POST "https://api.rytiv.app/v1/resources" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-db","kind":"postgres"}'

Response

201 with a JSON object of these fields:

Field	Type	Description
name	string
kind	string
port	integer
secretKey	string	the name of the secret an attached app gets, DATABASE_URL
url	string	the connection URL with its password; returned here only

Errors

Status	Code	Meaning
400	bad-request	The request is malformed or a field is out of range. error names every field; issues lists them.
400	name-reserved	The platform keeps this name (for example api, console, docs, www, and every name that is rytiv or starts with rytiv-).
401	unauthenticated	No API key, or one that does not work.
403	token-scope	The key’s scopes do not cover this route.
409	conflict	The request conflicts with the current state.
409	name-taken	The name is used somewhere on Rytiv (an app, a database, a volume or a bucket).
503	no-capacity	No host in the region has room for the machine right now; try again.

GET /v1/resources

The organization’s databases, never a URL.

Auth: API key with full access or the scope read. Every class of agent token may call it.

Example request

curl -X GET "https://api.rytiv.app/v1/resources" \
  -H "Authorization: Bearer $RYTIV_TOKEN"

Response

200 with a list of databases, each:

[
  {
    "name": "my-db",
    "orgId": "<orgId>",
    "kind": "postgres",
    "port": -9007199254740991,
    "secretKey": "<secretKey>",
    "durability": "standard",
    "createdAt": "2026-10-21T09:00:00Z",
    "state": "restoring"
  }
]

Field	Type	Present	Description
name	string	always	The database’s name.
orgId	string	always	The organization that owns it.
kind	redis | postgres	always	postgres or redis.
port	integer	always	The port the database listens on. -9007199254740991 to 9007199254740991.
secretKey	string	always	The name of the secret an attached app gets, DATABASE_URL.
durability	standard | host-redundant | zone-redundant	always	standard: one machine. host-redundant: a standby on a second host. default "standard".
primaryMachineId	string	if set	Redundant databases: the machine that is primary now.
createdAt	string (ISO 8601)	always	When it was created.
state	restoring | ready | failed	always	ready, or for a copy restoring until it is, or failed. default "ready".
stateReason	string	if set	Why a copy ended failed.
sourceName	string	if set	Copies: the database it was made from.
sourceAsOf	string (ISO 8601)	if set	Copies: the moment of the source’s data.
copyKind	fork | branch	if set	fork or branch.
ephemeral	true	if set	Ephemeral branches only: true.
ephemeralNote	string	if set	The same, as a sentence.
suspendPolicy	object	if set	When the database sleeps.
suspendPolicy.mode	suspend | stop | off	always	suspend keeps the memory and resumes fast (machines up to 2048 MB; larger ones stop instead), stop shuts down, off never sleeps. default "suspend".
suspendPolicy.idleSeconds	integer	always	Seconds without requests and without CPU load before the machine sleeps. 10 to 86400, default 300.
suspendPolicy.stopAfterSeconds	integer	if set	Second stage: after this many seconds since the last activity a suspended machine is stopped (its memory snapshot dropped, its disk kept). Only with mode: "suspend", and greater than idleSeconds. 10 to 604800.
expiresAt	string (ISO 8601)	if set	Copies: when the platform deletes it.

Errors

Status	Code	Meaning
401	unauthenticated	No API key, or one that does not work.
403	token-scope	The key’s scopes do not cover this route.

GET /v1/resources/:name

One database with its state.

Auth: API key with full access (a key with scopes cannot call this route). Every class of agent token may call it.

Path parameters

Name	Description
name	The database’s name.

Example request

curl -X GET "https://api.rytiv.app/v1/resources/<name>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"

Response

200 with the database:

{
  "name": "my-db",
  "orgId": "<orgId>",
  "kind": "postgres",
  "port": -9007199254740991,
  "secretKey": "<secretKey>",
  "durability": "standard",
  "createdAt": "2026-10-21T09:00:00Z",
  "state": "restoring"
}

Field	Type	Present	Description
name	string	always	The database’s name.
orgId	string	always	The organization that owns it.
kind	redis | postgres	always	postgres or redis.
port	integer	always	The port the database listens on. -9007199254740991 to 9007199254740991.
secretKey	string	always	The name of the secret an attached app gets, DATABASE_URL.
durability	standard | host-redundant | zone-redundant	always	standard: one machine. host-redundant: a standby on a second host. default "standard".
primaryMachineId	string	if set	Redundant databases: the machine that is primary now.
createdAt	string (ISO 8601)	always	When it was created.
state	restoring | ready | failed	always	ready, or for a copy restoring until it is, or failed. default "ready".
stateReason	string	if set	Why a copy ended failed.
sourceName	string	if set	Copies: the database it was made from.
sourceAsOf	string (ISO 8601)	if set	Copies: the moment of the source’s data.
copyKind	fork | branch	if set	fork or branch.
ephemeral	true	if set	Ephemeral branches only: true.
ephemeralNote	string	if set	The same, as a sentence.
suspendPolicy	object	if set	When the database sleeps.
suspendPolicy.mode	suspend | stop | off	always	suspend keeps the memory and resumes fast (machines up to 2048 MB; larger ones stop instead), stop shuts down, off never sleeps. default "suspend".
suspendPolicy.idleSeconds	integer	always	Seconds without requests and without CPU load before the machine sleeps. 10 to 86400, default 300.
suspendPolicy.stopAfterSeconds	integer	if set	Second stage: after this many seconds since the last activity a suspended machine is stopped (its memory snapshot dropped, its disk kept). Only with mode: "suspend", and greater than idleSeconds. 10 to 604800.
expiresAt	string (ISO 8601)	if set	Copies: when the platform deletes it.

Errors

Status	Code	Meaning
401	unauthenticated	No API key, or one that does not work.
403	token-scope	The key’s scopes do not cover this route.
404	not-found	Not found, or not yours. An object of another organization answers like one that does not exist.

PATCH /v1/resources/:name

Changes what can change later: the expiry of a copy, and the sleep policy.

Auth: API key with full access (a key with scopes cannot call this route). An agent token of class sandbox or twin may call it; class production is refused (agent-token-production-readonly).

Path parameters

Name	Description
name	The database’s name.

Request body

JSON, the shape UpdateResourceRequest of the contract.

Field	Type	Required	Description
suspendPolicy	object	optional	When the machine sleeps. Without it, a new app never sleeps; a deploy without it keeps the app’s rule.
suspendPolicy.mode	suspend | stop | off	optional	suspend keeps the memory and resumes fast (machines up to 2048 MB; larger ones stop instead), stop shuts down, off never sleeps. default "suspend".
suspendPolicy.idleSeconds	integer	optional	Seconds without requests and without CPU load before the machine sleeps. 10 to 86400, default 300.
suspendPolicy.stopAfterSeconds	integer	optional	Second stage: after this many seconds since the last activity a suspended machine is stopped (its memory snapshot dropped, its disk kept). Only with mode: "suspend", and greater than idleSeconds. 10 to 604800.
expiresAt	string (ISO 8601) or null	optional	When the copy is deleted (a moment). Not together with ttlSeconds.
ttlSeconds	integer	optional	Lifetime from now, in seconds. 60 to 2592000.

Example request

curl -X PATCH "https://api.rytiv.app/v1/resources/<name>" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"suspendPolicy":{"mode":"suspend"}}'

Response

200 with the database:

{
  "name": "my-db",
  "orgId": "<orgId>",
  "kind": "postgres",
  "port": -9007199254740991,
  "secretKey": "<secretKey>",
  "durability": "standard",
  "createdAt": "2026-10-21T09:00:00Z",
  "state": "restoring"
}

Field	Type	Present	Description
name	string	always	The database’s name.
orgId	string	always	The organization that owns it.
kind	redis | postgres	always	postgres or redis.
port	integer	always	The port the database listens on. -9007199254740991 to 9007199254740991.
secretKey	string	always	The name of the secret an attached app gets, DATABASE_URL.
durability	standard | host-redundant | zone-redundant	always	standard: one machine. host-redundant: a standby on a second host. default "standard".
primaryMachineId	string	if set	Redundant databases: the machine that is primary now.
createdAt	string (ISO 8601)	always	When it was created.
state	restoring | ready | failed	always	ready, or for a copy restoring until it is, or failed. default "ready".
stateReason	string	if set	Why a copy ended failed.
sourceName	string	if set	Copies: the database it was made from.
sourceAsOf	string (ISO 8601)	if set	Copies: the moment of the source’s data.
copyKind	fork | branch	if set	fork or branch.
ephemeral	true	if set	Ephemeral branches only: true.
ephemeralNote	string	if set	The same, as a sentence.
suspendPolicy	object	if set	When the database sleeps.
suspendPolicy.mode	suspend | stop | off	always	suspend keeps the memory and resumes fast (machines up to 2048 MB; larger ones stop instead), stop shuts down, off never sleeps. default "suspend".
suspendPolicy.idleSeconds	integer	always	Seconds without requests and without CPU load before the machine sleeps. 10 to 86400, default 300.
suspendPolicy.stopAfterSeconds	integer	if set	Second stage: after this many seconds since the last activity a suspended machine is stopped (its memory snapshot dropped, its disk kept). Only with mode: "suspend", and greater than idleSeconds. 10 to 604800.
expiresAt	string (ISO 8601)	if set	Copies: when the platform deletes it.

Errors

Status	Code	Meaning
400	bad-request	The request is malformed or a field is out of range. error names every field; issues lists them.
401	unauthenticated	No API key, or one that does not work.
403	token-scope	The key’s scopes do not cover this route.
404	not-found	Not found, or not yours. An object of another organization answers like one that does not exist.

DELETE /v1/resources/:name

Deletes the database, its machine and its volume, and detaches it from every app. It cannot be undone.

Auth: API key with full access (a key with scopes cannot call this route). An agent token of class sandbox or twin may call it; class production is refused (agent-token-production-readonly).

Path parameters

Name	Description
name	The database’s name.

Example request

curl -X DELETE "https://api.rytiv.app/v1/resources/<name>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"

Response

204 with no body.

Errors

Status	Code	Meaning
401	unauthenticated	No API key, or one that does not work.
403	token-scope	The key’s scopes do not cover this route.
404	not-found	Not found, or not yours. An object of another organization answers like one that does not exist.

POST /v1/resources/:name/branch

Creates a copy-on-write branch of the database as it is now. Answers 202 with the branch in state restoring.

Auth: API key with full access (a key with scopes cannot call this route). An agent token of class sandbox or twin may call it; class production is refused (agent-token-production-readonly).

Path parameters

Name	Description
name	The database’s name.

Request body

JSON, the shape BranchResourceRequest of the contract.

Field	Type	Required	Description
name	string	required	The name of the new branch.
ephemeral	boolean	optional	Ready faster, without an archive of its own; lost if its host fails.
expiresAt	string (ISO 8601)	optional	When the copy is deleted (a moment). Not together with ttlSeconds.
ttlSeconds	integer	optional	When the copy is deleted, as seconds from now. 60 to 2592000.

Example request

curl -X POST "https://api.rytiv.app/v1/resources/<name>/branch" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-db-try"}'

Response

202 with the branch, in state restoring:

{
  "name": "my-db",
  "orgId": "<orgId>",
  "kind": "postgres",
  "port": -9007199254740991,
  "secretKey": "<secretKey>",
  "durability": "standard",
  "createdAt": "2026-10-21T09:00:00Z",
  "state": "restoring"
}

Field	Type	Present	Description
name	string	always	The database’s name.
orgId	string	always	The organization that owns it.
kind	redis | postgres	always	postgres or redis.
port	integer	always	The port the database listens on. -9007199254740991 to 9007199254740991.
secretKey	string	always	The name of the secret an attached app gets, DATABASE_URL.
durability	standard | host-redundant | zone-redundant	always	standard: one machine. host-redundant: a standby on a second host. default "standard".
primaryMachineId	string	if set	Redundant databases: the machine that is primary now.
createdAt	string (ISO 8601)	always	When it was created.
state	restoring | ready | failed	always	ready, or for a copy restoring until it is, or failed. default "ready".
stateReason	string	if set	Why a copy ended failed.
sourceName	string	if set	Copies: the database it was made from.
sourceAsOf	string (ISO 8601)	if set	Copies: the moment of the source’s data.
copyKind	fork | branch	if set	fork or branch.
ephemeral	true	if set	Ephemeral branches only: true.
ephemeralNote	string	if set	The same, as a sentence.
suspendPolicy	object	if set	When the database sleeps.
suspendPolicy.mode	suspend | stop | off	always	suspend keeps the memory and resumes fast (machines up to 2048 MB; larger ones stop instead), stop shuts down, off never sleeps. default "suspend".
suspendPolicy.idleSeconds	integer	always	Seconds without requests and without CPU load before the machine sleeps. 10 to 86400, default 300.
suspendPolicy.stopAfterSeconds	integer	if set	Second stage: after this many seconds since the last activity a suspended machine is stopped (its memory snapshot dropped, its disk kept). Only with mode: "suspend", and greater than idleSeconds. 10 to 604800.
expiresAt	string (ISO 8601)	if set	Copies: when the platform deletes it.

Errors

Status	Code	Meaning
400	bad-request	The request is malformed or a field is out of range. error names every field; issues lists them.
401	unauthenticated	No API key, or one that does not work.
403	token-scope	The key’s scopes do not cover this route.
404	not-found	Not found, or not yours. An object of another organization answers like one that does not exist.
409	name-taken	The name is used somewhere on Rytiv (an app, a database, a volume or a bucket).

POST /v1/resources/:name/fork

Creates a full copy from the database’s archive, optionally as of a moment in the past. Answers 202.

Auth: API key with full access (a key with scopes cannot call this route). An agent token of class sandbox or twin may call it; class production is refused (agent-token-production-readonly).

Path parameters

Name	Description
name	The database’s name.

Request body

JSON, the shape ForkResourceRequest of the contract.

Field	Type	Required	Description
name	string	required	The name of the new fork.
asOf	string (ISO 8601)	optional	A moment in the past to copy or restore from (ISO 8601). Without it, now.
expiresAt	string (ISO 8601)	optional	When the copy is deleted (a moment). Not together with ttlSeconds.
ttlSeconds	integer	optional	When the copy is deleted, as seconds from now. 60 to 2592000.

Example request

curl -X POST "https://api.rytiv.app/v1/resources/<name>/fork" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-db-yesterday"}'

Response

202 with the fork, in state restoring:

{
  "name": "my-db",
  "orgId": "<orgId>",
  "kind": "postgres",
  "port": -9007199254740991,
  "secretKey": "<secretKey>",
  "durability": "standard",
  "createdAt": "2026-10-21T09:00:00Z",
  "state": "restoring"
}

Field	Type	Present	Description
name	string	always	The database’s name.
orgId	string	always	The organization that owns it.
kind	redis | postgres	always	postgres or redis.
port	integer	always	The port the database listens on. -9007199254740991 to 9007199254740991.
secretKey	string	always	The name of the secret an attached app gets, DATABASE_URL.
durability	standard | host-redundant | zone-redundant	always	standard: one machine. host-redundant: a standby on a second host. default "standard".
primaryMachineId	string	if set	Redundant databases: the machine that is primary now.
createdAt	string (ISO 8601)	always	When it was created.
state	restoring | ready | failed	always	ready, or for a copy restoring until it is, or failed. default "ready".
stateReason	string	if set	Why a copy ended failed.
sourceName	string	if set	Copies: the database it was made from.
sourceAsOf	string (ISO 8601)	if set	Copies: the moment of the source’s data.
copyKind	fork | branch	if set	fork or branch.
ephemeral	true	if set	Ephemeral branches only: true.
ephemeralNote	string	if set	The same, as a sentence.
suspendPolicy	object	if set	When the database sleeps.
suspendPolicy.mode	suspend | stop | off	always	suspend keeps the memory and resumes fast (machines up to 2048 MB; larger ones stop instead), stop shuts down, off never sleeps. default "suspend".
suspendPolicy.idleSeconds	integer	always	Seconds without requests and without CPU load before the machine sleeps. 10 to 86400, default 300.
suspendPolicy.stopAfterSeconds	integer	if set	Second stage: after this many seconds since the last activity a suspended machine is stopped (its memory snapshot dropped, its disk kept). Only with mode: "suspend", and greater than idleSeconds. 10 to 604800.
expiresAt	string (ISO 8601)	if set	Copies: when the platform deletes it.

Errors

Status	Code	Meaning
400	bad-request	The request is malformed or a field is out of range. error names every field; issues lists them.
401	unauthenticated	No API key, or one that does not work.
403	token-scope	The key’s scopes do not cover this route.
404	not-found	Not found, or not yours. An object of another organization answers like one that does not exist.
409	name-taken	The name is used somewhere on Rytiv (an app, a database, a volume or a bucket).

POST /v1/resources/:name/restore

Puts the database back to a moment in time in place; the state before is kept as a branch.

Auth: API key with full access (a key with scopes cannot call this route). An agent token of class sandbox or twin may call it; class production is refused (agent-token-production-readonly).

Path parameters

Name	Description
name	The database’s name.

Request body

JSON, the shape RestoreResourceRequest of the contract.

Field	Type	Required	Description
asOf	string (ISO 8601)	required	A moment in the past to copy or restore from (ISO 8601). Without it, now.
backupName	string	optional	The name of the branch that keeps the state before the restore. Default: <name>-old-<timestamp>.

Example request

curl -X POST "https://api.rytiv.app/v1/resources/<name>/restore" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"asOf":"2026-10-21T09:00:00Z"}'

Response

A JSON body on success.

Errors

Status	Code	Meaning
400	bad-request	The request is malformed or a field is out of range. error names every field; issues lists them.
401	unauthenticated	No API key, or one that does not work.
403	token-scope	The key’s scopes do not cover this route.
404	not-found	Not found, or not yours. An object of another organization answers like one that does not exist.

POST /v1/resources/:name/url

Hands out the connection URL of a branch or fork exactly once.

Auth: API key with full access (a key with scopes cannot call this route). An agent token of class sandbox or twin may call it; class production is refused.

Path parameters

Name	Description
name	The name of the branch or fork.

Example request

curl -X POST "https://api.rytiv.app/v1/resources/<name>/url" \
  -H "Authorization: Bearer $RYTIV_TOKEN"

Response

200 with the connection URL:

{
  "name": "my-app",
  "url": "<url>"
}

Field	Type	Present	Description
name	string	always
url	string	always	The connection URL with its password. Handed out once.

Errors

Status	Code	Meaning
401	unauthenticated	No API key, or one that does not work.
403	token-scope	The key’s scopes do not cover this route.
404	not-found	Not found, or not yours. An object of another organization answers like one that does not exist.
409	not-a-copy	The database is neither a fork nor a branch; its URL came with its create answer.
409	not-ready	The copy is still restoring, or failed; there is nothing to hand out yet.
409	url-handed-out	The URL of this copy was handed out already. It leaves the platform exactly once.