Skip to content

Session Plan Artifact Patches

GET
/v1/sessions/{session_id}/plan-artifact/patches
curl --request GET \
--url 'https://agents.lumalabs.ai/v1/sessions/example/plan-artifact/patches?since=1' \
--header 'Authorization: Bearer <token>'

The patch chain carrying a client from since to the current revision.

The delta half of the plan read path: plan.updated tells a client THAT the document moved, this says what moved, and the snapshot stays the fallback whenever a chain cannot be trusted.

Serves a chain only when it is provably whole — one patch per revision in (since, current]. When it is not, the answer is complete=False and NO patches rather than a prefix: read the full document from the snapshot instead.

session_id
required
Session Id
string
since
required
Since

The revision the client already holds.

integer

The revision the client already holds.

Successful Response

Media typeapplication/json
PlanArtifactDelta

The patch chain carrying a client from its revision to the server's.

complete=False is the ONLY thing a client needs to branch on: it means this chain cannot be trusted to reconstruct the document (a gap, a revision recorded twice under the unlocked revision++ race, or a client asking from a revision with no record), so the client must fall back to the full snapshot. patches is empty whenever it is false — an incomplete chain is never partially served, because applying a prefix would leave the client silently describing itself as a revision it does not hold.

object
complete
required
Complete

Whether patches reconstructs revision exactly.

boolean
from_revision
required
From Revision

Echo of the requested since revision.

integer
patches
Patches

Ordered hops from from_revision to revision.

Array<object>
PlanArtifactPatch

One revision's hop: the RFC-6902 ops carrying the previous revision's document to this one, plus the hash of the result.

object
document_hash
required
Document Hash

SHA-256 over canonical JSON of the document AFTER this hop.

string
mutated_by
required
Mutated By

Tool/stage that performed the mutation.

string
patch
required
Patch

RFC-6902 ops from revision-1 to this revision.

Array<object>
object
key
additional properties
any
revision
required
Revision

The revision this hop produces.

integer
revision
required
Revision

The server's current plan-artifact revision.

integer
state
required
SessionState

The session's state, so a delta read need not also fetch the snapshot.

string
Allowed values: active closing suspended error completed expired
Example
{
"state": "active"
}

Validation Error

Media typeapplication/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
ctx
Context
object
input
Input
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
Examplegenerated
{
"detail": [
{
"ctx": {},
"input": "example",
"loc": [
"example"
],
"msg": "example",
"type": "example"
}
]
}