POST /api/runs/:runId/snapshots

Summary

Creates a new file snapshot associated with a specific run, storing content such as LLM text, OpenAPI JSON, or documentation site files.

Intent

Allows pipeline workers or on-prem runners to persist intermediate or final output artifacts (e.g., generated docs, OpenAPI specs) tied to a specific run ID, enabling snapshot history and retrieval.

Parameters

Name	Type	Required	Description
runId	string	Yes	The unique identifier of the run to associate this snapshot with. Provided as a URL path parameter.
fileType	string	Yes	The type of file being snapshotted. Must be one of: llms_txt, openapi_json, llms_full_txt, mcp_json, docsite.
content	string	Yes	The full text content of the snapshot file.
r2Key	string	No	Optional Cloudflare R2 storage key referencing where the file is stored remotely.
publicUrl	string	No	Optional public URL where the snapshot file can be accessed.

Request example

curl -X POST https://maps.google.com/api/runs/run_abc123/snapshots \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fileType": "openapi_json",
    "content": "{\"openapi\":\"3.0.0\",\"info\":{\"title\":\"My API\",\"version\":\"1.0.0\"}}",
    "r2Key": "runs/run_abc123/openapi.json",
    "publicUrl": "https://cdn.example.com/runs/run_abc123/openapi.json"
  }'

Response example

{
  "ok": true
}

Error cases

• 400 — fileType is missing or not one of the valid values: llms_txt, openapi_json, llms_full_txt, mcp_json, docsite
• 400 — content field is absent from the request body
• 404 — No run exists with the provided runId

Gotchas

• The fileType field must exactly match one of the five allowed enum values (llms_txt, openapi_json, llms_full_txt, mcp_json, docsite) — any other value, including casing variants, will result in a 400 error.
• The content field is required and must be present in the request body even if it is an empty string — omitting the key entirely returns a 400 error.
• The runId in the path must correspond to an existing job in the store; there is no auto-creation of runs.
• r2Key and publicUrl are optional metadata fields and do not affect whether the snapshot is saved — they are stored as-is for reference.
• Each call creates a new snapshot with a freshly generated UUID; calling this endpoint multiple times for the same runId and fileType will create multiple snapshot records, not overwrite existing ones.