JUST SHIPPEDRuntime 2.4 — a clearer view of every agent
CONTROLPLANE
DOCUMENTATION / SAMPLE API V1

Developer documentation

A clear path
to your first run.

Define the workflow. Set its boundaries. Keep the execution in view. Start with the concepts below and explore the sample API.

This is a documentation design for a fictional platform. The endpoint uses the reserved .example domain. There is no live SDK, API, account system, or backend included.

4 results

Quick start

The sample contract separates configuration from execution. Define what a workflow may do before creating a run.

1

Name the workflow and its boundary.

Give it a version, an explicit tool list, and a stopping condition. This JSON is a complete illustrative definition.

JSON / workflow definition
{
  "name": "support-resolver",
  "version": "2.4.1",
  "model_policy": "balanced-v3",
  "tools": ["search_articles", "draft_reply"],
  "limits": { "max_steps": 8, "timeout_ms": 15000 },
  "on_limit": "human_review"
}

2

Send a request with bounded input.

A real implementation would authenticate the caller, validate input, and enforce the workflow policy on the server. The sample below does not connect to a real service.

API example

Create one execution against a named version. Never embed a real secret in browser code. The token below is deliberately not a credential.

Shell / illustrative request
curl https://api.controlplane.example/v1/runs \
  -H "Authorization: Bearer DEMO_TOKEN_NOT_A_REAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow": "support-resolver",
    "version": "2.4.1",
    "input": { "question": "How do I export a report?" }
  }'

3

Keep the run and trace identifiers.

Use stable identifiers to connect an application request with its execution details. Do not confuse the sample response below with a live result.

JSON / sample response
{
  "run_id": "run_demo_7f28",
  "status": "completed",
  "workflow_version": "2.4.1",
  "trace_id": "tr_demo_9a13",
  "usage": { "steps": 3, "duration_ms": 142 }
}

A policy is an operating contract.

Model choice, tool access, retry behavior, and limits should be reviewable independently of a prompt. In this sample, a run that exhausts its step or time budget returns to human review rather than silently expanding its authority.

Before adapting this documentation to a real service, replace the fictional schema and status vocabulary with the behavior your implementation actually supports. Document validation errors, rate limits, retention, idempotency, and authentication alongside the happy path.

Keep the connector boundary explicit.

An integration adapter translates an approved tool call into the contract of your existing service. Keep authentication server-side, validate the input at that boundary, and define what a repeated request means before allowing retries.

The integration catalog groups sample adapters by purpose. It is a reference layout, not a list of installed or certified third-party connections.

Explore integration patterns

Read the execution, not just its status.

Start with the run ID and workflow version. Follow context retrieval, model generation, and policy validation as separate spans. In the sample trace view, those stages take 38 ms, 89 ms, and 15 ms respectively, totaling 142 ms.

A completed status describes this fictional run. It does not prove that an answer is correct. Keep evaluation outcomes and operational completion as separate concepts, and avoid logging sensitive inputs by default.

Inspect the sample trace Read the boundaries field guide