# API overview

Klineo’s v2 API connects project discovery, issuer planning, deterministic studies, treasury records, proposal review and verifiable evidence. Its base path is `/api/liquidity-studio/v2` on your API deployment. Set the API origin supplied by your workspace administrator; `docs.klineo.io` serves documentation.

The [API reference](/api-reference/overview/) is generated from the committed OpenAPI 3.1 contract. It includes every operation, its authentication alternatives, headers, body, response statuses and named schemas. [Download the OpenAPI document](/openapi/liquidity-operating-system-v2.openapi.json) for contract tooling.

## Choose the right integration surface

The full API includes three access patterns. Public discovery operations explicitly declare anonymous access; other published resources may omit an authentication declaration in the contract and still depend on deployment configuration. Private application workflows use the `__Host-klineo_session` production cookie (`klineo_session` in development) and workspace access. Service integrations use OAuth client credentials only on operations that declare `serviceCredential` authentication.

A service token does not provide access to every route. For example, study reads declare `studies:read` and study creation declares `studies:write`. Agent research and many treasury workflows are session-only. Check the authentication section for the exact operation before choosing an SDK call or raw HTTP request.

## Authenticate a service integration

Create an authorized developer credential through the workspace. Store its client secret in your server’s secret manager. Exchange the client ID and secret using HTTP Basic authentication at `/oauth/token`; send `grant_type=client_credentials` as a form field, the workspace’s organization header, and the scopes you need. The contract describes a scoped token with a one-hour lifetime. Use the returned expiry rather than assuming a token stays valid.

```bash
curl --request POST "$KLINEO_API_ORIGIN/api/liquidity-studio/v2/oauth/token" \
  --user "$KLINEO_CLIENT_ID:$KLINEO_CLIENT_SECRET" \
  --header "x-klineo-organization-id: $KLINEO_ORGANIZATION_ID" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "scope=studies:read"
```

The variables in this example are your deployment origin, client credential and authorized organization ID. The origin excludes the API base path. Keep these values in a server environment; do not put client secrets in browser code, source control or documentation examples.

```bash
curl "$KLINEO_API_ORIGIN/api/liquidity-studio/v2/studies?limit=20" \
  --header "Authorization: Bearer $KLINEO_ACCESS_TOKEN" \
  --header "x-klineo-organization-id: $KLINEO_ORGANIZATION_ID"
```

The organization header selects a workspace. It does not independently grant membership or cross-workspace access. The credential must be authorized for that workspace and scope.

## Pagination and resource versions

List operations that declare pagination accept `limit` from 1 to 100, with a contract default of 50, and an opaque `cursor`. Return the received `meta.nextCursor` unchanged when `meta.hasMore` is true. Individual operations can declare different parameters; check their reference.

Resources commonly return a `data` envelope, with a `RecordEnvelope` carrying immutable version information and a typed `payload`. Some workflows return a specialized result or asynchronous job instead. Use the response schema for the operation rather than assuming every result has the same shape.

## Mutations and concurrency

Send `Idempotency-Key` where the operation requires it. The common contract length is 8 to 160 characters. Preserve a key when retrying the same intended request; use a different key for a different action. Check an operation’s parameters before retrying a mutation.

Versioned mutations can require a strong `If-Match` value. Preserve the exact quoted version supplied by the API. Some operations also require resource-version hashes in their body to bind dependent inputs. A version conflict means the state must be read and reviewed again before constructing a fresh action; do not replace a stale precondition automatically.

## Read declared errors and runtime state

Response tables show the statuses declared by each operation, including workflow-specific conflicts and unavailable prerequisites. The reference is a contract view; deployment middleware can enforce additional authentication, rate limits and access checks. Read the returned error instead of assuming that a missing status in OpenAPI cannot occur.

Public discovery can return partial source observations and explicit gaps. `/status` reports fail-closed service readiness; a listed operation alone does not prove that a provider, database, issuer Safe, signed release or reconciled execution gateway is currently available.

## Financial authority stays explicit

SDKs and HTTP requests can prepare studies, proposals, policy drafts and evidence workflows. AI output remains non-executable. Issuer Safe authorization and immutable typed adapters remain the financial authority boundary. Recording a proposal’s Safe evidence or a lifecycle transition does not itself broadcast financial execution.

For individual contracts, start with [simulation](/api-reference/simulation/), [proposal review](/api-reference/proposals/), [protected execution planning](/api-reference/protected-execution/) and [proof resources](/api-reference/proof/).