Klineo/Docs
Open app ↗
Documentation/API reference

API reference

Agent runs and research

API v2·View Markdown ↗

Paths on this page are relative to /api/liquidity-studio/v2. Authentication and required headers vary by operation.

API reference overview · OpenAPI download

Operations on this page#

Method Path Operation
GET /agent-runs/{runId}/research-planning getResearchPlanning
GET /agent-runs/{runId}/research-progress getResearchProgress
GET /agent-runs/{runId}/research-trials/{trialKey} getResearchTrialInput
GET /agent-runs/{runId}/result getAgentRunResult
GET /agent-runs/{runId}/evidence/{evidenceId} getAgentRunEvidence
POST /agent-runs/{runId}/commands applyAgentRunCommand
POST /agent-runs startHealthAgentRun
GET /agent-runs listAgentRuns
GET /agent-runs/{runId} getAgentRun
GET /agent-runs/{runId}/events listAgentRunEvents

Read current private Research proposal, clarification and linked study task#

GET /agent-runs/{runId}/research-planning

Operation ID: getResearchPlanning

Authentication: __Host-klineo_session cookie (sessionCookie)

Parameters#

Name Location Required Type Description and constraints
x-klineo-organization-id header Yes string —
runId path Yes string Pattern: ^[a-zA-Z0-9][a-zA-Z0-9:_-]{2,159}$

Responses#

Status Description Content type and schema
200 Current tenant-authorized projection. Activity has no model reasoning or raw evidence. application/json: object
400 Invalid query or cursor No response body declared
401 Session required No response body declared
403 Current workspace access denied No response body declared
404 Run is unavailable in this workspace No response body declared
503 Recovery data temporarily unavailable No response body declared

200 response headers

Header Required Type Description and constraints
Cache-Control Yes Constant private, no-store —

200 application/json body

object — Additional properties rejected

Field Required at this level Type Description and constraints
data Yes ResearchPlanningState —

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

Read current private Research child-study progress#

GET /agent-runs/{runId}/research-progress

Operation ID: getResearchProgress

Authentication: __Host-klineo_session cookie (sessionCookie)

Parameters#

Name Location Required Type Description and constraints
x-klineo-organization-id header Yes string —
runId path Yes string Pattern: ^[a-zA-Z0-9][a-zA-Z0-9:_-]{2,159}$

Responses#

Status Description Content type and schema
200 Current tenant-authorized projection. Activity has no model reasoning or raw evidence. application/json: object
400 Invalid query or cursor No response body declared
401 Session required No response body declared
403 Current workspace access denied No response body declared
404 Run is unavailable in this workspace No response body declared
503 Recovery data temporarily unavailable No response body declared

200 response headers

Header Required Type Description and constraints
Cache-Control Yes Constant private, no-store —

200 application/json body

object — Additional properties rejected

Field Required at this level Type Description and constraints
data Yes ResearchProgress —

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

Inspect the exact immutable inputs of a private Research study#

GET /agent-runs/{runId}/research-trials/{trialKey}

Operation ID: getResearchTrialInput

Authentication: __Host-klineo_session cookie (sessionCookie)

Parameters#

Name Location Required Type Description and constraints
x-klineo-organization-id header Yes string —
runId path Yes string Pattern: ^[a-zA-Z0-9][a-zA-Z0-9:_-]{2,159}$
trialKey path Yes string Allowed: baseline, alternative-1, alternative-2, alternative-3

Responses#

Status Description Content type and schema
200 Current tenant-authorized projection. Activity has no model reasoning or raw evidence. application/json: object
400 Invalid query or cursor No response body declared
401 Session required No response body declared
403 Current workspace access denied No response body declared
404 Run is unavailable in this workspace No response body declared
503 Recovery data temporarily unavailable No response body declared

200 response headers

Header Required Type Description and constraints
Cache-Control Yes Constant private, no-store —

200 application/json body

object — Additional properties rejected

Field Required at this level Type Description and constraints
data Yes ResearchTrialInput —

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

Read and revalidate a saved Health, Proposal Review or Research report#

GET /agent-runs/{runId}/result

Operation ID: getAgentRunResult

Authentication: __Host-klineo_session cookie (sessionCookie)

Interactive tenant-authorized read. Returns the immutable vault or public-project Health report, or saved Proposal Review report, after deterministic verification against its sealed capture and settled model draft. Applicability is separate from the historical report. Public-project results contain at most two frozen public observations; comparison of saved samples is not a continuous-period measurement or causal explanation. PARTIAL and ABSTAINED reports do not assess market health or grant financial authority. Proposal Review requires current narrow review authority and exposes recorded proposal evidence, exact atomic flows where available, cost gaps and current applicability; it never approves or executes a proposal. Research reports reconstruct the comparison from the immutable protocol and completed child receipts; COMPLETED describes modeled work, not financial assurance. Failed and incompatible trials remain visible. Unavailable or unverifiable results fail closed.

Parameters#

Name Location Required Type Description and constraints
x-klineo-organization-id header Yes string —
runId path Yes string Pattern: ^[a-zA-Z0-9][a-zA-Z0-9:_-]{2,159}$

Responses#

Status Description Content type and schema
200 Current tenant-authorized projection. Activity has no model reasoning or raw evidence. application/json: object
400 Invalid query or cursor No response body declared
401 Session required No response body declared
403 Current workspace access denied No response body declared
404 Run is unavailable in this workspace No response body declared
503 Recovery data temporarily unavailable No response body declared

200 response headers

Header Required Type Description and constraints
Cache-Control Yes Constant private, no-store —

200 application/json body

object — Additional properties rejected

Field Required at this level Type Description and constraints
data Yes AgentRunResult —

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

Read allowlisted fields from a sealed Health evidence record#

GET /agent-runs/{runId}/evidence/{evidenceId}

Operation ID: getAgentRunEvidence

Authentication: __Host-klineo_session cookie (sessionCookie)

Interactive tenant-authorized read. Evidence is the frozen captured generation, never refreshed source data. Only scalar fields from the strict source allowlists are returned; internal authorization classifications, signatures, credentials and arbitrary payload objects are excluded. Recorded source assertions are not independent verification.

Parameters#

Name Location Required Type Description and constraints
x-klineo-organization-id header Yes string —
runId path Yes string Pattern: ^[a-zA-Z0-9][a-zA-Z0-9:_-]{2,159}$
evidenceId path Yes string Pattern: ^[a-zA-Z0-9][a-zA-Z0-9:_-]{2,159}$

Responses#

Status Description Content type and schema
200 Current tenant-authorized projection. Activity has no model reasoning or raw evidence. application/json: object
400 Invalid query or cursor No response body declared
401 Session required No response body declared
403 Current workspace access denied No response body declared
404 Run is unavailable in this workspace No response body declared
503 Recovery data temporarily unavailable No response body declared

200 response headers

Header Required Type Description and constraints
Cache-Control Yes Constant private, no-store —

200 application/json body

object — Additional properties rejected

Field Required at this level Type Description and constraints
data Yes CapturedHealthEvidenceView —

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

Cancel remaining work or answer a persisted clarification as its requester#

POST /agent-runs/{runId}/commands

Operation ID: applyAgentRunCommand

Authentication: __Host-klineo_session cookie (sessionCookie)

Interactive requester only; current tenant/workflow authority is rechecked atomically. Retry an unconfirmed command with the identical body, If-Match and Idempotency-Key. Receipt state is the accepted command outcome, not a claim about current worker progress. Cancellation preserves settled work and does not undo external work already sent.

Parameters#

Name Location Required Type Description and constraints
x-klineo-organization-id header Yes string —
runId path Yes string Pattern: ^[a-zA-Z0-9][a-zA-Z0-9:_-]{2,159}$
If-Match header Yes string Pattern: ^"0x[0-9a-f]{64}"$
Idempotency-Key header Yes string Min length: 8; Max length: 200

Request body#

Required: yes.

application/json

AgentControlCommand

Responses#

Status Description Content type and schema
200 Current tenant-authorized projection. Activity has no model reasoning or raw evidence. application/json: object
400 Invalid query or cursor No response body declared
401 Session required No response body declared
403 Current workspace access denied No response body declared
404 Run is unavailable in this workspace No response body declared
409 Command key conflicts or run is terminal; refresh before a new command No response body declared
412 Run or clarification changed; refresh before a new command No response body declared
428 Strong current run If-Match required No response body declared
429 Remaining checkpoint budget exhausted No response body declared
503 Recovery data temporarily unavailable No response body declared

200 response headers

Header Required Type Description and constraints
Cache-Control Yes Constant private, no-store —

200 application/json body

object — Additional properties rejected

Field Required at this level Type Description and constraints
data Yes AgentControlReceipt —

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

Admit a bounded Health, Proposal Review or Research task against an exact source version#

POST /agent-runs

Operation ID: startHealthAgentRun

Authentication: __Host-klineo_session cookie (sessionCookie)

The existing operation identifier is retained for SDK compatibility. Interactive member only. Admission checks deployment enablement, current delegated authority, tenant policy, source version and quotas. Provider assignment and profile eligibility are checked when the worker prepares model work. The caller cannot choose tools, model, budgets, organization or requester. Vault Health uses fully closed UTC-day windows; public-project Health binds saved samples. Proposal Review binds an exact V1 updatedAt, V2 resourceVersion or Research candidate Decision Pack resourceVersion plus contentHash and uses narrow ai:proposal-review authority; it does not grant general AI generation or simulation rights to an approver. Research accepts an explicit reviewed experiment or a PLAN request containing a question and explicit optional assumptions, with exact issuer-intent version and simulation authority. PLAN reserves model resources but no study compute; typed confirmation creates a separately linked execution task. It runs a private baseline plus at most three alternatives, without signed-study or publication side effects. Retry uncertain admission with the identical body and key. A receipt means accepted work, not a completed report; recover progress using the returned run ID. No proposal, approval, comment, payment or financial transaction is created or changed by this endpoint.

Parameters#

Name Location Required Type Description and constraints
x-klineo-organization-id header Yes string —
Idempotency-Key header Yes string Min length: 8; Max length: 200

Request body#

Required: yes.

application/json

AgentAdmissionRequest

Responses#

Status Description Content type and schema
200 The identical admission was recovered; read current task state separately. application/json: object
202 A new bounded investigation was atomically admitted. application/json: object
400 Invalid or unsupported request. application/json: object
401 Interactive session required. application/json: object
403 Current authority does not permit the investigation. application/json: object
404 Subject unavailable in this workspace. application/json: object
409 Idempotency key belongs to a different request. application/json: object
412 Reviewed source generation or window changed. application/json: object
428 Reviewed subject version is required. application/json: object
429 Workspace allowance or active limit reached. application/json: object
503 Admission, provider or tenant workflow is unavailable. application/json: object

200 response headers

Header Required Type Description and constraints
Cache-Control Yes Constant private, no-store —
ETag Yes string Pattern: ^"0x[0-9a-f]{64}"$

200 application/json body

object — Additional properties rejected

Field Required at this level Type Description and constraints
data Yes AgentAdmissionReceipt —

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

202 response headers

Header Required Type Description and constraints
Cache-Control Yes Constant private, no-store —
ETag Yes string Pattern: ^"0x[0-9a-f]{64}"$

202 application/json body

object — Additional properties rejected

Field Required at this level Type Description and constraints
data Yes AgentAdmissionReceipt —

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

400 response headers

Header Required Type Description and constraints
Cache-Control Yes Constant private, no-store —

400 application/json body

object — Additional properties rejected

Field Required at this level Type Description and constraints
error Yes ApiError —

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

401 response headers

Header Required Type Description and constraints
Cache-Control Yes Constant private, no-store —

401 application/json body

object — Additional properties rejected

Field Required at this level Type Description and constraints
error Yes ApiError —

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

403 response headers

Header Required Type Description and constraints
Cache-Control Yes Constant private, no-store —

403 application/json body

object — Additional properties rejected

Field Required at this level Type Description and constraints
error Yes ApiError —

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

404 response headers

Header Required Type Description and constraints
Cache-Control Yes Constant private, no-store —

404 application/json body

object — Additional properties rejected

Field Required at this level Type Description and constraints
error Yes ApiError —

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

409 response headers

Header Required Type Description and constraints
Cache-Control Yes Constant private, no-store —

409 application/json body

object — Additional properties rejected

Field Required at this level Type Description and constraints
error Yes ApiError —

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

412 response headers

Header Required Type Description and constraints
Cache-Control Yes Constant private, no-store —

412 application/json body

object — Additional properties rejected

Field Required at this level Type Description and constraints
error Yes ApiError —

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

428 response headers

Header Required Type Description and constraints
Cache-Control Yes Constant private, no-store —

428 application/json body

object — Additional properties rejected

Field Required at this level Type Description and constraints
error Yes ApiError —

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

429 response headers

Header Required Type Description and constraints
Cache-Control Yes Constant private, no-store —

429 application/json body

object — Additional properties rejected

Field Required at this level Type Description and constraints
error Yes ApiError —

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

503 response headers

Header Required Type Description and constraints
Cache-Control Yes Constant private, no-store —

503 application/json body

object — Additional properties rejected

Field Required at this level Type Description and constraints
error Yes ApiError —

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

Recover authorized agent task history#

GET /agent-runs

Operation ID: listAgentRuns

Authentication: __Host-klineo_session cookie (sessionCookie)

Parameters#

Name Location Required Type Description and constraints
x-klineo-organization-id header Yes string —
limit query No integer Default: 25; Minimum: 1; Maximum: 100
cursor query No string Max length: 2048
kind query No string Allowed: HEALTH_INVESTIGATION, PROPOSAL_REVIEW, WHAT_IF_RESEARCH
state query No string Allowed: QUEUED, RUNNING, WAITING_FOR_INPUT, WAITING_FOR_CHILDREN, COMPLETED, PARTIAL, ABSTAINED, FAILED, CANCELLED
subjectRecordType query No string Allowed: VAULT, PROPOSAL, PROPOSAL_WORKSPACE, ISSUER_INTENT, SAVED_PUBLIC_PROJECT, DECISION_PACK
subjectRecordId query No string Pattern: ^[a-zA-Z0-9][a-zA-Z0-9:_-]{2,159}$

Responses#

Status Description Content type and schema
200 Current tenant-authorized projection. Activity has no model reasoning or raw evidence. application/json: object
400 Invalid query or cursor No response body declared
401 Session required No response body declared
403 Current workspace access denied No response body declared
404 Run is unavailable in this workspace No response body declared
503 Recovery data temporarily unavailable No response body declared

200 response headers

Header Required Type Description and constraints
Cache-Control Yes Constant private, no-store —

200 application/json body

object — Additional properties rejected

Field Required at this level Type Description and constraints
data Yes AgentRunList —

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

Read persisted run status and pending clarification#

GET /agent-runs/{runId}

Operation ID: getAgentRun

Authentication: __Host-klineo_session cookie (sessionCookie)

Parameters#

Name Location Required Type Description and constraints
x-klineo-organization-id header Yes string —
runId path Yes string Pattern: ^[a-zA-Z0-9][a-zA-Z0-9:_-]{2,159}$

Responses#

Status Description Content type and schema
200 Current tenant-authorized projection. Activity has no model reasoning or raw evidence. application/json: object
400 Invalid query or cursor No response body declared
401 Session required No response body declared
403 Current workspace access denied No response body declared
404 Run is unavailable in this workspace No response body declared
503 Recovery data temporarily unavailable No response body declared

200 response headers

Header Required Type Description and constraints
Cache-Control Yes Constant private, no-store —

200 application/json body

object — Additional properties rejected

Field Required at this level Type Description and constraints
data Yes AgentRunDetail —

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

Read recorded run and checkpoint transitions#

GET /agent-runs/{runId}/events

Operation ID: listAgentRunEvents

Authentication: __Host-klineo_session cookie (sessionCookie)

Parameters#

Name Location Required Type Description and constraints
x-klineo-organization-id header Yes string —
runId path Yes string Pattern: ^[a-zA-Z0-9][a-zA-Z0-9:_-]{2,159}$
after query No string Default: 0; Pattern: ^(0|[1-9][0-9]{0,18})$
limit query No integer Default: 50; Minimum: 1; Maximum: 100

Responses#

Status Description Content type and schema
200 Current tenant-authorized projection. Activity has no model reasoning or raw evidence. application/json: object
400 Invalid query or cursor No response body declared
401 Session required No response body declared
403 Current workspace access denied No response body declared
404 Run is unavailable in this workspace No response body declared
503 Recovery data temporarily unavailable No response body declared

200 response headers

Header Required Type Description and constraints
Cache-Control Yes Constant private, no-store —

200 application/json body

object — Additional properties rejected

Field Required at this level Type Description and constraints
data Yes AgentActivityPage —

Nested required fields apply when their parent object or matching union branch is present. Named types link to their complete schema.

↑ ↓ to navigate · Enter to open · Esc to close