Skip to main content
Use these conventions across KODE API integrations. Individual endpoint pages document limits or behavior that differ for a specific resource.

Base URL and version

Version one resources use:
Build paths from this base URL. Do not remove the /api/v1 segment.

Request format

Send and receive JSON unless an endpoint documents another media type.
You do not need Content-Type for requests without a body. Attachment endpoints can require multipart/form-data or base64-encoded JSON.

Pagination

List endpoints commonly accept page and limit.
integer
default:"1"
Page number to retrieve. The first page is 1.
integer
default:"50"
Maximum number of items to return. Some endpoints support up to 200.
Paginated responses commonly include:
array
required
Resources returned for the current page.
integer
required
Total number of matching resources.
integer
required
Maximum number of resources returned per page.
integer
required
Current page number.
integer
required
Total number of available pages.
Stop requesting pages when page equals pageCount. Do not infer completion from a short page when the response provides pagination metadata.

Rate limits

KODE applies concurrent rolling limits per environment, such as acme.kodelabs.com. Every request that reaches the gateway counts, including requests that return 4xx or 5xx. Exceeding any window returns 429 Too Many Requests.
Queue requests per environment and add random jitter to retries. This prevents multiple workers from retrying at the same time.

Retry failed requests

Retry transient failures such as 429, 502, 503, and 504. Use increasing delays with jitter and a maximum retry count. Do not automatically retry a write unless you know the operation is safe to repeat. Read the resource after an ambiguous failure before resubmitting a create or update.
retry.js

Handle HTTP status codes

Log the HTTP method, path, status, duration, and a correlation identifier when available. Redact tokens, assertions, private keys, and sensitive payload fields.

Work with identifiers

Treat resource identifiers as opaque strings. Do not parse identifiers or depend on their length and format. Retrieve identifiers from list or lookup endpoints before calling a dependent endpoint. For example, list buildings before requesting devices for a building.

Work with time

Use ISO 8601 timestamps where an endpoint accepts date and time strings. Timeseries ingestion endpoints can require Unix epoch timestamps. Preserve the source timestamp and timezone. Do not substitute the ingestion time for the measurement time.

Next steps

Guides

Follow end-to-end workflows for common integrations.

API reference

Browse every endpoint and try requests in the playground.
Last modified on November 10, 2026