> For the complete documentation index, see [llms.txt](https://docs.kinesis.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kinesis.network/api/conventions.md).

# 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](https://4256139742-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fobv1L4EfK71xeiC2NpU7%2Fuploads%2FgGXKmhKy3DIMEXqyyvgv%2Fkinesis-api-v1-openapi-1.5.0.json?alt=media) 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.

| Identifier                  | Format                                     | Obtain it from               |
| --------------------------- | ------------------------------------------ | ---------------------------- |
| 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](/api/authentication.md).

## 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.

The server’s `addedBy` field identifies who added it to the organization. It is null when nobody is recorded, for another organization’s server, or without `members:read`. It does not change server identifiers or ownership.

`GranteeList.ownerEmail` has been removed. Use the organization and member/access fields instead of depending on an individual resource owner.

## 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.

```bash
curl --get https://api.kinesis.network/v1/projects \
  -H "Authorization: Bearer $KINESIS_API_KEY" \
  --data-urlencode 'limit=50' \
  --data-urlencode "cursor=$NEXT_CURSOR"
```

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.

```mermaid
flowchart LR
  A[Submit deployment] --> B{Source}
  B -->|Image| C[Read app status]
  B -->|GitHub| D[Poll build]
  D -->|Succeeded| C
  D -->|Failed| E[Read build error and logs]
  C --> F{Ready endpoint?}
  F -->|Yes| G[Use returned address]
  F -->|No| H[Inspect state and errors]
  H --> C
```

For builds and orders, follow `pollAfterSec` where it is returned. Avoid tight polling loops.

## Idempotency

These operations accept `Idempotency-Key` in the request header:

| Operation           | Endpoint                          |
| ------------------- | --------------------------------- |
| 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.

{% hint style="warning" %}
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.
{% endhint %}

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.

| Header                  | Meaning                                  |
| ----------------------- | ---------------------------------------- |
| `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 null environment value preserves an existing variable; a new variable still needs a value. This also lets OpenAI-profile clients preserve credential-like values hidden from reads. Serialize app configuration changes when more than one client can write to the same app.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.kinesis.network/api/conventions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.