> ## Documentation Index > Fetch the complete documentation index at: https://docs.checkfu.com/llms.txt > Use this file to discover all available pages before exploring further. # 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… ## OpenAPI ````yaml /openapi.json post /v1/instruction-proposals/{id}/evaluate openapi: 3.1.0 info: title: Checkfu API version: '2026-08-31' description: >- Authentication is declared per operation: API-key, runtime, or connector bearer; Automation signature; or credential-free pairing redemption. Every general Checkfu REST request requires the dated `Checkfu-Version` header (one of: 2026-08-31); the three MCP JSON-RPC transports use `MCP-Protocol-Version`, A2A uses `A2A-Version`, and the provider OAuth callback carries neither Checkfu header. API keys resolve one Workspace without a request selector; authenticated responses identify it with `Checkfu-Workspace-Id`. servers: - url: https://api.checkfu.com security: - bearerAuth: [] tags: - name: organizations - name: sourceRepositories - name: tenants - name: workspaces - name: principals - name: principalGroups - name: principalAccessCredentials - name: apiKeys - name: agents - name: harnessRuntime - name: permissionAssignments - name: actionPolicies - name: files - name: memoryStores - name: modelCredentials - name: modelRoutingProfiles - name: toolSources - name: skills - name: skillSources - name: agentBlueprints - name: skillProposals - name: instructionProposals - name: catalog - name: managedTools - name: concepts - name: support - name: connections - name: connectionVaults - name: connectionAssignments - name: connectedRuntimes - name: fileTrees - name: collaboration - name: automationGraphs - name: automations - name: actionApprovals - name: standingApprovals - name: workloadReviewPolicies - name: usage - name: models - name: outcomes - name: budgets - name: billing - name: sessions - name: audit - name: sessionExports - name: runs - name: runnerPools - name: transcripts - name: sessionWatches - name: sessionCapsules - name: sessionTrajectories - name: webhookEndpoints - name: integrationGateway - name: workEnvironments - name: computers - name: computerScreens - name: computerBrowserObservations - name: computerBrowserActions - name: environments - name: computerHeadlessOperations - name: vaults - name: apiMcp - name: a2a paths: /v1/instruction-proposals/{id}/evaluate: post: tags: - instructionProposals summary: Evaluate an instruction proposal description: >- 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, `expected_version` matching that reviewed row, and the requester Principal and CMA Environment for the evaluation Sessions. The service durably reserves that source version, both Session IDs, their Environment, and requester before either launch; resend the same payload and Idempotency-Key after a timeout to resume or return that exact holdout even if an intervening GET reconciled it. Returns the InstructionProposal in `evaluating` or its already-reconciled terminal evaluation state. 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. operationId: instructionProposals.evaluateInstructionProposal parameters: - name: id in: path schema: $ref: '#/components/schemas/InstructionProposalId' required: true - name: checkfu-version in: header schema: type: string enum: - '2026-08-31' required: true - name: idempotency-key in: header schema: type: string allOf: - maxLength: 255 required: false requestBody: content: application/json: schema: type: object properties: expected_version: type: integer exclusiveMinimum: 0 principal: $ref: '#/components/schemas/PrincipalId' environment_id: $ref: '#/components/schemas/EnvironmentId' required: - expected_version - principal additionalProperties: false required: true responses: '200': description: >- 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 content: application/json: schema: $ref: '#/components/schemas/InstructionProposalConsistency_1' headers: checkfu-workspace-id: description: The Workspace resolved from the authenticated bearer credential. required: true schema: $ref: '#/components/schemas/WorkspaceId' '400': description: Typed Checkfu wire error content: application/json: schema: type: object required: - error properties: error: type: object properties: type: type: string enum: - validation.malformed message: type: string more: type: string enum: - >- https://docs.checkfu.com/reference/errors#validation-malformed description: >- Stable public documentation and remedy for this error type. required: - type - message - more additionalProperties: false additionalProperties: false '401': description: Typed Checkfu wire error content: application/json: schema: type: object required: - error properties: error: type: object required: - type - message - more properties: type: type: string enum: - auth.invalid_key message: type: string more: type: string enum: - >- https://docs.checkfu.com/reference/errors#auth-invalid-key description: >- Stable public documentation and remedy for this error type. additionalProperties: false additionalProperties: false '403': description: >- The organization, tenant, or workspace backing this key is administratively disabled. | Deployment governance or retention policy denied the request. content: application/json: schema: anyOf: - type: object required: - error properties: error: type: object properties: type: type: string enum: - auth.disabled_tenancy message: type: string more: type: string enum: - >- https://docs.checkfu.com/reference/errors#auth-disabled-tenancy description: >- Stable public documentation and remedy for this error type. required: - type - message - more additionalProperties: false additionalProperties: false - $ref: '#/components/schemas/PolicyDeniedError' '404': description: >- The requested resource does not exist in the resolved deployment boundary. content: application/json: schema: $ref: '#/components/schemas/ValidationNotFoundError' '409': description: >- The operation is illegal for the resource's current lifecycle state. | The request conflicts with the resource's current state. | An idempotent mutation conflicts with a completed or in-progress request for the same key. content: application/json: schema: anyOf: - $ref: '#/components/schemas/RuntimeInvalidTransitionError' - $ref: '#/components/schemas/ValidationConflictError' - $ref: '#/components/schemas/IdempotencyConflictError' '422': description: No model candidate satisfies the deployment's routing constraints. content: application/json: schema: $ref: '#/components/schemas/ModelNoEligibleModelError' '429': description: Typed Checkfu wire error headers: retry-after: description: >- Delay in seconds for rate limits or deployment quotas with a known release or UTC reset boundary required: false schema: type: integer minimum: 1 content: application/json: schema: type: object required: - error properties: error: type: object required: - type - message - more properties: type: type: string enum: - budget.exceeded message: type: string more: type: string enum: - >- https://docs.checkfu.com/reference/errors#budget-exceeded description: >- Stable public documentation and remedy for this error type. additionalProperties: false additionalProperties: false '500': description: >- An unexpected internal failure occurred; the message contains an opaque incident reference. content: application/json: schema: $ref: '#/components/schemas/RuntimeInternalError' security: - bearerAuth: [] components: schemas: InstructionProposalId: type: string pattern: ^inp_[0-9a-f]{32}$ PrincipalId: type: string pattern: ^prin_[0-9a-f]{32}$ EnvironmentId: type: string pattern: ^env_[0-9a-f]{32}$ InstructionProposalConsistency_1: type: object properties: id: $ref: '#/components/schemas/InstructionProposalId' status: $ref: '#/components/schemas/Union_162' agent: $ref: '#/components/schemas/AgentId' base_draft_revision: type: integer exclusiveMinimum: 0 base_instructions: type: string model_routing_profile_key: type: string pattern: ^[a-z0-9](?:[a-z0-9._-]{0,93})$ judge_model_routing_profile_key: type: string pattern: ^[a-z0-9](?:[a-z0-9._-]{0,93})$ source_session_ids: $ref: '#/components/schemas/Arrays_24' instructions: anyOf: - type: string allOf: - maxLength: 4096 - type: 'null' length_budget: type: integer exclusiveMinimum: 0 deltas: $ref: '#/components/schemas/Union_163' result_instructions: anyOf: - type: string - type: 'null' evaluation_material: $ref: '#/components/schemas/Union_164' evaluations: $ref: '#/components/schemas/Arrays_25' application: $ref: '#/components/schemas/Union_165' published_version: anyOf: - type: integer exclusiveMinimum: 0 - type: 'null' error: anyOf: - type: string enum: - input_session_unavailable - input_sessions_too_large - authoring_failed - internal - type: 'null' usage: $ref: '#/components/schemas/Objects_77' created_at: type: string updated_at: type: string version: type: integer exclusiveMinimum: 0 required: - id - status - agent - base_draft_revision - base_instructions - model_routing_profile_key - judge_model_routing_profile_key - source_session_ids - instructions - length_budget - deltas - result_instructions - evaluation_material - evaluations - application - published_version - error - usage - created_at - updated_at - version additionalProperties: false WorkspaceId: type: string pattern: ^wrkspc_[0-9a-f]{32}$ PolicyDeniedError: type: object properties: error: type: object properties: type: type: string enum: - policy.denied message: type: string more: type: string enum: - https://docs.checkfu.com/reference/errors#policy-denied description: Stable public documentation and remedy for this error type. required: - type - message - more additionalProperties: false required: - error additionalProperties: false description: Deployment governance or retention policy denied the request. ValidationNotFoundError: type: object properties: error: type: object properties: type: type: string enum: - validation.not_found message: type: string more: type: string enum: - https://docs.checkfu.com/reference/errors#validation-not-found description: Stable public documentation and remedy for this error type. required: - type - message - more additionalProperties: false required: - error additionalProperties: false description: >- The requested resource does not exist in the resolved deployment boundary. RuntimeInvalidTransitionError: type: object properties: error: type: object properties: type: type: string enum: - runtime.invalid_transition message: type: string more: type: string enum: - >- https://docs.checkfu.com/reference/errors#runtime-invalid-transition description: Stable public documentation and remedy for this error type. required: - type - message - more additionalProperties: false required: - error additionalProperties: false description: The operation is illegal for the resource's current lifecycle state. ValidationConflictError: type: object properties: error: type: object properties: type: type: string enum: - validation.conflict message: type: string more: type: string enum: - https://docs.checkfu.com/reference/errors#validation-conflict description: Stable public documentation and remedy for this error type. required: - type - message - more additionalProperties: false required: - error additionalProperties: false description: The request conflicts with the resource's current state. IdempotencyConflictError: anyOf: - $ref: '#/components/schemas/ValidationIdempotencyConflictError' - $ref: '#/components/schemas/ValidationIdempotencyInProgressError' description: >- An idempotent mutation conflicts with a completed or in-progress request for the same key. ModelNoEligibleModelError: type: object properties: error: type: object properties: type: type: string enum: - model.no_eligible_model message: type: string more: type: string enum: - >- https://docs.checkfu.com/reference/errors#model-no-eligible-model description: Stable public documentation and remedy for this error type. required: - type - message - more additionalProperties: false required: - error additionalProperties: false description: No model candidate satisfies the deployment's routing constraints. RuntimeInternalError: type: object properties: error: type: object properties: type: type: string enum: - runtime.internal message: type: string more: type: string enum: - https://docs.checkfu.com/reference/errors#runtime-internal description: Stable public documentation and remedy for this error type. required: - type - message - more additionalProperties: false required: - error additionalProperties: false description: >- An unexpected internal failure occurred; the message contains an opaque incident reference. Union_162: type: string enum: - authoring - drafted - authoring_failed - evaluating - evaluated - evaluation_failed - applied - discarded AgentId: type: string pattern: ^agent_[0-9a-f]{32}$ Arrays_24: type: array items: $ref: '#/components/schemas/SessionId' allOf: - minItems: 1 - maxItems: 8 Union_163: anyOf: - type: array items: anyOf: - type: object properties: op: type: string enum: - add after: anyOf: - type: string allOf: - minLength: 1 - maxLength: 1024 - type: 'null' text: type: string allOf: - minLength: 1 - maxLength: 1024 provenance: $ref: '#/components/schemas/Objects_78' required: - op - after - text - provenance additionalProperties: false - type: object properties: op: type: string enum: - replace find: type: string allOf: - minLength: 1 - maxLength: 1024 replace: type: string allOf: - minLength: 1 - maxLength: 1024 provenance: $ref: '#/components/schemas/Objects_78' required: - op - find - replace - provenance additionalProperties: false - type: object properties: op: type: string enum: - retire find: type: string allOf: - minLength: 1 - maxLength: 1024 provenance: $ref: '#/components/schemas/Objects_78' required: - op - find - provenance additionalProperties: false allOf: - minItems: 1 - maxItems: 8 - type: 'null' Union_164: anyOf: - type: object properties: task: type: string allOf: - minLength: 1 - maxLength: 1024 rubric: type: string allOf: - minLength: 1 - maxLength: 2048 required: - task - rubric additionalProperties: false - type: 'null' Arrays_25: type: array items: $ref: '#/components/schemas/InstructionEvaluationDistinctSessions' allOf: - maxItems: 4 Union_165: anyOf: - type: object properties: agent_version: type: integer exclusiveMinimum: 0 draft_revision: type: integer exclusiveMinimum: 0 applied_at: type: string required: - agent_version - draft_revision - applied_at additionalProperties: false - type: 'null' Objects_77: type: object properties: input_tokens: type: integer minimum: 0 cached_input_tokens: type: integer minimum: 0 cache_write_input_tokens: type: integer minimum: 0 output_tokens: type: integer minimum: 0 reasoning_output_tokens: type: integer minimum: 0 total_tokens: type: integer minimum: 0 required: - input_tokens - cached_input_tokens - cache_write_input_tokens - output_tokens - reasoning_output_tokens - total_tokens additionalProperties: false ValidationIdempotencyConflictError: type: object properties: error: type: object properties: type: type: string enum: - validation.idempotency_conflict message: type: string more: type: string enum: - >- https://docs.checkfu.com/reference/errors#validation-idempotency-conflict description: Stable public documentation and remedy for this error type. required: - type - message - more additionalProperties: false required: - error additionalProperties: false description: The Idempotency-Key is already bound to a different request. ValidationIdempotencyInProgressError: type: object properties: error: type: object properties: type: type: string enum: - validation.idempotency_in_progress message: type: string more: type: string enum: - >- https://docs.checkfu.com/reference/errors#validation-idempotency-in-progress description: Stable public documentation and remedy for this error type. required: - type - message - more additionalProperties: false required: - error additionalProperties: false description: >- An identical idempotent request is still in progress and may be retried later. SessionId: type: string pattern: ^sess_[0-9a-f]{32}$ Objects_78: type: object properties: sources: type: array items: type: object properties: session: $ref: '#/components/schemas/SessionId' event: $ref: '#/components/schemas/EventId' required: - session - event additionalProperties: false allOf: - maxItems: 8 note: anyOf: - type: string allOf: - maxLength: 512 - type: 'null' required: - sources - note additionalProperties: false InstructionEvaluationDistinctSessions: type: object properties: baseline_session: $ref: '#/components/schemas/SessionId' candidate_session: $ref: '#/components/schemas/SessionId' source_version: type: integer exclusiveMinimum: 0 environment_id: $ref: '#/components/schemas/EnvironmentId' principal: $ref: '#/components/schemas/PrincipalId' started_at: type: string result: anyOf: - type: object properties: baseline: $ref: '#/components/schemas/Union_159' candidate: $ref: '#/components/schemas/Union_159' improved: type: boolean baseline_cost_tokens: anyOf: - type: integer minimum: 0 - type: 'null' candidate_cost_tokens: anyOf: - type: integer minimum: 0 - type: 'null' completed_at: type: string required: - baseline - candidate - improved - baseline_cost_tokens - candidate_cost_tokens - completed_at additionalProperties: false - type: 'null' required: - baseline_session - candidate_session - started_at - result additionalProperties: false EventId: type: string pattern: ^evt_[0-9a-f]{32}$ Union_159: type: string enum: - satisfied - needs_revision - max_iterations_reached - failed - interrupted securitySchemes: bearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.