Common Structures

This page describes the common patterns, data types, and conventions used throughout the k0rdent API to ensure consistency and predictability.

Response Envelope

All API responses use a consistent discriminated union envelope structure with a success boolean discriminator.

Type Definition

Success Response

Error Response

Meta Object

The meta object is always present in responses and contains request tracking information.

Base Meta Fields

Extended Meta Types

Success responses can extend meta with additional context:

Pagination Meta:

Workflow Meta:

Resource Identifiers

Resources use globally unique, opaque IDs that do NOT contain region information. This decouples resource identity from physical location.

ID Format

Format: {prefix}_{base62}

Resource ID Prefixes

Resource IDs are 26 characters after the prefix, using base62 encoding (case-sensitive).

Request Identifiers

Every API request gets a unique Request ID for tracing, debugging, and correlation across services.

Format

Format: req_{region}-{timestamp}-{entropy}

Example

Components

• req_ - Platform prefix for easy grepping in logs
• sfo1 - Region code where request was processed
• 1770564159296 - Unix timestamp in milliseconds
• 7d4b9e1f3a5b - Random entropy (12 hex characters)

Request IDs are returned in the X-Request-Id response header and meta.requestId field.

Naming Conventions

URL Paths

Field Names

Dates and Timestamps

All temporal fields use ISO 8601 format and are always treated as UTC.

Common Fields

Example

Use of HTTP

HTTP Methods

The k0rdent API uses standard HTTP methods:

Content Type

All requests and responses use Content-Type: application/json unless otherwise specified.

Example Request

Pagination

All list endpoints support two pagination modes: cursor-based and offset-based. The appropriate mode depends on how frequently the underlying data changes.

Choosing a Mode

Cursor mode is recommended for resources that change frequently — active sessions, servers, API keys, clusters, instances, networks. Because the cursor anchors to a stable position in the dataset, inserting or deleting records between requests does not cause items to be skipped or duplicated on subsequent pages.

Offset mode is recommended for stable resources — roles, organizations, projects, providers, policies, groups. Offset allows UIs to display total counts and navigate directly to a page, which is useful when the dataset is bounded and predictable.

pageToken and offset are mutually exclusive. Include one or the other, not both.

Query Parameters

Cursor-Based Example

Use for frequently updated resources (sessions, servers, API keys, clusters):

Response:

nextPageToken is absent when there are no more results. total is not returned in cursor mode.

Offset-Based Example

Use for stable resources (roles, organizations, providers, policies):

Response:

total reflects the full count of matching items, regardless of pageSize. Use it to compute page counts and display "showing X–Y of Z" UI. nextPageToken is not returned in offset mode.

total Field Caveat

total requires a COUNT(*) query on the backend and is only populated when using offset-based pagination. It is omitted (or null) in cursor mode. For large datasets, avoid relying on total in performance-critical paths — consider caching or approximate counts where precision is not required.

Filtering

You can filter resources by most attributes using query parameters:

Simple Filter

Multiple Values

Example Response

All filtered results still use the standard response envelope with pagination.

Sorting

Sort resources in ascending or descending order:

Sort Ascending

Sort Descending

Use - prefix for descending:

Multiple Sort Fields

Field Design Rules

Use Objects Over Primitives

Always wrap values that might grow into objects:

Never Use Booleans for State

States often grow beyond two values:

Use IDs with Optional Expansion

Don't embed full objects - use IDs and let clients request expansion:

Optional Fields

Unpopulated optional data is returned as follows:

• Arrays and Objects may be returned as empty ([], {})
• Number, String, and Boolean types may be returned as null

Clients should handle both null and empty values gracefully.