Skip to main content
POST
Define what done looks like for a session

Authorizations

Authorization
string
header
required

A Recursion API key, created in the console under API keys.

Headers

x-tenant-id
string

Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is default.

Minimum string length: 1
x-organization-id
string

Organization in which to act. Required for a tenant-scoped API key. Optional for an organization-scoped key, where it must name that same organization. The value may be an organization id or default.

Minimum string length: 1

Path Parameters

sessionId
string<uuid>
required

Session id (UUID) returned by managedAgentsStartSessionV2 or managedAgentsListSessionsV2.

Body

application/json

A definition of done for a session. Send criteria, rubric, or rubricFile; rubricFile is exclusive, while criteria and rubric may be sent together only when the rubric parses to exactly those criteria.

criteria
object[]
required

Grading criteria in rubric order. Send criteria, rubric, or rubricFile; rubricFile cannot be combined with either other source. Criteria and rubric can be sent together only when the rubric parses to exactly those criteria, as in a read-back body. Criteria render to at most 256 KiB.

Required array length: 1 - 200 elements
description
string
required

Objective the agent works toward.

Minimum string length: 1
evaluatorAgentId
string

Explicit evaluator for this outcome. If omitted, each pass uses the writer session's current agent version's default evaluator, or the managed grader.

Minimum string length: 1
maxIterations
null | integer<int64>
default:5

Maximum evaluator passes; zero means unbounded. Null inherits the default of five.

Required range: 0 <= x <= 9007199254740991
rubric
string

Deprecated: send criteria. Markdown rubric read into criteria at definition time. Cannot be combined with rubricFile; if sent with criteria, it must parse to exactly those criteria. Criteria render to at most 256 KiB.

Minimum string length: 1
rubricFile
object

File holding the rubric, read into criteria at definition time. Cannot be combined with criteria or rubric. Criteria render to at most 256 KiB. Resolved into rubric and rubricRef on the stored outcome.

Response

Created

createdAt
string<date-time>
required
read-only

RFC 3339 timestamp when the outcome was created.

description
string
required

Objective the writer works toward, in prose.

maxIterations
integer<int64>
required

Maximum evaluator passes; zero explicitly means unbounded.

Required range: -9007199254740991 <= x <= 9007199254740991
organizationId
string
required
read-only

Organization that owns the outcome.

outcomeId
string
required
read-only

Server-assigned outcome identifier (UUID).

rubric
string
required

Deprecated: read criteria. The markdown rubric as it was sent, or the criteria rendered as a keyed markdown rubric when the outcome was defined from a criteria list.

sessionId
string
required
read-only

Writer session this outcome belongs to (UUID).

status
enum<string>
required
read-only

Current outcome lifecycle state, including evaluating while a root pass is in flight.

Available options:
pending,
running,
evaluating,
terminal
updatedAt
string<date-time>
required
read-only

RFC 3339 timestamp of the latest outcome change.

agentId
string
read-only

Writer agent that owns the outcome (UUID).

criteria
object[]

Criteria the writer's work is evaluated against, in rubric order. Absent on an outcome whose historical rubric has no structured form; read rubric for it.

endedAt
string<date-time>
read-only

RFC 3339 timestamp when the outcome became terminal.

evaluations
object[]
read-only

Evaluator verdicts in order, newest last. Only passes that produced a verdict are listed: a pass that could not grade the work is reported by the pass status, and by terminalResult and terminalExplanation when it ended the outcome. A historical pass whose grader session is no longer recorded stays listed here even though it has no evaluator.

evaluatorAgentId
string

Explicit evaluator chosen when the outcome was defined. Absent when not chosen explicitly; each pass then uses the writer session's current agent version's defaultEvaluatorAgentId, or the managed grader.

historicalRoots
object[]
read-only

Original cloned grader roots with no pass link or verdict; iteration and exact preparation start are unknown.

passes
object[]
read-only

Cloned grading attempts, including preparation, failure, and interruption before a verdict exists.

rubricRef
string
read-only

Source file reference when the rubric was captured from an uploaded file.

rubricSha256
string
read-only

SHA-256 digest of the source rubric file, when present.

terminalExplanation
string
read-only

Why the outcome ended, beside terminalResult: the final verdict's explanation, or the reason an outcome that ended without one could not be graded. Absent until terminal, and on an outcome that ended before explanations were recorded.

terminalResult
enum<string>
read-only

Final outcome verdict; absent until terminal. not_applicable means no criterion applied and is not success.

Available options:
satisfied,
max_iterations_reached,
not_applicable,
not_evaluable,
failed