Data shapes and field constraints

These tables describe serialized fields. “Required by schema” is a field-level rule, not permission to send every writable field. The endpoint reference takes precedence: IDs supplied by the URL or account are assigned by the service, updates are partial, and some response shapes are assembled separately. Read-only fields belong in responses; write-only fields belong in requests.

UUIDs are strings; timestamps use ISO 8601. Null, omitted and empty string are different values. computed fields are described in the notes below. Defaults and cross-field requirements are given on the operation page.

Workspace

Field	Type	Direction	Required by schema	Constraints
id	UUID string	response	no	—
name	string	request/response	yes	max_length: 100
description	string	request/response	no	empty string allowed
owner_id	string	request/response	yes	max_length: 50
is_active	boolean	request/response	no	—
database_count	computed	response	no	—
member_count	computed	response	no	—
created_at	timestamp	response	no	—
updated_at	timestamp	response	no	—

WorkspaceMember

Field	Type	Direction	Required by schema	Constraints
id	UUID string	response	no	—
workspace	resource ID	request/response	yes	—
user_id	string	request/response	yes	max_length: 50
user_email	computed	response	no	—
workspace_name	string	response	no	—
role	enum	request/response	no	values: owner, admin, member
created_at	timestamp	response	no	—

WorkspaceInvitation

Field	Type	Direction	Required by schema	Constraints
id	UUID string	response	no	—
workspace	resource ID	response	no	—
workspace_name	string	response	no	—
invited_user_id	string	request/response	yes	max_length: 50
invited_user_email	computed	response	no	—
invited_by_id	string	response	no	—
role	enum	request/response	no	values: owner, admin, member
status	enum	response	no	values: pending, accepted, rejected, expired, cancelled
created_at	timestamp	response	no	—
expires_at	timestamp	response	no	—
is_expired	boolean	response	no	—

DeveloperSearch

Field	Type	Direction	Required by schema	Constraints
id	string	request/response	yes	—
email	string	request/response	yes	—
first_name	string	request/response	no	empty string allowed
last_name	string	request/response	no	empty string allowed

Database

Field	Type	Direction	Required by schema	Constraints
id	UUID string	response	no	—
workspace	resource ID	request/response	yes	—
workspace_name	string	response	no	—
display_name	string	request/response	yes	max_length: 100
description	string	request/response	no	empty string allowed
db_name	string	response	no	—
engine	enum	request/response	no	values: postgres, redis, mongodb
host	string	response	no	—
port	integer	response	no	—
status	enum	response	no	values: creating, active, paused, deleting, deleted, error
storage_used_mb	integer	response	no	—
max_storage_mb	integer	request/response	no	min_value: -9223372036854775808; max_value: 9223372036854775807
max_connections	integer	request/response	no	min_value: -9223372036854775808; max_value: 9223372036854775807
version	string	response	no	—
region	string	response	no	—
allowed_cidrs	JSON value	request/response	no	—
allowlist_enforced	computed	response	no	—
user_count	computed	response	no	—
backup_count	computed	response	no	—
created_at	timestamp	response	no	—
updated_at	timestamp	response	no	—
paused_at	timestamp	response	no	nullable

DatabaseConnection

Field	Type	Direction	Required by schema	Constraints
host	string	request/response	yes	—
port	integer	request/response	yes	—
database	string	request/response	yes	—
username	string	request/response	yes	—
password	string	request/response	yes	—
connection_string	string	request/response	yes	—
ssl_mode	string	request/response	no	default: prefer

DatabaseUser

Field	Type	Direction	Required by schema	Constraints
id	UUID string	response	no	—
database	resource ID	request/response	yes	—
database_name	string	response	no	—
username	string	request/response	yes	max_length: 63
permissions	enum	request/response	no	values: read, write, admin
is_active	boolean	request/response	no	—
created_at	timestamp	response	no	—
updated_at	timestamp	response	no	—
last_used_at	timestamp	response	no	nullable

DatabaseUserCreate

Field	Type	Direction	Required by schema	Constraints
username	string	request/response	yes	max_length: 63
password	string	request	no	—
permissions	enum	request/response	no	default: read; values: read, write, admin

DatabaseRestore

Field	Type	Direction	Required by schema	Constraints
id	UUID string	response	no	—
backup	resource ID	response	no	—
target_database	resource ID	response	no	—
status	enum	response	no	values: pending, in_progress, completed, failed
error_message	string	response	no	—
created_at	timestamp	response	no	—
started_at	timestamp	response	no	nullable
completed_at	timestamp	response	no	nullable

DatabaseBackup

Field	Type	Direction	Required by schema	Constraints
id	UUID string	response	no	—
database	resource ID	request/response	yes	—
database_name	string	response	no	—
name	string	request/response	no	max_length: 100; empty string allowed
backup_type	enum	request/response	no	values: manual, scheduled
status	enum	response	no	values: pending, in_progress, completed, failed, restoring
file_size_bytes	BigIntegerField	response	no	—
file_size_mb	number	response	no	—
started_at	timestamp	response	no	nullable
completed_at	timestamp	response	no	nullable
expires_at	timestamp	response	no	nullable
is_expired	boolean	response	no	—
error_message	string	response	no	—
created_at	timestamp	response	no	—
latest_restore	computed	response	no	—

DatabaseMetrics

Field	Type	Direction	Required by schema	Constraints
timestamp	timestamp	request/response	no	—
storage_used_mb	integer	request/response	no	min_value: -9223372036854775808; max_value: 9223372036854775807
active_connections	integer	request/response	no	min_value: -9223372036854775808; max_value: 9223372036854775807
transactions_total	BigIntegerField	request/response	no	min_value: -9223372036854775808; max_value: 9223372036854775807
cache_hit_ratio	number	request/response	no	—
tuples_returned	BigIntegerField	request/response	no	min_value: -9223372036854775808; max_value: 9223372036854775807
tuples_inserted	BigIntegerField	request/response	no	min_value: -9223372036854775808; max_value: 9223372036854775807
tuples_updated	BigIntegerField	request/response	no	min_value: -9223372036854775808; max_value: 9223372036854775807
tuples_deleted	BigIntegerField	request/response	no	min_value: -9223372036854775808; max_value: 9223372036854775807

HealthCheck

Field	Type	Direction	Required by schema	Constraints
status	string	request/response	yes	—
connection	boolean	request/response	yes	—
accepting_connections	boolean	request/response	yes	—
message	string	request/response	yes	—

DatabaseClone

Field	Type	Direction	Required by schema	Constraints
new_display_name	string	request/response	yes	max_length: 100
workspace	UUID string	request/response	no	—

PlanStatus

Field	Type	Direction	Required by schema	Constraints
limits	object	request/response	yes	—
usage	object	request/response	yes	—

BackupSchedule

Field	Type	Direction	Required by schema	Constraints
id	UUID string	response	no	—
database	resource ID	request/response	yes	—
database_name	string	response	no	—
name	string	request/response	no	max_length: 100; empty string allowed
frequency	enum	request/response	no	values: hourly, daily, weekly, monthly
hour	integer	request/response	no	min_value: -9223372036854775808; max_value: 9223372036854775807
minute	integer	request/response	no	min_value: -9223372036854775808; max_value: 9223372036854775807
day_of_week	integer	request/response	no	min_value: -9223372036854775808; max_value: 9223372036854775807; nullable
day_of_month	integer	request/response	no	min_value: -9223372036854775808; max_value: 9223372036854775807; nullable
retention_count	integer	request/response	no	min_value: -9223372036854775808; max_value: 9223372036854775807
is_active	boolean	request/response	no	—
last_run_at	timestamp	response	no	nullable
next_run_at	timestamp	response	no	nullable
last_run_status	string	response	no	—
created_at	timestamp	response	no	—
updated_at	timestamp	response	no	—

DeveloperAccessToken

Field	Type	Direction	Required by schema	Constraints
id	UUID string	response	no	—
name	string	request/response	yes	min_length: 3; max_length: 255
token_prefix_display	string	response	no	—
scopes	array	request	yes	—
scope_list	array	response	no	—
created_at	timestamp	response	no	—
expires_at	timestamp	request/response	no	nullable
last_used_at	timestamp	response	no	nullable
last_used_ip	IPAddressField	response	no	nullable
is_active	boolean	response	no	—
is_expired	boolean	response	no	—
token	string	response	no	—
expires_in_days	integer	request	no	min_value: 1; max_value: 365; default: 30

UserActionLog

Field	Type	Direction	Required by schema	Constraints
id	UUID string	response	no	—
user_id	string	response	no	—
username	string	response	no	nullable
action	string	response	no	—
resource_type	string	response	no	—
resource_id	string	response	no	nullable
resource_name	string	response	no	nullable
details	JSON value	response	no	—
ip_address	IPAddressField	response	no	nullable
created_at	timestamp	response	no	—

Computed fields and endpoint overrides

• Workspace counts are integers. Member/invitation email lookups can return null; an unavailable display email does not change the account ID.
• Database.allowlist_enforced is boolean; user_count and backup_count are integers. Database host metadata is not a substitute for the public connection endpoint.
• The connection response also contains engine, and Redis adds key_prefix. Use actual returned values, including TLS options.
• Creation assigns workspace owner_id, database workspace, database-user database, backup database and schedule database. Do not add them to request bodies merely because a reusable schema lists them.
• Database creation accepts the provisioning fields in its operation; cloning accepts new_display_name. Changing metadata is not an engine conversion, resize, workspace move or ownership transfer.
• Token token appears at creation only. scope_list is an array of strings and token_prefix_display is a masked display string. expires_at on token creation is derived from expires_in_days; use that request field.
• Metrics and health endpoints build engine-specific objects; the metrics serializer describes stored samples. Query/table results also depend on the engine.