> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hardlightsim.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Job lifecycle endpoints and auth model.

Base URL:

`https://api-sim.hardlightsim.com`

Base path:

`/v0`

Managed training base path:

`/v1`

Auth:

`Authorization: Bearer hls_live_your_service_key`

## Core Endpoints

* `POST /v0/jobs` create simulation job.
* `GET /v0/jobs/{job_id}` fetch status + artifacts.
* `GET /v0/jobs` list jobs for authenticated customer.
  * supports `status` and `submission_group_id` filters
* `POST /v0/jobs/{job_id}/cancel` request cancellation.
* `GET /v0/jobs/{job_id}/artifacts/{artifact_name}/download-url` fetch presigned URL.
* `POST /v0/inputs/presign-upload` create upload URL for input files.
* `POST /v0/assets/register` register an input URI and return `asset_id`.
* `GET /v0/assets` list registered input assets.
* `GET /v0/assets/{asset_id}` fetch one registered input asset.

## Asset ID Inputs (Recommended)

Hardsim supports two input styles:

* URI-based: `robot.urdf_uri`, `robot.usd_uri`, `scene.usd_uri`
* Asset-ID based: `robot.urdf_asset_id`, `robot.usd_asset_id`, `scene.usd_asset_id`

When you send `*_asset_id`, the API resolves it to canonical URI server-side before job validation and execution.

## Isaac Lab Submit Additions

`POST /v0/jobs` also supports an Isaac Lab rollout path with:

* `runtime_profile="isaac_lab_rollout"`
* `isaac_lab.task_module`
* `isaac_lab.task_class_or_name`
* `isaac_lab.task_package_asset_id`
* optional `isaac_lab.task_args`

Use this only when you need a custom task package. For the standard customer path, `submit_assets(...)` with robot/scene assets is still the recommended entry point.

## Managed Training Endpoints

* `POST /v1/training-runs`
* `GET /v1/training-runs/{run_id}`
* `POST /v1/training-runs/{run_id}/pause`
* `POST /v1/training-runs/{run_id}/resume`
* `POST /v1/training-runs/{run_id}/cancel`
* `GET /v1/training-runs/{run_id}/iterations`
* `GET /v1/training-runs/{run_id}/checkpoints`
* `GET /v1/training-runs/{run_id}/events`
* `GET /v1/training-runs/{run_id}/checkpoints/{checkpoint_id}/download-url`
* `GET /v1/training-runs/{run_id}/artifacts/download-url?uri=...`
* `GET /v1/training-runs` supports `submission_group_id` filter.

Managed training payload also supports `checkpoint_init_asset_id` (resolved to `checkpoint_init_uri`).

## Submission Group Endpoints

* `POST /v1/submission-groups`
* `POST /v1/submission-groups/{group_id}/ingest`
* `GET /v1/submission-groups/{group_id}`
* `GET /v1/submission-groups`
* `GET /v1/submission-groups/{group_id}/items`
* `GET /v1/submission-groups/{group_id}/events`
* `POST /v1/submission-groups/{group_id}/cancel`

Submission groups are typed (`simulation` or `training`) and support partial accept with per-item machine-readable errors.

Managed training scopes:

* `training:write` for create/pause/resume/cancel.
* `training:read` for get/list/iterations/checkpoints/events.

Managed training guardrail:

* `trainer_spec.resources.gpu` must be greater than `0` (GPU-only trainer policy by default).

## Submit Response Billing Fields

`POST /v0/jobs` includes:

* `estimated_credits`
* `estimated_usd`
* `billing_model`
* `billing_price_id`
* `gpu_hourly_rate_usd`

These values are estimates at submit time. Final debit is settled at terminal state from runtime usage.

## Error Types You Should Handle

* `400` invalid payload (for example, missing required GPU trainer resources).
* `402` insufficient credits / billing guardrail.
* `403` plan not entitled.
* `404` cross-tenant or unknown job.
* `409` idempotency conflict.
* `429` tenant guardrail exceeded.

## Full Contract

Use the guides in this docs site for production request/response patterns:

* [Getting Started](./getting-started)
* [SDK Overview](./sdk-overview)
* [Isaac Lab Jobs](./isaac-lab-jobs)
* [Artifacts and Diagnostics](./artifacts-and-diagnostics)
* [Submission Groups](./submission-groups)