Evaluate an instruction proposal

curl --request POST \
  --url https://api.checkfu.com/v1/instruction-proposals/{id}/evaluate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'checkfu-version: <checkfu-version>' \
  --data '
{
  "principal": "<string>"
}
'

import requests

url = "https://api.checkfu.com/v1/instruction-proposals/{id}/evaluate"

payload = { "principal": "<string>" }
headers = {
    "checkfu-version": "<checkfu-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'checkfu-version': '<checkfu-version>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({principal: '<string>'})
};

fetch('https://api.checkfu.com/v1/instruction-proposals/{id}/evaluate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.checkfu.com/v1/instruction-proposals/{id}/evaluate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'principal' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "checkfu-version: <checkfu-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.checkfu.com/v1/instruction-proposals/{id}/evaluate"

	payload := strings.NewReader("{\n  \"principal\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("checkfu-version", "<checkfu-version>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.checkfu.com/v1/instruction-proposals/{id}/evaluate")
  .header("checkfu-version", "<checkfu-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"principal\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.checkfu.com/v1/instruction-proposals/{id}/evaluate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["checkfu-version"] = '<checkfu-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"principal\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "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
}

{
  "error": {
    "type": "validation.malformed",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-malformed"
  }
}

{
  "error": {
    "type": "auth.invalid_key",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#auth-invalid-key"
  }
}

{
  "error": {
    "type": "auth.disabled_tenancy",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#auth-disabled-tenancy"
  }
}

{
  "error": {
    "type": "validation.not_found",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-not-found"
  }
}

{
  "error": {
    "type": "runtime.invalid_transition",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#runtime-invalid-transition"
  }
}

{
  "error": {
    "type": "model.no_eligible_model",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#model-no-eligible-model"
  }
}

{
  "error": {
    "type": "budget.exceeded",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#budget-exceeded"
  }
}

{
  "error": {
    "type": "runtime.internal",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#runtime-internal"
  }
}

Evaluate an instruction proposal

Run the bounded holdout pair: baseline and candidate replay the source Outcome’s own task and rubric in two ordinary isolated Sessions, one graded iteration each, and their verdicts reconcile from those Sessions’ event logs. Candidate text reaches exactly one place before apply — each holdout Session’s own graded context. Requires a drafted or evaluation_failed proposal plus the requester Principal for the evaluation Sessions. Returns the InstructionProposal in evaluating; 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

instruction-proposals

{id}

evaluate

Evaluate an instruction proposal

curl --request POST \
  --url https://api.checkfu.com/v1/instruction-proposals/{id}/evaluate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'checkfu-version: <checkfu-version>' \
  --data '
{
  "principal": "<string>"
}
'

import requests

url = "https://api.checkfu.com/v1/instruction-proposals/{id}/evaluate"

payload = { "principal": "<string>" }
headers = {
    "checkfu-version": "<checkfu-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'checkfu-version': '<checkfu-version>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({principal: '<string>'})
};

fetch('https://api.checkfu.com/v1/instruction-proposals/{id}/evaluate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.checkfu.com/v1/instruction-proposals/{id}/evaluate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'principal' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "checkfu-version: <checkfu-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.checkfu.com/v1/instruction-proposals/{id}/evaluate"

	payload := strings.NewReader("{\n  \"principal\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("checkfu-version", "<checkfu-version>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.checkfu.com/v1/instruction-proposals/{id}/evaluate")
  .header("checkfu-version", "<checkfu-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"principal\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.checkfu.com/v1/instruction-proposals/{id}/evaluate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["checkfu-version"] = '<checkfu-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"principal\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "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
}

{
  "error": {
    "type": "validation.malformed",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-malformed"
  }
}

{
  "error": {
    "type": "auth.invalid_key",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#auth-invalid-key"
  }
}

{
  "error": {
    "type": "auth.disabled_tenancy",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#auth-disabled-tenancy"
  }
}

{
  "error": {
    "type": "validation.not_found",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-not-found"
  }
}

{
  "error": {
    "type": "runtime.invalid_transition",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#runtime-invalid-transition"
  }
}

{
  "error": {
    "type": "model.no_eligible_model",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#model-no-eligible-model"
  }
}

{
  "error": {
    "type": "budget.exceeded",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#budget-exceeded"
  }
}

{
  "error": {
    "type": "runtime.internal",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#runtime-internal"
  }
}

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-27

idempotency-key

string

Maximum string length: 255

Path Parameters

string

required

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

Body

application/json

principal

string

required

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

Response

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

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

Developer tools

Canonical tables

Author protocols

Generated HTTP API

Evaluate an instruction proposal

Authorizations

Headers

Path Parameters

Body

Response