Author an instruction proposal

Start a model-curated reflection job over outcome-bearing source Session logs, where needs_revision and failed grader verdicts are the richest signal. The artifact is an ordered set of span-addressed deltas against one Agent draft revision, each citing the verdict events that justify it, under a hard result-length budget — never a wholesale rewrite. The reflection model_routing_profile_key must differ from the route the Outcome grader judges through, and each source Session may appear at most once. Returns the InstructionProposal in authoring; accepts an optional Idempotency-Key.

Checkfu support posture: alpha; hosted. Required evidence journey: skill-delivery. Deployment-specific readiness and the latest proven release are available from GET /v1/support/capabilities.

POST /v1/instruction-proposals

Author an instruction proposal

cURL

curl --request POST \
  --url https://api.checkfu.com/v1/instruction-proposals \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'checkfu-version: <checkfu-version>' \
  --data '
{
  "agent": "<string>",
  "source_session_ids": [
    "<string>"
  ],
  "model_routing_profile_key": "<string>",
  "instructions": "<string>",
  "length_budget": 1408
}
'

201

{
  "id": "<string>",
  "status": "authoring",
  "agent": "<string>",
  "base_draft_revision": 1,
  "base_instructions": "<string>",
  "model_routing_profile_key": "<string>",
  "judge_model_routing_profile_key": "<string>",
  "source_session_ids": [
    "<string>"
  ],
  "instructions": "<string>",
  "length_budget": 1,
  "deltas": [
    {
      "op": "add",
      "after": "<string>",
      "text": "<string>",
      "provenance": {
        "sources": [
          {
            "session": "<string>",
            "event": "<string>"
          }
        ],
        "note": "<string>"
      }
    }
  ],
  "result_instructions": "<string>",
  "evaluation_material": {
    "task": "<string>",
    "rubric": "<string>"
  },
  "evaluations": [
    {
      "baseline_session": "<string>",
      "candidate_session": "<string>",
      "started_at": "<string>",
      "result": {
        "baseline": "satisfied",
        "candidate": "satisfied",
        "improved": true,
        "baseline_cost_tokens": 1,
        "candidate_cost_tokens": 1,
        "completed_at": "<string>"
      }
    }
  ],
  "application": {
    "agent_version": 1,
    "draft_revision": 1,
    "applied_at": "<string>"
  },
  "published_version": 1,
  "error": "input_session_unavailable",
  "usage": {
    "input_tokens": 1,
    "cached_input_tokens": 1,
    "cache_write_input_tokens": 1,
    "output_tokens": 1,
    "reasoning_output_tokens": 1,
    "total_tokens": 1
  },
  "created_at": "<string>",
  "updated_at": "<string>",
  "version": 1
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

checkfu-version · enum<string> · required

Available options: 2026-08-24

idempotency-key · string

Maximum string length: 255

Body

application/json

agent · string · required

Pattern: ^agent_[0-9a-f]{32}$

source_session_ids · string[] · required

Required array length: 1 - 8 elements

Pattern: ^sess_[0-9a-f]{32}$

model_routing_profile_key · string · required

Pattern: ^[a-z0-9](?:[a-z0-9._-]{0,93})$

instructions · string

Required string length: 1 - 4096

length_budget · integer

Required range: 256 <= x <= 2560

Response

201

application/json

distinct reflection and judge bindings, an error exactly on authoring failure, an artifact exactly past authoring, an application exactly on applied, a published version only after application, and evaluation states only with a recorded comparison

id · string · required

Pattern: ^inp_[0-9a-f]{32}$

status · enum<string> · required

Available options: authoring, drafted, authoring_failed, evaluating, evaluated, evaluation_failed, applied, discarded

agent · string · required

Pattern: ^agent_[0-9a-f]{32}$

base_draft_revision · integer · required

Required range: x > 0

base_instructions · string · required

model_routing_profile_key · string · required

Pattern: ^[a-z0-9](?:[a-z0-9._-]{0,93})$

judge_model_routing_profile_key · string · required

Pattern: ^[a-z0-9](?:[a-z0-9._-]{0,93})$

source_session_ids · string[] · required

Required array length: 1 - 8 elements

Pattern: ^sess_[0-9a-f]{32}$

instructions · string | null · required

Maximum string length: 4096

length_budget · integer · required

Required range: x > 0

deltas · object[] | null · required

Required array length: 1 - 8 elements

Option 1

Option 2

Option 3

Show child attributes

result_instructions · string | null · required

evaluation_material · object | null · required

Show child attributes

evaluations · object[] · required

Maximum array length: 4

Show child attributes

application · object | null · required

Show child attributes

published_version · integer | null · required

Required range: x > 0

error · enum<string> | null · required

Available options: input_session_unavailable, input_sessions_too_large, authoring_failed, internal

usage · object · required

Show child attributes

created_at · string · required

updated_at · string · required

version · integer · required

Required range: x > 0