> ## 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. # Create a run > Start a run; dryRun returns the quote without work. Driving evaluations use type closed_loop with datasetId, explicit scenarioIds and policy {kind:model_version,family,modelVersionId} naming an available model of GET /api/v1/evaluation-options (its id and family); each scenario costs that model's pricePerScenarioCents, preparation included. Other evaluation kinds and models remain 403 evaluation_launch_disabled. Paid submissions require maxCostCents and Idempotency-Key. Admission atomically checks balance and reserves the whole quote before work; insufficient credits return 402. Unserved work returns 403 cloud_not_open. Reusing the same key and request returns the original run. ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/runs openapi: 3.1.0 info: title: SimForge Cloud API version: '2026-10-24' 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) and every `/api/v1` response is in that version's shape and names it in the same header; this document describes 2026-10-24. 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/runs: post: tags: - Runs summary: Create a run description: >- Start a run; dryRun returns the quote without work. Driving evaluations use type closed_loop with datasetId, explicit scenarioIds and policy {kind:model_version,family,modelVersionId} naming an available model of GET /api/v1/evaluation-options (its id and family); each scenario costs that model's pricePerScenarioCents, preparation included. Other evaluation kinds and models remain 403 evaluation_launch_disabled. Paid submissions require maxCostCents and Idempotency-Key. Admission atomically checks balance and reserves the whole quote before work; insufficient credits return 402. Unserved work returns 403 cloud_not_open. Reusing the same key and request returns the original run. operationId: createRun requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RunCreateRequest' responses: '200': description: Quote or idempotent replay, including managed driving evaluations. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Run' - $ref: '#/components/schemas/DryRunResponse' - $ref: '#/components/schemas/Evaluation' - $ref: '#/components/schemas/EvaluationQuote' '201': description: Created run or canonical managed evaluation. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Run' - $ref: '#/components/schemas/Evaluation' '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' '402': description: >- `insufficient_credits`: the workspace's credits do not cover the estimate (`detail.requestedCents`, `detail.balanceCents`, `detail.creditsUrl`, `detail.checkout`); or `budget_exceeded`: the estimate is above the request's `maxCostCents` (`detail.limit` `max_cost`). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: >- `cloud_not_open`: SimForge Cloud is off here, or no worker here runs the work yet (the reason names it, `detail.code` `run_kind_unavailable`, `detail.kinds` its job kinds); or `insufficient_scope`. 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' '429': description: The request failed. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - simforgeToken: - runs:write components: schemas: RunCreateRequest: type: object properties: type: type: string minLength: 1 input: description: >- The run type's input. For `type: "render"` it is a RenderRunInput; the other run types' inputs are objects of their own. anyOf: - $ref: '#/components/schemas/RenderRunInput' - type: object additionalProperties: true dryRun: type: boolean maxCostCents: type: integer minimum: 0 description: >- Required for non-dry submissions with a positive cost estimate; the maximum approved price in cents. required: - type examples: - type: render input: scenarioId: engine: 3d preset: showcase rig: schema: simforge.render-rig/v1 sources: - actorId: ego sensorId: cam-front outputName: cam-front transform: position: x: 1.6 'y': 1.45 z: 0 rotation: yawRad: 0 pitchRad: -0.0524 rollRad: 0 modality: rgb attributes: width: 1280 height: 720 fps: 20 horizontalFovDeg: 90 nearM: 0.05 farM: 1000 maxCostCents: 100 Run: type: object properties: id: type: string idempotencyKey: type: - string - 'null' description: >- Caller-supplied run identity; qualification namespaces are excluded from evaluation suites. type: type: string status: type: string enum: - queued - running - succeeded - partial - failed - cancelled input: {} createdAt: type: string format: date-time startedAt: type: - string - 'null' format: date-time finishedAt: type: - string - 'null' format: date-time createdBy: type: - object - 'null' properties: id: type: string minLength: 1 email: type: - string - 'null' required: - id - email published: type: boolean description: >- A run published from another workspace (read-only here): a public benchmark. False for a master render of one of your Sample scenarios. Absent means false (a server older than this field). costEstimateCents: type: - integer - 'null' minimum: 0 costCents: type: - integer - 'null' minimum: 0 billing: type: object properties: hold: type: - string - 'null' enum: - pending - released - null heldCents: type: integer minimum: 0 chargedCents: type: integer minimum: 0 required: - hold - heldCents - chargedCents jobs: type: array items: type: object properties: id: type: string kind: type: string status: type: string enum: - queued - leased - running - succeeded - failed - cancelled - skipped attempt: type: integer minimum: 0 maxAttempts: type: integer exclusiveMinimum: 0 leaseExpiresAt: type: - string - 'null' format: date-time workerClass: type: - string - 'null' enum: - cpu - gpu - null queue: type: - object - 'null' properties: blockedBy: type: array items: type: string ahead: type: - integer - 'null' minimum: 0 etaSeconds: type: - integer - 'null' minimum: 0 waitingFor: type: - string - 'null' enum: - worker - gpu - map - null required: - blockedBy - ahead - etaSeconds - waitingFor progress: {} errorCode: type: - string - 'null' errorReason: type: - string - 'null' startedAt: type: - string - 'null' format: date-time finishedAt: type: - string - 'null' format: date-time required: - id - kind - status - attempt - maxAttempts - leaseExpiresAt - workerClass - queue - errorCode - errorReason - startedAt - finishedAt warnings: type: array items: type: object properties: code: type: string message: type: string subject: type: string detail: type: object properties: {} additionalProperties: {} jobId: type: string required: - code - message result: {} unavailable: type: object properties: code: type: string message: type: string required: - code - message description: >- Present when this run's artifacts and result could not be read: `result` is null and its artifacts are left out, while every other field still holds. The rest of a page is unaffected. required: - id - type - status - createdAt - startedAt - finishedAt - createdBy - costEstimateCents - costCents - billing - jobs - warnings DryRunResponse: type: object properties: dryRun: type: boolean enum: - true type: type: string input: {} requestSha256: type: string jobs: type: array items: type: object properties: key: type: string kind: type: string input: {} dependsOn: type: array items: type: string maxAttempts: type: integer exclusiveMinimum: 0 required: - key - kind - dependsOn estimate: type: object properties: jobs: type: integer minimum: 0 seconds: type: number minimum: 0 required: - jobs - seconds costEstimateCents: type: integer minimum: 0 costBreakdown: type: array items: type: object properties: jobKey: type: string kind: type: string cents: type: integer minimum: 0 required: - jobKey - kind - cents maxCost: type: - object - 'null' properties: limitCents: type: integer minimum: 0 exceeded: type: boolean required: - limitCents - exceeded description: >- The request's maxCostCents and whether the estimate exceeds it (the same request without dryRun would be refused budget_exceeded); null when no maxCostCents was sent. A dry run over the cap is still priced, never refused. allowed: type: boolean description: Whether the same request without dryRun would be admitted now. refusal: type: - object - 'null' properties: code: type: string message: type: string detail: type: object properties: {} additionalProperties: {} required: - code - message description: >- Why it would be refused now, with the code and detail that submission would answer: evaluation_admissions_paused (evaluations are paused; the price still stands), budget_exceeded, insufficient_credits, rate_limited, or cloud_not_open when no worker serves its work right now (detail.code run_kind_unavailable, model_unavailable or render_preset_unavailable). Null when allowed. notes: type: array items: type: object properties: code: type: string message: type: string subject: type: string detail: type: object properties: {} additionalProperties: {} required: - code - message description: >- What the run would do differently while still doing its work, in the words its run warnings will use (an open-loop evaluation of a render whose frames are off the model's 10 Hz clock: render_frame_rate_differs). Empty when nothing. model: $ref: '#/components/schemas/ModelIdentity' modelParams: type: object additionalProperties: anyOf: - type: number - type: string description: >- The model's parameters it would run with, by name, defaults filled in (the request's input.params, else each one's default); absent with model. customParams: type: boolean description: >- True when a parameter whose comparability is custom is off its default: compare the run only with runs of the same params. cancellation: type: object properties: queuedCostCents: type: number enum: - 0 failedRunCostCents: type: number enum: - 0 partialCharge: type: string enum: - succeeded_jobs_only wholeRunPriceRequiresSuccess: type: boolean required: - queuedCostCents - failedRunCostCents - partialCharge - wholeRunPriceRequiresSuccess required: - dryRun - type - requestSha256 - jobs - estimate - costEstimateCents - costBreakdown - maxCost - allowed - refusal - notes - cancellation Evaluation: type: object properties: id: type: string pattern: ^(run|cmpj)_ kind: type: string description: >- Legacy: alpamayo.openloop for the default model or a workspace alias of it, policy.openloop for every other model (before API version 2026-10-24: the lane it ran on, the default model's family lane or policy.openloop). Name the model by model.modelVersionId. idempotencyKey: type: - string - 'null' description: >- Caller-supplied job identity; qualification namespaces are excluded from evaluation suites. status: type: string enum: - queued - dispatching - dispatch_unknown - running - cancelling - succeeded - partial - failed - cancelled workspaceId: type: string description: >- The workspace it ran in; absent on an evaluation published to every workspace (`published`). published: type: boolean enum: - true description: >- An evaluation SimForge published to every workspace (`GET /api/v1/evaluations?published=true`): read-only, without its workspace, origin, submitter, estimate or cost. origin: type: string enum: - browser - desktop - cli - api description: >- Where it was launched from: Studio (browser), the desktop app, the simforge CLI (cli) or an API key (api). model: type: object properties: family: type: string description: Its model family (architecture and upstream weights). revision: type: string description: The upstream weights revision (40 hex) its family pins. quant: type: string description: Its quantization. modelVersionId: type: - string - 'null' description: >- The registered model version it ran; absent or null on an evaluation from before cloud runs that names none. name: type: string description: >- Its name, as `GET /api/v1/evaluation-options` lists an offered model. checkpointDigest: type: - string - 'null' description: >- The sha256 of the checkpoint it runs; a model job runs only beside a model host serving exactly this checkpoint. aliasOf: type: - string - 'null' description: >- The offered model this workspace's own version copies (the same family, quantization and checkpoint); null for an offered model and any other version. owner: type: string description: >- Whose model it is: `simforge` (a model SimForge offers) or `workspace` (this workspace's own version, an alias of an offered model included). An open string: a reader keeps a value it does not know. required: - family - revision - quant description: >- What it ran: the identity block (`ModelIdentity`); an evaluation from before cloud runs may lack modelVersionId, name, checkpointDigest, aliasOf and owner. params: type: object additionalProperties: {} description: >- The runner's job parameters (its instants, render source and sampling). modelParams: type: object additionalProperties: anyOf: - type: number - type: string description: >- The model's parameters it runs with, by name, defaults filled in (what params sent, else each one's default). customParams: type: boolean description: >- True when a parameter whose comparability is custom (a sampling setting, a navigation instruction) was off its default: compare it only with runs of the same params. estimateCents: type: object properties: lowCents: type: number minimum: 0 highCents: type: number minimum: 0 basis: type: string enum: - measured - unbenchmarked - per_scenario required: - lowCents - highCents - basis reservedCents: type: number settledCents: type: - number - 'null' scored: type: - boolean - 'null' result: type: - object - 'null' properties: metrics: type: object additionalProperties: {} artifacts: type: array items: type: object properties: role: type: string artifactId: type: string mediaType: type: string bytes: type: number minimum: 0 sha256: type: string pattern: ^[a-f0-9]{64}$ required: - role - artifactId - mediaType - bytes - sha256 required: - metrics - artifacts additionalProperties: {} required: - id - kind - status - model - params - scored - result additionalProperties: {} EvaluationQuote: type: object properties: dryRun: type: boolean enum: - true type: type: string description: >- Legacy: alpamayo.openloop for the default model or a workspace alias of it, policy.openloop for every other model (before API version 2026-10-24: the lane it ran on, the default model's family lane or policy.openloop). Name the model by model.modelVersionId. scenarioId: type: string description: The scenario it would evaluate. estimate: type: object properties: lowCents: type: number minimum: 0 highCents: type: number minimum: 0 basis: type: string enum: - measured - unbenchmarked - per_scenario required: - lowCents - highCents - basis allowed: type: boolean refusal: type: - object - 'null' properties: code: type: string message: type: string detail: type: object additionalProperties: {} required: - code - message description: >- Why the same request without dryRun would be refused now, with that submission's code and detail (cloud_not_open with detail.code model_unavailable while no worker serves the model). Null when allowed. notes: type: array items: type: object properties: code: type: string message: type: string subject: type: string detail: type: object properties: {} additionalProperties: {} required: - code - message description: >- Warnings attached to the evaluation while it runs, including model_defaulted before API version 2026-10-24 when the request names no model. Empty when nothing. availableCreditsCents: type: number concurrency: type: object properties: active: type: number limit: type: - number - 'null' description: The workspace's active-job limit; null when it has none. required: - active - limit maxCostCents: type: integer minimum: 0 cancellationTerms: type: string modelVersionId: type: string description: >- The model version it would run (before API version 2026-10-24, the default model when the request names none); `model.modelVersionId`. modelName: type: string description: '`model.name`.' model: $ref: '#/components/schemas/ModelIdentity' modelParams: type: object additionalProperties: anyOf: - type: number - type: string description: >- The model's parameters it runs with, by name, defaults filled in (what params sent, else each one's default). customParams: type: boolean description: >- True when a parameter whose comparability is custom (a sampling setting, a navigation instruction) was off its default: compare it only with runs of the same params. required: - dryRun - type - scenarioId - estimate - allowed - refusal - notes - availableCreditsCents - concurrency - maxCostCents - cancellationTerms 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 - 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 RenderRunInput: description: >- The input of a `render` run: a scenario of the workspace (at a revision) rendered by the 2D or the 3D engine, through a sensor rig. oneOf: - type: object additionalProperties: false required: - scenarioId - engine properties: scenarioId: type: string minLength: 1 description: A scenario of the workspace (`GET /api/v1/scenarios`). revisionId: type: string minLength: 1 description: >- An immutable revision of it. Default: the scenario's current revision. engine: enum: - 2d description: >- `2d`: the top-down map video (CPU). `3d`: the Helios Engine (GPU); the schematic look is `3d` with `preset: schematic`. preset: type: string minLength: 1 description: >- `training`, `showcase` or `schematic` (3D only). Default for a hosted 3D render: `training`. rig: description: >- A complete simforge.render-rig/v1 rig, or {clip} for 2D only. Clip endSeconds must exceed startSeconds. Default: the built-in front camera on the scenario's ego. anyOf: - $ref: '#/components/schemas/RenderRig' - type: object additionalProperties: false required: - clip properties: clip: type: object properties: startSeconds: type: number minimum: 0 endSeconds: type: number exclusiveMinimum: 0 required: - startSeconds - endSeconds additionalProperties: false outputs: enum: - video - stills description: >- `video` (default): one MP4 per sensor. `stills`: the RGB frames as PNGs (a preview). replayOf: type: string pattern: ^run_ description: >- A succeeded `closed_loop` run of this scenario: render the drive that run scored (its episode's render timeline, `GET /api/v1/runs/{id}/replay`) instead of the scenario's own simulation. The render is pinned to that run's revision. - type: object additionalProperties: false required: - scenarioId - engine properties: scenarioId: type: string minLength: 1 description: A scenario of the workspace (`GET /api/v1/scenarios`). revisionId: type: string minLength: 1 description: >- An immutable revision of it. Default: the scenario's current revision. engine: enum: - 3d description: >- `2d`: the top-down map video (CPU). `3d`: the Helios Engine (GPU); the schematic look is `3d` with `preset: schematic`. preset: type: string minLength: 1 description: >- `training`, `showcase` or `schematic` (3D only). Default for a hosted 3D render: `training`. rig: $ref: '#/components/schemas/RenderRig' description: >- A complete simforge.render-rig/v1 rig. Default: the built-in front camera on the scenario's ego. outputs: enum: - video - stills description: >- `video` (default): one MP4 per sensor. `stills`: the RGB frames as PNGs (a preview). replayOf: type: string pattern: ^run_ description: >- A succeeded `closed_loop` run of this scenario: render the drive that run scored (its episode's render timeline, `GET /api/v1/runs/{id}/replay`) instead of the scenario's own simulation. The render is pinned to that run's revision. rigs: type: array minItems: 1 maxItems: 16 description: >- Several ego actors (3D): which rig each ego carries, every source of `rig` hosted by one of them. `rigId` is a built-in sensor rig that fits the actor's kind (a car, truck, bus, van or motorcycle takes road rigs, a drone drone rigs), or `custom` for a rig file. Each actor must be an ego of the scenario (its `ego`, or a role marked `org.simforge.ego.v1`). Absent: one ego, every source mounted on it. items: type: object additionalProperties: false required: - actorId - rigId properties: actorId: type: string minLength: 1 rigId: type: string minLength: 1 horizonSeconds: type: number minimum: 3 maximum: 120 description: >- Simulate and render the scenario to this many seconds (3D). A scenario authored shorter is simulated on past its end without being edited: its authored vehicles drive on as traffic, and the run warns `simulated_past_authored_end`. At or under the scenario's clip, or absent: the scenario's own clip. ModelIdentity: type: object properties: modelVersionId: type: string description: >- The model version: an offered model's id (`GET /api/v1/evaluation-options`) or one of this workspace's own. name: type: string description: >- Its name, as `GET /api/v1/evaluation-options` lists an offered model. family: type: string description: Its model family (architecture and upstream weights). revision: type: string description: The upstream weights revision (40 hex) its family pins. quant: type: string description: Its quantization. checkpointDigest: type: string description: >- The sha256 of the checkpoint it runs; a model job runs only beside a model host serving exactly this checkpoint. aliasOf: type: - string - 'null' description: >- The offered model this workspace's own version copies (the same family, quantization and checkpoint); null for an offered model and any other version. owner: type: string description: >- Whose model it is: `simforge` (a model SimForge offers) or `workspace` (this workspace's own version, an alias of an offered model included). An open string: a reader keeps a value it does not know. required: - modelVersionId - name - family - revision - quant - checkpointDigest - aliasOf - owner RenderRig: $comment: >- GENERATED from RenderRigV1Schema by `pnpm --filter @simforge/scenario schema:render-rig`. Do not edit. title: simforge.render-rig/v1 description: >- Actor-mounted capture sources. Consumers also enforce unique actor/sensor/modality identities and output names, reject topdown rig sources, and check cross-field camera and scan constraints. type: object properties: schema: type: string const: simforge.render-rig/v1 sources: minItems: 1 maxItems: 64 type: array items: $ref: '#/components/schemas/RenderRigSource' sensorHosts: minItems: 1 maxItems: 64 type: array items: type: object properties: sourceId: $ref: '#/components/schemas/RenderRigOutputName' actorId: type: string pattern: ^[0-9A-Za-z][0-9A-Za-z_-]{0,63}$ vehicleAsset: type: object properties: catalogAssetId: type: string minLength: 1 maxLength: 200 required: - catalogAssetId additionalProperties: {} required: - sourceId - actorId - vehicleAsset additionalProperties: false clip: type: object properties: startSeconds: type: number minimum: 0 endSeconds: type: number exclusiveMinimum: 0 required: - startSeconds - endSeconds additionalProperties: false video: type: object properties: width: type: integer minimum: 64 maximum: 8192 height: type: integer minimum: 64 maximum: 8192 fps: type: number exclusiveMinimum: 0 maximum: 240 container: type: string enum: - mp4 - webm codec: type: string enum: - h264 - vp9 - av1 quality: type: string enum: - draft - standard - high - lossless required: - width - height - fps - container - codec - quality additionalProperties: false required: - schema - sources additionalProperties: false examples: - schema: simforge.render-rig/v1 sources: - actorId: ego sensorId: cam-front outputName: cam-front transform: position: x: 1.6 'y': 1.45 z: 0 rotation: yawRad: 0 pitchRad: -0.0524 rollRad: 0 modality: rgb attributes: width: 1280 height: 720 fps: 20 horizontalFovDeg: 90 nearM: 0.05 farM: 1000 RenderRigSource: oneOf: - type: object properties: actorId: type: string pattern: ^[0-9A-Za-z][0-9A-Za-z_-]{0,63}$ sensorId: type: string pattern: ^[0-9A-Za-z][0-9A-Za-z_-]{0,63}$ sensorLabel: type: string minLength: 1 maxLength: 200 outputName: $ref: '#/components/schemas/RenderRigOutputName' transform: $ref: '#/components/schemas/RenderRigTransform' modality: type: string enum: - rgb - depth - semantic - instance mountFrame: type: string enum: - body - gimbal attributes: type: object properties: captureStage: type: string const: scene-pre-postprocess/v1 detector: type: object properties: schema: type: string const: simforge.hdr-detector-config/v1 captureStage: type: string const: scene-pre-postprocess/v1 noise: type: object properties: model: type: string const: gaussian-electron-ptc/v1 correlatedDetector: type: object properties: model: type: string const: gaussian-row-column-detector/v1 width: type: integer minimum: 1 maximum: 16384 height: type: integer minimum: 1 maximum: 16384 fixedPatternSeedHex: type: string pattern: ^[a-f0-9]{64}$ physicalInstanceId: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9_.-]+$ epoch: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9_.-]+$ rowFixedSigmaElectrons: type: number minimum: 0 maximum: 1000000 columnFixedSigmaElectrons: type: number minimum: 0 maximum: 1000000 rowReadSigmaElectrons: type: number minimum: 0 maximum: 1000000 columnReadSigmaElectrons: type: number minimum: 0 maximum: 1000000 required: - model - width - height - fixedPatternSeedHex - physicalInstanceId - epoch - rowFixedSigmaElectrons - columnFixedSigmaElectrons - rowReadSigmaElectrons - columnReadSigmaElectrons additionalProperties: false electronsPerInputUnit: type: number minimum: 1.e-12 maximum: 1000000000000 shotEnabled: type: boolean readSigmaElectrons: type: number minimum: 0 maximum: 1000000 rootSeedHex: type: string pattern: ^[a-f0-9]{64}$ runNamespace: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9_.-]+$ required: - model - electronsPerInputUnit - shotEnabled - readSigmaElectrons - rootSeedHex - runNamespace additionalProperties: false inputDomain: type: string const: renderer-relative-scene-signal responseGainPerRendererSignal: type: number exclusiveMinimum: 0 blackLevelNormalized: type: number minimum: 0 maximum: 1 bitDepth: anyOf: - type: number const: 8 - type: number const: 10 - type: number const: 12 - type: number const: 16 alphaPolicy: type: string const: require-opaque-and-discard required: - schema - inputDomain - responseGainPerRendererSignal - blackLevelNormalized - bitDepth - alphaPolicy additionalProperties: false temporal: type: object properties: schema: type: string const: simforge.camera-temporal-request/v1 captureStage: type: string const: scene-pre-postprocess/v1 noise: type: object properties: model: type: string const: gaussian-electron-ptc/v1 correlatedDetector: type: object properties: model: type: string const: gaussian-row-column-detector/v1 width: type: integer minimum: 1 maximum: 16384 height: type: integer minimum: 1 maximum: 16384 fixedPatternSeedHex: type: string pattern: ^[a-f0-9]{64}$ physicalInstanceId: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9_.-]+$ epoch: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9_.-]+$ rowFixedSigmaElectrons: type: number minimum: 0 maximum: 1000000 columnFixedSigmaElectrons: type: number minimum: 0 maximum: 1000000 rowReadSigmaElectrons: type: number minimum: 0 maximum: 1000000 columnReadSigmaElectrons: type: number minimum: 0 maximum: 1000000 required: - model - width - height - fixedPatternSeedHex - physicalInstanceId - epoch - rowFixedSigmaElectrons - columnFixedSigmaElectrons - rowReadSigmaElectrons - columnReadSigmaElectrons additionalProperties: false electronsPerInputUnit: type: number minimum: 1.e-12 maximum: 1000000000000 shotEnabled: type: boolean readSigmaElectrons: type: number minimum: 0 maximum: 1000000 rootSeedHex: type: string pattern: ^[a-f0-9]{64}$ runNamespace: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9_.-]+$ required: - model - electronsPerInputUnit - shotEnabled - readSigmaElectrons - rootSeedHex - runNamespace additionalProperties: false timing: type: object properties: height: type: integer minimum: 1 maximum: 16384 shutter: type: string enum: - global - rolling readoutDirection: type: string enum: - top-to-bottom - bottom-to-top readoutSeconds: type: number minimum: 0 maximum: 60 exposureSeconds: type: number exclusiveMinimum: 0 maximum: 60 processingLatencySeconds: type: number const: 0 required: - height - shutter - readoutDirection - readoutSeconds - exposureSeconds - processingLatencySeconds additionalProperties: false samplesPerRow: type: integer minimum: 1 maximum: 4096 response: type: object properties: inputDomain: type: string const: renderer-relative-scene-signal-seconds responseGainPerRendererSignalSecond: type: number exclusiveMinimum: 0 blackLevelNormalized: type: number minimum: 0 maximum: 1 bitDepth: anyOf: - type: number const: 8 - type: number const: 10 - type: number const: 12 - type: number const: 16 required: - inputDomain - responseGainPerRendererSignalSecond - blackLevelNormalized - bitDepth additionalProperties: false budgets: type: object properties: maxUniqueCaptures: type: integer minimum: 1 maximum: 4096 maxCapturePixels: type: integer minimum: 1 maximum: 67108864 maxCaptureBytes: type: integer minimum: 1 maximum: 1073741824 maxReductionReadBytes: type: integer minimum: 1 maximum: 1073741824 maxWeightedValues: type: integer minimum: 1 maximum: 268435456 maxSceneActorSamples: type: integer minimum: 1 maximum: 262144 maxResidentPixelBytes: type: integer minimum: 1 maximum: 536870912 maxRetainedBytes: type: integer minimum: 1 maximum: 1073741824 required: - maxUniqueCaptures - maxCapturePixels - maxCaptureBytes - maxReductionReadBytes - maxWeightedValues - maxSceneActorSamples - maxResidentPixelBytes - maxRetainedBytes additionalProperties: false required: - schema - timing - samplesPerRow - response - budgets additionalProperties: false width: type: integer minimum: 64 maximum: 8192 height: type: integer minimum: 64 maximum: 8192 fps: type: number exclusiveMinimum: 0 maximum: 240 horizontalFovDeg: type: number exclusiveMinimum: 0 maximum: 180 cameraModel: type: object properties: type: type: string const: ftheta referenceResolution: minItems: 2 maxItems: 2 type: array items: type: integer minimum: 1 maximum: 8192 principalPoint: minItems: 2 maxItems: 2 type: array items: type: number pixeldistToAnglePoly: minItems: 2 maxItems: 8 type: array items: type: number angleToPixeldistPoly: type: array items: type: number linearCde: minItems: 3 maxItems: 3 type: array items: type: number maxAngleRad: type: number exclusiveMinimum: 0 exclusiveMaximum: 3.141592653589793 required: - type - referenceResolution - principalPoint - pixeldistToAnglePoly - maxAngleRad additionalProperties: false nearM: type: number exclusiveMinimum: 0 farM: type: number exclusiveMinimum: 0 orthographicHeightM: type: number exclusiveMinimum: 0 maximum: 10000 required: - width - height - fps - nearM - farM additionalProperties: false sensorProfile: type: string const: generic-rgb@1 reportedCalibration: type: object properties: transform: $ref: '#/components/schemas/RenderRigTransform' attributes: type: object properties: captureStage: type: string const: scene-pre-postprocess/v1 detector: type: object properties: schema: type: string const: simforge.hdr-detector-config/v1 captureStage: type: string const: scene-pre-postprocess/v1 noise: type: object properties: model: type: string const: gaussian-electron-ptc/v1 correlatedDetector: type: object properties: model: type: string const: gaussian-row-column-detector/v1 width: type: integer minimum: 1 maximum: 16384 height: type: integer minimum: 1 maximum: 16384 fixedPatternSeedHex: type: string pattern: ^[a-f0-9]{64}$ physicalInstanceId: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9_.-]+$ epoch: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9_.-]+$ rowFixedSigmaElectrons: type: number minimum: 0 maximum: 1000000 columnFixedSigmaElectrons: type: number minimum: 0 maximum: 1000000 rowReadSigmaElectrons: type: number minimum: 0 maximum: 1000000 columnReadSigmaElectrons: type: number minimum: 0 maximum: 1000000 required: - model - width - height - fixedPatternSeedHex - physicalInstanceId - epoch - rowFixedSigmaElectrons - columnFixedSigmaElectrons - rowReadSigmaElectrons - columnReadSigmaElectrons additionalProperties: false electronsPerInputUnit: type: number minimum: 1.e-12 maximum: 1000000000000 shotEnabled: type: boolean readSigmaElectrons: type: number minimum: 0 maximum: 1000000 rootSeedHex: type: string pattern: ^[a-f0-9]{64}$ runNamespace: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9_.-]+$ required: - model - electronsPerInputUnit - shotEnabled - readSigmaElectrons - rootSeedHex - runNamespace additionalProperties: false inputDomain: type: string const: renderer-relative-scene-signal responseGainPerRendererSignal: type: number exclusiveMinimum: 0 blackLevelNormalized: type: number minimum: 0 maximum: 1 bitDepth: anyOf: - type: number const: 8 - type: number const: 10 - type: number const: 12 - type: number const: 16 alphaPolicy: type: string const: require-opaque-and-discard required: - schema - inputDomain - responseGainPerRendererSignal - blackLevelNormalized - bitDepth - alphaPolicy additionalProperties: false temporal: type: object properties: schema: type: string const: simforge.camera-temporal-request/v1 captureStage: type: string const: scene-pre-postprocess/v1 noise: type: object properties: model: type: string const: gaussian-electron-ptc/v1 correlatedDetector: type: object properties: model: type: string const: gaussian-row-column-detector/v1 width: type: integer minimum: 1 maximum: 16384 height: type: integer minimum: 1 maximum: 16384 fixedPatternSeedHex: type: string pattern: ^[a-f0-9]{64}$ physicalInstanceId: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9_.-]+$ epoch: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9_.-]+$ rowFixedSigmaElectrons: type: number minimum: 0 maximum: 1000000 columnFixedSigmaElectrons: type: number minimum: 0 maximum: 1000000 rowReadSigmaElectrons: type: number minimum: 0 maximum: 1000000 columnReadSigmaElectrons: type: number minimum: 0 maximum: 1000000 required: - model - width - height - fixedPatternSeedHex - physicalInstanceId - epoch - rowFixedSigmaElectrons - columnFixedSigmaElectrons - rowReadSigmaElectrons - columnReadSigmaElectrons additionalProperties: false electronsPerInputUnit: type: number minimum: 1.e-12 maximum: 1000000000000 shotEnabled: type: boolean readSigmaElectrons: type: number minimum: 0 maximum: 1000000 rootSeedHex: type: string pattern: ^[a-f0-9]{64}$ runNamespace: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9_.-]+$ required: - model - electronsPerInputUnit - shotEnabled - readSigmaElectrons - rootSeedHex - runNamespace additionalProperties: false timing: type: object properties: height: type: integer minimum: 1 maximum: 16384 shutter: type: string enum: - global - rolling readoutDirection: type: string enum: - top-to-bottom - bottom-to-top readoutSeconds: type: number minimum: 0 maximum: 60 exposureSeconds: type: number exclusiveMinimum: 0 maximum: 60 processingLatencySeconds: type: number const: 0 required: - height - shutter - readoutDirection - readoutSeconds - exposureSeconds - processingLatencySeconds additionalProperties: false samplesPerRow: type: integer minimum: 1 maximum: 4096 response: type: object properties: inputDomain: type: string const: renderer-relative-scene-signal-seconds responseGainPerRendererSignalSecond: type: number exclusiveMinimum: 0 blackLevelNormalized: type: number minimum: 0 maximum: 1 bitDepth: anyOf: - type: number const: 8 - type: number const: 10 - type: number const: 12 - type: number const: 16 required: - inputDomain - responseGainPerRendererSignalSecond - blackLevelNormalized - bitDepth additionalProperties: false budgets: type: object properties: maxUniqueCaptures: type: integer minimum: 1 maximum: 4096 maxCapturePixels: type: integer minimum: 1 maximum: 67108864 maxCaptureBytes: type: integer minimum: 1 maximum: 1073741824 maxReductionReadBytes: type: integer minimum: 1 maximum: 1073741824 maxWeightedValues: type: integer minimum: 1 maximum: 268435456 maxSceneActorSamples: type: integer minimum: 1 maximum: 262144 maxResidentPixelBytes: type: integer minimum: 1 maximum: 536870912 maxRetainedBytes: type: integer minimum: 1 maximum: 1073741824 required: - maxUniqueCaptures - maxCapturePixels - maxCaptureBytes - maxReductionReadBytes - maxWeightedValues - maxSceneActorSamples - maxResidentPixelBytes - maxRetainedBytes additionalProperties: false required: - schema - timing - samplesPerRow - response - budgets additionalProperties: false width: type: integer minimum: 64 maximum: 8192 height: type: integer minimum: 64 maximum: 8192 fps: type: number exclusiveMinimum: 0 maximum: 240 horizontalFovDeg: type: number exclusiveMinimum: 0 maximum: 180 cameraModel: type: object properties: type: type: string const: ftheta referenceResolution: minItems: 2 maxItems: 2 type: array items: type: integer minimum: 1 maximum: 8192 principalPoint: minItems: 2 maxItems: 2 type: array items: type: number pixeldistToAnglePoly: minItems: 2 maxItems: 8 type: array items: type: number angleToPixeldistPoly: type: array items: type: number linearCde: minItems: 3 maxItems: 3 type: array items: type: number maxAngleRad: type: number exclusiveMinimum: 0 exclusiveMaximum: 3.141592653589793 required: - type - referenceResolution - principalPoint - pixeldistToAnglePoly - maxAngleRad additionalProperties: false nearM: type: number exclusiveMinimum: 0 farM: type: number exclusiveMinimum: 0 orthographicHeightM: type: number exclusiveMinimum: 0 maximum: 10000 required: - width - height - fps - nearM - farM additionalProperties: false required: - transform - attributes additionalProperties: false required: - actorId - sensorId - outputName - transform - modality - attributes additionalProperties: false - type: object properties: actorId: type: string pattern: ^[0-9A-Za-z][0-9A-Za-z_-]{0,63}$ sensorId: type: string pattern: ^[0-9A-Za-z][0-9A-Za-z_-]{0,63}$ sensorLabel: type: string minLength: 1 maxLength: 200 outputName: $ref: '#/components/schemas/RenderRigOutputName' transform: $ref: '#/components/schemas/RenderRigTransform' modality: type: string const: lidar attributes: type: object properties: observationRun: oneOf: - type: object properties: schema: type: string const: simforge.cloud-lidar-observation/v1 profile: type: string const: generic-uniform-cpu/v1 geometryPolicy: type: string const: authored-dimension-primitives/v1 trajectoryKeyIntervalNs: type: integer minimum: 1 maximum: 10000000000 deliveryDelayNs: type: integer minimum: 0 maximum: 10000000000 consumerArchiveByteLimit: type: integer minimum: 1 maximum: 1073741824 rangeEstimation: type: object properties: effectId: type: string pattern: ^[A-Za-z0-9_-]{1,64}$ randomNamespace: type: string pattern: ^[A-Za-z0-9_-]{1,64}$ seed: type: integer minimum: 0 maximum: 9007199254740991 biasM: type: number minimum: -3.4028234663852886e+38 maximum: 3.4028234663852886e+38 uniformHalfWidthM: type: number minimum: 0 maximum: 3.4028234663852886e+38 profileRef: type: object properties: schema: type: string const: simforge.lidar-fitted-reference-ref/v1 sha256: type: string pattern: ^[a-f0-9]{64}$ sizeBytes: type: integer minimum: 1 maximum: 1048576 required: - schema - sha256 - sizeBytes additionalProperties: false required: - effectId - randomNamespace - seed - biasM - uniformHalfWidthM additionalProperties: false channelFault: type: object properties: effectId: type: string pattern: ^[A-Za-z0-9_-]{1,64}$ channel: type: integer minimum: 0 maximum: 255 startNs: type: integer minimum: 0 maximum: 9007199254740991 endNs: type: integer minimum: 0 maximum: 9007199254740991 required: - effectId - channel - startNs - endNs additionalProperties: false engineering: type: object properties: archiveByteLimit: type: integer minimum: 1 maximum: 1073741824 truthArchiveByteLimit: type: integer minimum: 1 maximum: 1073741824 queryProvenance: type: object properties: maxUniqueTriangles: type: integer minimum: 1 maximum: 4000000 maxInstances: type: integer minimum: 1 maximum: 65536 required: - maxUniqueTriangles - maxInstances additionalProperties: false required: - archiveByteLimit - truthArchiveByteLimit additionalProperties: false required: - schema - profile - geometryPolicy - trajectoryKeyIntervalNs - deliveryDelayNs - consumerArchiveByteLimit additionalProperties: false - type: object properties: schema: type: string const: simforge.cloud-lidar-observation/v2 profile: type: string const: generic-uniform-response-cpu/v1 geometryPolicy: type: string const: authored-dimension-primitives/v1 trajectoryKeyIntervalNs: type: integer minimum: 1 maximum: 10000000000 deliveryDelayNs: type: integer minimum: 0 maximum: 10000000000 consumerArchiveByteLimit: type: integer minimum: 1 maximum: 1073741824 rangeEstimation: type: object properties: effectId: type: string pattern: ^[A-Za-z0-9_-]{1,64}$ randomNamespace: type: string pattern: ^[A-Za-z0-9_-]{1,64}$ seed: type: integer minimum: 0 maximum: 9007199254740991 biasM: type: number minimum: -3.4028234663852886e+38 maximum: 3.4028234663852886e+38 uniformHalfWidthM: type: number minimum: 0 maximum: 3.4028234663852886e+38 profileRef: type: object properties: schema: type: string const: simforge.lidar-fitted-reference-ref/v1 sha256: type: string pattern: ^[a-f0-9]{64}$ sizeBytes: type: integer minimum: 1 maximum: 1048576 required: - schema - sha256 - sizeBytes additionalProperties: false required: - effectId - randomNamespace - seed - biasM - uniformHalfWidthM additionalProperties: false channelFault: type: object properties: effectId: type: string pattern: ^[A-Za-z0-9_-]{1,64}$ channel: type: integer minimum: 0 maximum: 255 startNs: type: integer minimum: 0 maximum: 9007199254740991 endNs: type: integer minimum: 0 maximum: 9007199254740991 required: - effectId - channel - startNs - endNs additionalProperties: false engineering: type: object properties: archiveByteLimit: type: integer minimum: 1 maximum: 1073741824 truthArchiveByteLimit: type: integer minimum: 1 maximum: 1073741824 queryProvenance: type: object properties: maxUniqueTriangles: type: integer minimum: 1 maximum: 4000000 maxInstances: type: integer minimum: 1 maximum: 65536 required: - maxUniqueTriangles - maxInstances additionalProperties: false required: - archiveByteLimit - truthArchiveByteLimit additionalProperties: false receiverResponse: type: object properties: schema: type: string const: simforge.generic-lidar-receiver-response/v1 effectId: type: string pattern: ^[A-Za-z0-9_-]{1,64}$ enabled: type: boolean minSignal: type: number minimum: 0 maximum: 3.4028234663852886e+38 materialResponses: maxItems: 7 type: array items: type: object properties: material: type: string enum: - unknown - asphalt - lane_marking - retroreflective_sign - vehicle_paint - vegetation - building reflectivity: type: number minimum: 0 maximum: 1 required: - material - reflectivity additionalProperties: false required: - schema - effectId - enabled - minSignal - materialResponses additionalProperties: false required: - schema - profile - geometryPolicy - trajectoryKeyIntervalNs - deliveryDelayNs - consumerArchiveByteLimit - receiverResponse additionalProperties: false minimumRangeM: type: number minimum: 0 returnMode: type: string const: single channels: type: integer minimum: 1 maximum: 256 rangeM: type: number exclusiveMinimum: 0 maximum: 1000 pointsPerSecond: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 rotationFrequencyHz: type: number exclusiveMinimum: 0 maximum: 240 upperFovDeg: type: number minimum: -180 maximum: 180 lowerFovDeg: type: number minimum: -180 maximum: 180 horizontalFovDeg: default: 360 type: number minimum: 5 maximum: 360 required: - channels - rangeM - pointsPerSecond - rotationFrequencyHz - upperFovDeg - lowerFovDeg additionalProperties: false required: - actorId - sensorId - outputName - transform - modality - attributes additionalProperties: false - type: object properties: actorId: type: string pattern: ^[0-9A-Za-z][0-9A-Za-z_-]{0,63}$ sensorId: type: string pattern: ^[0-9A-Za-z][0-9A-Za-z_-]{0,63}$ sensorLabel: type: string minLength: 1 maxLength: 200 outputName: $ref: '#/components/schemas/RenderRigOutputName' transform: $ref: '#/components/schemas/RenderRigTransform' modality: type: string const: radar attributes: type: object properties: horizontalFovDeg: type: number exclusiveMinimum: 0 maximum: 180 verticalFovDeg: type: number exclusiveMinimum: 0 maximum: 180 rangeM: type: number exclusiveMinimum: 0 maximum: 1000 pointsPerSecond: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 required: - horizontalFovDeg - verticalFovDeg - rangeM - pointsPerSecond additionalProperties: false required: - actorId - sensorId - outputName - transform - modality - attributes additionalProperties: false - type: object properties: actorId: type: string pattern: ^[0-9A-Za-z][0-9A-Za-z_-]{0,63}$ sensorId: type: string pattern: ^[0-9A-Za-z][0-9A-Za-z_-]{0,63}$ sensorLabel: type: string minLength: 1 maxLength: 200 outputName: $ref: '#/components/schemas/RenderRigOutputName' transform: $ref: '#/components/schemas/RenderRigTransform' modality: type: string const: topdown attributes: type: object properties: width: type: integer minimum: 320 maximum: 3840 height: type: integer minimum: 240 maximum: 2160 fps: type: number exclusiveMinimum: 0 maximum: 120 camera: type: string enum: - follow-ego - overview northUp: type: boolean pxPerM: type: number exclusiveMinimum: 0 maximum: 100 required: - width - height - fps - camera additionalProperties: false required: - actorId - sensorId - outputName - transform - modality - attributes additionalProperties: false RenderRigOutputName: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$ RenderRigTransform: type: object properties: position: $ref: '#/components/schemas/RenderRigVec3' rotation: default: {} type: object properties: yawRad: default: 0 type: number minimum: -3.141593 maximum: 3.141593 pitchRad: default: 0 type: number minimum: -1.5707963267948966 maximum: 1.5707963267948966 rollRad: default: 0 type: number minimum: -3.141593 maximum: 3.141593 additionalProperties: false required: - position additionalProperties: false RenderRigVec3: type: object properties: x: type: number 'y': type: number z: type: number required: - x - 'y' - z additionalProperties: false 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.