> 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%2Fq3IkP1awx0kPSmh3Mx4v%2Fkinesis-public-openapi.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. 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               |
| --------------------------- | ------------------------------------------ | ---------------------------- |
| 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 |

## 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 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, 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 secret environment value of null preserves the stored secret. 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.