> ## Documentation Index > Fetch the complete documentation index at: https://docs.simforge.ai/llms.txt > Use this file to discover all available pages before exploring further. # Apply a transaction ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/drafts/{id}/transactions openapi: 3.1.0 info: title: SimForge Cloud API version: '2026-10-29' description: >- The public SimForge API: what `simforge --cloud`, `simforge login` and the Python client call. Authenticate with a bearer token: the access token `simforge login` stores, an AI agent's access token (its recipe is `/auth.md`), or an `sfk_` API key. A `/api/v1` 401 carries `WWW-Authenticate: Bearer resource_metadata="/.well-known/oauth-protected-resource"`. `/api/v1` errors are an `ErrorEnvelope`; `/api/cli` and `/agent` errors are an OAuth error object. Versions: send `SimForge-Version: ` (2026-10-01, 2026-10-21, 2026-10-22, 2026-10-23, 2026-10-24, 2026-10-28, 2026-10-29) and every `/api/v1` response is in that version's shape and names it in the same header; this document describes 2026-10-29. A request without the header gets 2026-10-01, where an error's hint is `detail.hint` and `GET /api/v1/evaluations` names its rows `jobs`. A header that is not a date, or a date before 2026-10-01, is `400 bad_request`. Every response also carries `SimForge-Cli-Minimum`: the oldest `simforge` CLI the server serves. Retries: from 2026-10-21, send a new `Idempotency-Key` (1-255 characters) with every POST, PUT, PATCH and DELETE, and the same key when retrying that request. The first request's answer is kept for 24 hours and a repeat gets it again with `Idempotent-Replayed: true`; the key with any other request, or while the first is still running, is `409 idempotency_conflict` (`retryable` while running). A 5xx answer is not kept. Creating an API key refuses a key (its secret is shown once). license: name: Apache-2.0 identifier: Apache-2.0 servers: - url: https://dev.simforge.ai description: Development (dev.simforge.ai) security: [] tags: - name: Sign-in description: >- `simforge login`: OAuth 2.0 device and browser sign-in for the CLI, the session behind a token. AI agents sign in through auth.md (`/auth.md`): register, a person approves, then the claim and JWT-bearer grants. - name: Account description: The principal, its workspaces, API keys and usage, and system status. - name: Runs description: >- Cloud runs (`--cloud`): renders, simulations, Recast log ingestion and transfers, their events and artifacts. - name: Models description: Customer fine-tunes and their workspace-owned model weights. - name: Datasets description: >- Datasets, their files as signed links (`simforge.dataset-files/v1`, `simforge datasets pull`), and copies out of shared datasets (SIMLOG-25k). - name: Maps and vehicles description: >- Maps the workspace can use, the vehicles a scenario can bind and the asset gallery. - name: Authoring description: >- Hosted scenario authoring: drafts, transactions, validation and map discovery. - name: Distribution description: >- The runtime and map pack agreement and signed downloads (`simforge runtime install`, `simforge maps pull`). - name: Telemetry description: Runtime usage telemetry, a condition of the runtime terms. - name: Benchmark description: Renderer benchmark results and scene packs (`simforge bench`). - name: Challenge description: >- The driving challenge: team, registry login and submissions (`simforge challenge`). paths: /api/v1/drafts/{id}/transactions: post: tags: - Authoring summary: Apply a transaction operationId: applyDraftTransaction parameters: - in: path name: id required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DraftTransactionRequest' responses: '200': description: Atomic authoring result; save returns an immutable revision. content: application/json: schema: $ref: '#/components/schemas/AuthoringHttpDraftTransactionResult' '400': description: The request failed. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: The request failed. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: The request failed. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: The request failed. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '409': description: The request failed. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '422': description: The request failed. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - simforgeToken: - maps:read - scenarios:write components: schemas: DraftTransactionRequest: type: object properties: expectedVersion: type: integer minimum: 0 maximum: 9007199254740991 expectedDigest: type: string pattern: ^[a-f0-9]{64}$ label: type: string minLength: 1 maxLength: 256 default: CLI authoring transaction operations: type: array items: $ref: '#/components/schemas/AuthoringOperationInput' minItems: 1 maxItems: 128 required: - expectedVersion - expectedDigest - operations additionalProperties: false AuthoringHttpDraftTransactionResult: type: object additionalProperties: false required: - document - version - digest - changedPaths - entityIds - diagnostics - inverseDocument - documentId - workspaceId - datasetId - draftVersion - contentDigest - operationDigest - content - mapPin - actorPins - recordingPins - provisional properties: document: type: object version: type: integer minimum: 1 digest: type: string pattern: ^[0-9a-f]{64}$ changedPaths: type: array items: type: string entityIds: type: array items: type: string diagnostics: type: array items: $ref: '#/components/schemas/AuthoringDiagnostic' inverseDocument: type: object scene: type: object description: >- Where every actor is relative to the ego: lane, metres ahead along the ego's route, lateral offset, when the ego reaches it, its events and any encounter expectation. Absent without an ego or a map. properties: ego: type: object actors: type: array items: type: object documentId: type: string minLength: 1 maxLength: 256 workspaceId: type: string minLength: 1 maxLength: 256 datasetId: type: string minLength: 1 maxLength: 256 draftVersion: type: integer minimum: 0 maximum: 9007199254740991 contentDigest: type: string pattern: ^[a-f0-9]{64}$ operationDigest: type: string pattern: ^[a-f0-9]{64}$ content: type: object propertyNames: type: string additionalProperties: {} mapPin: type: object properties: versionId: type: string minLength: 1 maxLength: 256 mapId: type: string minLength: 1 maxLength: 256 xodrSha256: type: string pattern: ^[a-f0-9]{64}$ closureSha256: type: string pattern: ^[a-f0-9]{64}$ assetCatalogVersionId: type: string minLength: 1 maxLength: 256 assetCatalogSha256: type: string pattern: ^[a-f0-9]{64}$ releaseDigest: type: string pattern: ^[a-f0-9]{64}$ required: - versionId - mapId - xodrSha256 - closureSha256 - assetCatalogVersionId - assetCatalogSha256 additionalProperties: false actorPins: type: array items: type: object properties: actorId: type: string minLength: 1 maxLength: 256 catalogId: anyOf: - type: string minLength: 1 maxLength: 256 - type: 'null' class: type: string minLength: 1 maxLength: 256 catalogueDigest: type: string pattern: ^[a-f0-9]{64}$ required: - actorId - catalogId - class - catalogueDigest additionalProperties: false recordingPins: type: array items: type: object properties: id: type: string minLength: 1 maxLength: 256 sha256: type: string pattern: ^[a-f0-9]{64}$ required: - id - sha256 additionalProperties: {} provisional: type: boolean warnings: type: array items: type: object properties: code: type: string message: type: string subject: type: string detail: type: object properties: {} additionalProperties: {} required: - code - message additionalProperties: false upgradedFrom: type: object properties: scenarioVersion: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 contentDigest: type: string pattern: ^[a-f0-9]{64}$ required: - scenarioVersion - contentDigest additionalProperties: false ErrorEnvelope: type: object properties: error: type: object properties: code: type: string enum: - bad_request - validation_failed - unauthorized - insufficient_scope - workspace_required - not_found - conflict - gone - idempotency_conflict - lease_lost - budget_exceeded - max_cost_required - idempotency_key_required - insufficient_credits - checkout_closed - cloud_not_open - email_unverified - terms_acceptance_required - evaluation_launch_disabled - evaluation_admissions_paused - fine_tunes_not_enabled - model_name_reserved - model_name_invalid - model_name_taken - model_quota_exceeded - checkpoint_too_large - checkpoint_format_unsupported - model_family_not_fine_tunable - checkpoint_file_unexpected - checkpoint_is_offered_model - model_version_exists - param_unknown - param_invalid - param_override_not_allowed - upload_incomplete - upload_mismatch - recording_too_large - model_in_use - rate_limited - internal_error reason: type: string hint: type: string param: type: string retryable: type: boolean detail: {} path: type: string requestId: type: string pattern: ^req_[0-9A-HJKMNP-TV-Z]{26}$ required: - code - reason - retryable - requestId required: - error AuthoringOperationInput: anyOf: - $ref: '#/components/schemas/AuthoringAddActorInput' - $ref: '#/components/schemas/AuthoringMoveActorInput' - $ref: '#/components/schemas/AuthoringDuplicateActorInput' - $ref: '#/components/schemas/AuthoringRemoveRoleInput' - $ref: '#/components/schemas/AuthoringSetEgoInput' - $ref: '#/components/schemas/AuthoringSetActorSpeedInput' - $ref: '#/components/schemas/AuthoringSetActorStaticInput' - $ref: '#/components/schemas/AuthoringAddLaneChangeInput' - $ref: '#/components/schemas/AuthoringAddNextJunctionTurnInput' - $ref: '#/components/schemas/AuthoringAddUTurnInput' - $ref: '#/components/schemas/AuthoringSetWaypointRouteInput' - $ref: '#/components/schemas/AuthoringAddSpeedChangeInput' - $ref: '#/components/schemas/AuthoringAddEncounterInput' - $ref: '#/components/schemas/AuthoringSetEventTimingInput' - $ref: '#/components/schemas/AuthoringSetWeatherInput' - $ref: '#/components/schemas/AuthoringSetClockInput' - $ref: '#/components/schemas/AuthoringSetClipInput' - $ref: '#/components/schemas/AuthoringTemplateOperationInput' AuthoringDiagnostic: type: object additionalProperties: false required: - code - severity - path - message properties: code: type: string severity: enum: - error - warning - info path: type: string message: type: string actorId: type: string AuthoringAddActorInput: type: object additionalProperties: false required: - type - id - catalogId properties: type: const: addActor description: Operation id. id: type: string pattern: ^[A-Za-z][A-Za-z0-9_-]{0,63}$ description: New actor id (never allocated implicitly). catalogId: type: string description: >- Built-in actor (`simforge scenario actors`): vehicle.sedan, pedestrian.adult, ... laneRsl: type: string pattern: ^-?[0-9]+:[0-9]+:-?[0-9]+$ description: Semantic lane `road:section:lane` (with s). s: type: number description: >- Metres along laneRsl in its direction of travel, from where traffic enters it: the same s a location's anchor.road.s and a crossing approach's stopS report. minimum: 0 x-unit: m movementRsl: type: string description: >- A junction movement's connecting lane (a junction_movement location's anchor.road.rsl): place the actor beforeM up its approach and turn it through that movement. beforeM: type: number description: 'With movementRsl: distance before the junction (default 40).' minimum: 1 maximum: 500 x-unit: m x: type: number description: Scene-frame x (east). x-unit: m z: type: number description: Scene-frame z (minus north). x-unit: m 'y': type: number description: >- Explicit height; otherwise the map ground at (x,z) is used and refused without ground. x-unit: m headingRad: type: number description: >- Heading in the scene frame; default: the lane heading or the actor class default. x-unit: rad lateralM: type: number description: Lateral offset in the lane, positive to the left of travel. x-unit: m overlapOverride: type: boolean default: false description: >- Accept overlap with another actor (free/static actors only; refused for moving road vehicles). opposing: type: boolean default: false description: Snap to the nearest genuinely opposing lane. static: type: boolean default: false description: Place as a static actor (no motion, zero speed). speedKph: type: number description: 'Initial speed; default: posted limit for road vehicles.' minimum: 0 maximum: 160 x-unit: km/h bodyColor: type: string pattern: ^#[0-9a-fA-F]{6}$ description: Presentation body colour `#rrggbb`. label: type: string maxLength: 80 description: Display label. oneOf: - required: - laneRsl - s - required: - x - z - required: - movementRsl AuthoringMoveActorInput: type: object additionalProperties: false required: - type - id properties: type: const: moveActor description: Operation id. id: type: string pattern: ^[A-Za-z][A-Za-z0-9_-]{0,63}$ description: Actor to move. laneRsl: type: string pattern: ^-?[0-9]+:[0-9]+:-?[0-9]+$ description: Semantic lane `road:section:lane` (with s). s: type: number description: >- Metres along laneRsl in its direction of travel, from where traffic enters it: the same s a location's anchor.road.s and a crossing approach's stopS report. minimum: 0 x-unit: m x: type: number description: Scene-frame x (east). x-unit: m z: type: number description: Scene-frame z (minus north). x-unit: m 'y': type: number description: >- Explicit height; otherwise the map ground at (x,z) is used and refused without ground. x-unit: m headingRad: type: number description: >- Heading in the scene frame; default: the lane heading or the actor class default. x-unit: rad lateralM: type: number description: Lateral offset in the lane, positive to the left of travel. x-unit: m overlapOverride: type: boolean default: false description: >- Accept overlap with another actor (free/static actors only; refused for moving road vehicles). oneOf: - required: - laneRsl - s - required: - x - z AuthoringDuplicateActorInput: type: object additionalProperties: false required: - type - id - newId properties: type: const: duplicateActor description: Operation id. id: type: string pattern: ^[A-Za-z][A-Za-z0-9_-]{0,63}$ description: Source actor. newId: type: string pattern: ^[A-Za-z][A-Za-z0-9_-]{0,63}$ description: New actor id. laneRsl: type: string pattern: ^-?[0-9]+:[0-9]+:-?[0-9]+$ description: Semantic lane `road:section:lane` (with s). s: type: number description: >- Metres along laneRsl in its direction of travel, from where traffic enters it: the same s a location's anchor.road.s and a crossing approach's stopS report. minimum: 0 x-unit: m x: type: number description: Scene-frame x (east). x-unit: m z: type: number description: Scene-frame z (minus north). x-unit: m 'y': type: number description: >- Explicit height; otherwise the map ground at (x,z) is used and refused without ground. x-unit: m headingRad: type: number description: >- Heading in the scene frame; default: the lane heading or the actor class default. x-unit: rad lateralM: type: number description: Lateral offset in the lane, positive to the left of travel. x-unit: m overlapOverride: type: boolean default: false description: >- Accept overlap with another actor (free/static actors only; refused for moving road vehicles). oneOf: - required: - laneRsl - s - required: - x - z AuthoringRemoveRoleInput: type: object additionalProperties: false required: - type - id properties: type: const: removeRole description: Operation id. id: type: string pattern: ^[A-Za-z][A-Za-z0-9_-]{0,63}$ description: Actor to delete. AuthoringSetEgoInput: type: object additionalProperties: false required: - type - roleId properties: type: const: setEgo description: Operation id. roleId: type: string pattern: ^[A-Za-z][A-Za-z0-9_-]{0,63}$ description: Actor to make ego. AuthoringSetActorSpeedInput: type: object additionalProperties: false required: - type - id - speedKph properties: type: const: setActorSpeed description: Operation id. id: type: string pattern: ^[A-Za-z][A-Za-z0-9_-]{0,63}$ description: Actor. speedKph: type: number description: Initial speed. minimum: 0 maximum: 160 x-unit: km/h AuthoringSetActorStaticInput: type: object additionalProperties: false required: - type - id - static properties: type: const: setActorStatic description: Operation id. id: type: string pattern: ^[A-Za-z][A-Za-z0-9_-]{0,63}$ description: Actor. static: type: boolean description: 'true: static; false: mobile.' AuthoringAddLaneChangeInput: type: object additionalProperties: false required: - type - id - actorId - direction - startS properties: type: const: addLaneChange description: Operation id. id: type: string pattern: ^[A-Za-z][A-Za-z0-9_-]{0,63}$ description: New event id. actorId: type: string pattern: ^[A-Za-z][A-Za-z0-9_-]{0,63}$ description: Actor. direction: type: string enum: - left - right description: Target lane side. startS: type: number description: Clip time the change starts. minimum: 0 x-unit: s endS: type: number description: Clip time the event ends. minimum: 0 x-unit: s durationS: type: number description: Lane-change duration. exclusiveMinimum: 0 default: 3 x-unit: s AuthoringAddNextJunctionTurnInput: type: object additionalProperties: false required: - type - id - actorId - direction - startS properties: type: const: addNextJunctionTurn description: Operation id. id: type: string pattern: ^[A-Za-z][A-Za-z0-9_-]{0,63}$ description: New event id. actorId: type: string pattern: ^[A-Za-z][A-Za-z0-9_-]{0,63}$ description: Actor. direction: type: string enum: - left - right - straight description: Movement at the next junction. startS: type: number description: Clip time the choice applies from. minimum: 0 x-unit: s endS: type: number description: Clip time the event ends. minimum: 0 x-unit: s AuthoringAddUTurnInput: type: object additionalProperties: false required: - type - id - actorId properties: type: const: addUTurn description: Operation id. id: type: string pattern: ^[A-Za-z][A-Za-z0-9_-]{0,63}$ description: New event id. actorId: type: string pattern: ^[A-Za-z][A-Za-z0-9_-]{0,63}$ description: A moving road vehicle on a lane. movementRsl: type: string description: >- A U-turn movement's connecting lane on the actor's route (authoring discover --kind movements, turnRelation UTurnLeft/UTurnRight); default: the first place it can turn. AuthoringSetWaypointRouteInput: type: object additionalProperties: false required: - type - id - actorId - points - startS - durationS properties: type: const: setWaypointRoute description: Operation id. id: type: string pattern: ^[A-Za-z][A-Za-z0-9_-]{0,63}$ description: New event id. actorId: type: string pattern: ^[A-Za-z][A-Za-z0-9_-]{0,63}$ description: Actor. points: type: array minItems: 2 description: >- Scene points `X,Z` in metres (x east, z minus north; the height follows the map ground), the actor's current position first. items: type: object additionalProperties: false required: - x - z properties: x: type: number z: type: number startS: type: number description: Clip time the route starts. minimum: 0 x-unit: s durationS: type: number description: Route duration. exclusiveMinimum: 0 x-unit: s endS: type: number description: Clip time the event ends. minimum: 0 x-unit: s AuthoringAddSpeedChangeInput: type: object additionalProperties: false required: - type - id - actorId - startS - targetKph properties: type: const: addSpeedChange description: Operation id. id: type: string pattern: ^[A-Za-z][A-Za-z0-9_-]{0,63}$ description: New event id. actorId: type: string pattern: ^[A-Za-z][A-Za-z0-9_-]{0,63}$ description: Actor. startS: type: number description: Clip time the change starts. minimum: 0 x-unit: s targetKph: type: number description: Speed to reach; 0 brakes to a stop. minimum: 0 maximum: 160 x-unit: km/h rateMps2: type: number description: >- Acceleration or deceleration (default 4, at most the class limit: a car brakes at up to 8, speeds up at up to 3). minimum: 0.1 maximum: 20 x-unit: m/s² endS: type: number description: Clip time the event ends. minimum: 0 x-unit: s AuthoringAddEncounterInput: type: object additionalProperties: false required: - type - kind - id properties: type: const: addEncounter description: Operation id. kind: type: string enum: - lead-brake - slow-lead - stopped - cut-in - crossing - oncoming - cross-traffic - reversing - pull-out - u-turn description: >- lead-brake: ahead in the target's lane, brakes to a stop at atS. slow-lead: ahead, slower. stopped: standing ahead in the lane. cut-in: from the lane on the target's side, into its lane from atS, starting gapM in front. crossing: a pedestrian on the target's path at atS (or at x,z), ttcS before the target. oncoming / cross-traffic: a car on the opposite / a crossing approach of a junction ahead crosses its path ttcS before it (the first junction whose movement enters within 30° of straight against / square to the target's heading, else the nearest to it). reversing: standing ahead, reverses toward the target from atS. pull-out: parked at the side edge of the target's lane gapM ahead, pulls into the lane at atS. u-turn: ahead in the target's lane gapM ahead, makes a U-turn at the first place it can (a mapped U-turn movement, else a path through a junction or across a road wide enough). id: type: string pattern: ^[A-Za-z][A-Za-z0-9_-]{0,63}$ description: New actor id. catalogId: type: string description: >- Built-in actor; default vehicle.sedan (box truck for reversing, pedestrian.adult for crossing). target: type: string pattern: ^[A-Za-z][A-Za-z0-9_-]{0,63}$ description: 'The actor the encounter is with: a moving road vehicle on a lane.' default: ego atS: type: number description: >- Clip time of the moment: lead-brake brake start (default 3), cut-in lane-change start (3), crossing time on the target's lane (4), reversing start (1), pull-out start (2). minimum: 0 x-unit: s side: type: string enum: - left - right description: >- cut-in: the target's side the car comes from (required). crossing: the side the pedestrian starts on (default right). pull-out: the lane edge the car is parked at (default right). gapM: type: number description: >- Centre-to-centre distance ahead of the target: at the start (lead-brake 20, slow-lead 30, stopped 25, reversing 25, pull-out 30, u-turn 25) or when the cut-in starts (7). minimum: 0 maximum: 500 x-unit: m speedKph: type: number description: >- The new actor's speed: lead-brake the target's, slow-lead half of it, cut-in 10 faster, crossing walk 4.5, oncoming/cross-traffic the posted limit, reversing 6, pull-out 20, u-turn the target's within 15-30. minimum: 0 maximum: 160 x-unit: km/h decelMps2: type: number description: >- lead-brake deceleration (default 5.5, a hard stop that stays within comfort checks). minimum: 0.5 maximum: 12 x-unit: m/s² ttcS: type: number description: >- crossing, oncoming, cross-traffic: the target's time to the conflict point when the new actor is on it (crossing default 2, junctions 1.5; negative: after the target). minimum: -10 maximum: 30 x-unit: s turn: type: string enum: - left - right - straight description: >- oncoming / cross-traffic: the new car's movement through the junction (default straight). x: type: number description: >- crossing: a scene point on the target's path where the pedestrian crosses (a crosswalk), with z; replaces atS. x-unit: m z: type: number description: 'crossing: the point''s scene z (minus north).' x-unit: m AuthoringSetEventTimingInput: type: object additionalProperties: false required: - type - id - startS properties: type: const: setEventTiming description: Operation id. id: type: string pattern: ^[A-Za-z][A-Za-z0-9_-]{0,63}$ description: Event. startS: type: number description: Start clip time. minimum: 0 x-unit: s endS: type: number description: End clip time. minimum: 0 x-unit: s AuthoringSetWeatherInput: type: object additionalProperties: false required: - type - weather properties: type: const: setWeather description: Operation id. weather: type: string enum: - clear - cloudy - overcast - light_rain - heavy_rain - wet_road - fog_light - fog_dense - snow - sleet description: Canonical scenario weather. AuthoringSetClockInput: type: object additionalProperties: false required: - type - minutes properties: type: const: setClock description: Operation id. minutes: type: integer minimum: 0 maximum: 1439 description: Minutes after local midnight. x-unit: min AuthoringSetClipInput: type: object additionalProperties: false required: - type properties: type: const: setClip description: Operation id. clipSeconds: type: number description: Clip length. minimum: 3 maximum: 120 x-unit: s warmupSeconds: type: number description: Warm-up before the clip. minimum: 0 maximum: 30 x-unit: s anyOf: - required: - clipSeconds - required: - warmupSeconds AuthoringTemplateOperationInput: type: object required: - type properties: type: type: string additionalProperties: true description: >- Advanced existing TemplateOp request; common operations use the typed catalogue inputs. securitySchemes: simforgeToken: type: http scheme: bearer description: >- A `sfc_at_…` access token from `simforge login`, or an `sfk_…` API key. An operation's security lists the scopes the credential must hold. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.