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 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 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.
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.
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, proposal review, protected execution planning and proof resources.