Artifacts

Last verified: 2026-06-20 (Task #390 — User APIs documentation).

A run produces artifacts — typed, validated outputs of its work. These endpoints are owner-only.

Artifact types

`artifactType`	What it holds
`candidates`	Raw candidate options gathered during retrieval.
`entities`	Normalized entities (stays, transit, activities).
`conflicts`	Detected scheduling or constraint conflicts.
`draft_ops`	Draft timeline operations the run would apply.
`proposals`	Proposals surfaced for member accept/reject.

Each artifact also carries validationStatus (pending / valid / invalid), isPartial (true while still streaming), and isPinned.

List artifacts

GET /v1/agent-runs/{runId}/artifacts

{
  "artifacts": [
    { "id": 5012, "artifactType": "entities", "validationStatus": "valid", "isPartial": false, "isPinned": false },
    { "id": 5013, "artifactType": "proposals", "validationStatus": "valid", "isPartial": false, "isPinned": true }
  ]
}

Artifacts are also returned inline by GET /v1/agent-runs/{runId} (see lifecycle.md).

Pin or unpin an artifact

PATCH /v1/agent-runs/{runId}/artifacts

Pinning marks an artifact to survive re-runs and surface it in the UI.

curl -s -X PATCH "https://api.travelmode.ai/v1/agent-runs/9f2a1c7e-…/artifacts" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "artifactId": 5012, "isPinned": true }'

{ "artifact": { "id": 5012, "artifactType": "entities", "isPinned": true } }

An artifactId that does not belong to this run returns 404 ({ "error": "Artifact not found" }).