Request conventions
Request encoding, pagination, idempotency, rate limits and asynchronous operations.
URLs and request bodies
All resource paths in the reference are relative to https://api.kinesis.network/v1. Download the public OpenAPI specification for the documented operations and provider choices. Use csp=kinesis for Kinesis compute.
GET and DELETE take non-path inputs in the query string. POST and PATCH take a JSON body. Organization selection is the exception: org stays in the query string for every HTTP method. Use Content-Type: application/json when sending a body. The body limit is 1 MiB.
Array query values can be repeated or comma-separated. Booleans accept true/false or 1/0; numeric parameters are converted according to their schema. URL-encode path values, especially names and addresses containing reserved characters.
Most responses are JSON. GET /billing/invoices/{invoiceNumber}/pdf returns binary application/pdf; save it to a file rather than parsing JSON. By contrast, app log export returns JSON containing text, lines and truncated. The text export defaults to a 1 MiB budget and accepts at most 4 MiB; when truncated, newer lines may be missing.
Organization
Permanent URL slug
GET /orgs
Project or app
24-character hexadecimal ID
Project/app listing
Grid
GUID
Grid listing
Server
0x followed by 40 hexadecimal characters
Server listing
Build or provisioning order
Returned string ID
Creation response or listing
Organization selection and resource metadata
Use ?org=<slug> on organization-level operations. Omitting it with several reachable organizations returns org_required and error.details.orgs. GET /projects and GET /apps instead span reachable organizations by default and accept org as a filter. Resource-ID calls on projects, apps and grids resolve their organization from that resource.
Projects and grids name their organization and visibility; projects, apps and grids carry access and createdBy. access describes effective role, outside and isCreator. Creator identities are null without members:read or when the caller is not a member of the resource’s organization. See Authentication and scopes.
Server labels
Use the server response’s name for display and address for subsequent API calls. The caller’s own label takes precedence. A rented marketplace machine otherwise uses its hardware, Kinesis region and address suffix; its hostname, csp, region, zone and instanceType are null. kcRegion remains available for the Kinesis region.
Pagination
For cursor-paginated lists, send limit and use the response's nextCursor in the next request. The usual default is 50 and maximum is 200; check the endpoint for exceptions. Stop only when nextCursor is null. Treat cursors as opaque and retain the same filters while paging.
GitHub browsing, app logs and some catalog endpoints use different result shapes or pagination controls. Their schemas describe those explicitly.
Accepted does not mean ready
App creation returns 201; start, stop, restart and build triggers return 202. A server provisioning dry run returns 200, while a real order returns 202. Inspect the response and poll the corresponding status resource.
For builds and orders, follow pollAfterSec where it is returned. Avoid tight polling loops.
Idempotency
These operations accept Idempotency-Key in the request header:
Create organization
POST /orgs
Create project
POST /projects
Create app
POST /projects/{projectId}/apps
Create grid
POST /grids
Provision servers
POST /servers/provision
Replace server
POST /servers/{address}/replace
Use a unique string of 1–255 characters with no whitespace. Reuse it with the same credential, organization, operation and arguments after a timeout or lost response. A replay sets Idempotent-Replayed: true. Keys are retained for 24 hours.
idempotency_conflict means the same key was used with different arguments. request_in_progress means the original request is still running; wait for retryAfterSec and retry the same request. For server provisioning, use a different key when moving from a dry run to the actual order because the inputs changed.
Idempotency records the completed response. If a process fails after the backend acts but before that response is recorded, a retry can still repeat the action. Inspect the resource or order after an uncertain failure before issuing another create or provisioning request.
Saved-card top-ups use a required idempotencyKey in the JSON body, with their own payment-specific validation. The top-up reference is authoritative. Do not assume every write supports the header: restarting an app or triggering a build again performs another action.
Rate limits and response headers
The default limits are 300 requests per minute per credential and 600 per user across credentials. The response headers describe the effective limit for your request.
X-Request-Id
Identifier for support and diagnostics
X-RateLimit-Limit
Effective request allowance
X-RateLimit-Remaining
Requests remaining in the current window
X-RateLimit-Reset
Window reset time, in Unix seconds
Retry-After
Seconds to wait when supplied
Idempotent-Replayed
True for an idempotent response replay
Rate limiting and authentication are shared by REST and MCP. For MCP, one HTTP request counts as one unit; JSON-RPC batches are rejected.
Configuration updates
App PATCH requests do not use a universal deep-merge rule. Lists such as ports, environment variables and volumes replace the entire list. Hardware and placement objects merge by key; instance bounds must be supplied together; grid priorities replace their map. A secret environment value of null preserves the stored secret. Serialize app configuration changes when more than one client can write to the same app.
Was this helpful?