> ## Documentation Index > Fetch the complete documentation index at: https://starforge.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Job Overview ## OpenAPI ````yaml /api-reference/openapi.json get /api/job openapi: 3.1.0 info: title: StarForge Console description: >- The StarForge control plane. Everything the `sf` CLI and the web console do goes through this API, and so can your own tooling. Authenticate with a bearer token from `POST /api/auth/login` or a CLI device flow; see the Authentication page for how to get one and how long it lasts. version: 0.3.15 servers: - url: https://{host} description: Your StarForge deployment variables: host: default: starforge.your-company.com description: >- The domain your administrator gave you, without a scheme or trailing slash. security: [] tags: - name: auth description: >- Log in, exchange a CLI device code, and inspect the current identity. Everything else on this API needs a bearer token from here. - name: profile description: >- The signed-in user's own account: quota, tokens, preferences, and notification settings. - name: projects description: >- Projects group runs the way `starforge.yaml` names them. A run belongs to exactly one. - name: experiments description: >- Read the experiment definitions the console found in the configured repository. - name: submit description: >- Admit a JobSpec. This is what `sf submit` calls: the catalog handshake, quota check, and preflight all happen here, and a rejection names the gate that refused it. - name: jobs description: >- Everything about a job after it is admitted: status, logs, metrics, samples, artifacts, and the pause/resume/stop controls. - name: runs description: >- Finished work, addressed by run id. A run outlives the job that produced it. - name: ingest description: >- The endpoints training code reports to. `starforge.report` speaks this; you only call it directly when writing an adapter for a framework the catalog does not cover. - name: datasets description: >- Versioned dataset upload, listing, and metadata. Protected datasets expose identity and schema here but never their records. - name: volumes description: Governed directories of files a job may mount read-only. - name: environments description: >- Agent RL environments: their manifests, versions, and upload URLs. A taskset is never returned. - name: benchmarks description: >- The benchmark catalog, the score matrix across runs, and externally scored evaluations. - name: rubrics description: >- Written scoring standards, their revisions, and which runs cited which version. - name: judge description: >- The LLM-judge endpoint a training job calls to score a rollout. OpenAI-compatible. - name: models description: >- The model registry: register a version, promote it, archive it, read its card. - name: model-deployments description: >- Managed model versions serving application traffic: revisions, promotion, rollback, suspension, and deployment tokens. - name: inference description: >- OpenAI-compatible inference against a promoted deployment revision. This is the endpoint applications call. - name: playground description: >- Short-lived serving sessions for human evaluation. Distinct from a deployment: a session expires, a deployment does not. - name: reflow description: >- The governed path from a deployment's production traffic back to the training data of its next version. - name: annotate description: 'Preference annotation: pull a batch, push judgements, read progress.' - name: plugins description: Installed plugins and the extension shelf the console renders. - name: diagnosis description: >- Automated analysis of a finished or failed run, and the accumulated project memory it draws on. - name: approvals description: 'Approval requests: an escalation path, one level deep, with a record.' - name: billing description: >- What the GPU-hours cost. One price on top of the hours the usage page already shows. - name: teams description: 'Teams: the unit capacity is budgeted to. A department, not a tenant.' - name: agent description: >- Submit plans: a proposed submission a human approves or rejects before it becomes a job. - name: share description: >- Public, revocable read-only links to a job or a comparison. The `/api/share/{token}` routes need no bearer token, which is the point. - name: notifications description: The signed-in user's notification feed. - name: search description: Cross-surface search over jobs, runs, datasets, and models. - name: sandbox description: >- Execute model-generated code in a throwaway container with no GPU and no network. - name: uploads description: >- Resumable upload sessions used by dataset, environment, and plugin publishing. - name: integrations-hf description: Hugging Face account linking and repository push. - name: mcp description: Model Context Protocol access information and per-user tool settings. - name: mcp-oauth description: >- OAuth metadata, authorization, token exchange, and dynamic client registration for MCP clients. - name: cluster description: Live capacity and node state across the fleets. - name: fleets description: >- Registered execution backends and the machines in them. Reading is open to every user; creating a fleet, minting a join token and draining a node are admin-only. Joining is authorized by the join token alone. - name: admin description: >- User, role, quota, hardware, schedule, integration, and settings administration. Admin role required. - name: tasks description: >- Scheduled platform maintenance tasks: what they are, when they last ran, and running one now. - name: report description: The rendered daily report page. - name: health description: Liveness and version. Unauthenticated. paths: /api/job: get: tags: - jobs summary: Job Overview operationId: job_overview_api_job_get parameters: - name: id in: query required: true schema: type: string title: Id responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/JobOverviewOut' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - HTTPBearer: [] components: schemas: JobOverviewOut: properties: job_id: type: string title: Job Id run_id: anyOf: - type: string - type: 'null' title: Run Id recipe: type: string title: Recipe default: unversioned recipe_version: anyOf: - type: string - type: 'null' title: Recipe Version framework: anyOf: - type: string - type: 'null' title: Framework framework_version: anyOf: - type: string - type: 'null' title: Framework Version exp: type: string title: Exp project_key: type: string title: Project Key default: '' name: type: string title: Name default: '' display_name: anyOf: - type: string - type: 'null' title: Display Name project: type: string title: Project default: '' model: anyOf: - type: string - type: 'null' title: Model status: anyOf: - type: string - type: 'null' title: Status retry_count: type: integer title: Retry Count default: 0 can_retry: type: boolean title: Can Retry default: false retry_blocker: type: string title: Retry Blocker default: '' can_rerun: type: boolean title: Can Rerun default: false rerun_blocker: type: string title: Rerun Blocker default: '' note: type: string title: Note default: '' tags: items: type: string type: array title: Tags default: [] start: type: string title: Start default: '-' dur: type: string title: Dur default: '-' running: type: boolean title: Running default: false data_source: type: string title: Data Source default: none steps: items: $ref: '#/components/schemas/JobOverviewStepOut' type: array title: Steps default: [] validations: items: $ref: '#/components/schemas/JobOverviewValidationOut' type: array title: Validations default: [] last_progress_at: anyOf: - type: string - type: 'null' title: Last Progress At primary_series: additionalProperties: items: items: type: number type: array type: array type: object title: Primary Series default: {} summary: additionalProperties: anyOf: - type: number - type: 'null' type: object title: Summary default: {} runtime_contract: anyOf: - $ref: '#/components/schemas/JobRuntimeContractOut' - $ref: '#/components/schemas/JobRuntimeContractErrorOut' - type: 'null' title: Runtime Contract type: object required: - job_id - exp title: JobOverviewOut HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError JobOverviewStepOut: properties: step: type: integer title: Step avg_reward: anyOf: - type: number - type: 'null' title: Avg Reward step_time: anyOf: - type: number - type: 'null' title: Step Time type: object required: - step title: JobOverviewStepOut JobOverviewValidationOut: properties: step: type: integer title: Step avg_reward: anyOf: - type: number - type: 'null' title: Avg Reward accuracy: anyOf: - type: number - type: 'null' title: Accuracy avg_len: anyOf: - type: number - type: 'null' title: Avg Len sample_count: type: integer title: Sample Count default: 0 dist: items: {} type: array title: Dist default: [] metrics: additionalProperties: type: number type: object title: Metrics default: {} type: object required: - step title: JobOverviewValidationOut JobRuntimeContractOut: properties: api_version: type: string title: Api Version framework: type: string title: Framework framework_version: type: string title: Framework Version runtime_id: type: string title: Runtime Id source_artifact: $ref: '#/components/schemas/JobRuntimeArtifactOut' adapter: type: string title: Adapter core_version: type: string title: Core Version recipe: $ref: '#/components/schemas/JobRecipeContractOut' artifact_contract: $ref: '#/components/schemas/JobArtifactContractOut' observability: $ref: '#/components/schemas/JobObservabilityContractOut' recipe_status: type: string title: Recipe Status default: current type: object required: - api_version - framework - framework_version - runtime_id - source_artifact - adapter - core_version - recipe - artifact_contract - observability title: JobRuntimeContractOut JobRuntimeContractErrorOut: properties: error: type: string title: Error type: object required: - error title: JobRuntimeContractErrorOut ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError JobRuntimeArtifactOut: properties: kind: type: string title: Kind reference: type: string title: Reference sha256: anyOf: - type: string - type: 'null' title: Sha256 source_digest: anyOf: - type: string - type: 'null' title: Source Digest architecture: anyOf: - type: string - type: 'null' title: Architecture ray_version: anyOf: - type: string - type: 'null' title: Ray Version type: object required: - kind - reference title: JobRuntimeArtifactOut JobRecipeContractOut: properties: name: type: string title: Name version: type: string title: Version digest: type: string title: Digest primary_metrics: items: type: string type: array title: Primary Metrics default: [] metric_semantics: additionalProperties: $ref: '#/components/schemas/JobMetricSemanticsOut' type: object title: Metric Semantics default: {} validation: anyOf: - $ref: '#/components/schemas/JobValidationContractOut' - type: 'null' type: object required: - name - version - digest title: JobRecipeContractOut JobArtifactContractOut: properties: version: type: string title: Version checkpoints: items: type: string type: array title: Checkpoints logs: items: type: string type: array title: Logs exports: items: type: string type: array title: Exports evaluations: items: type: string type: array title: Evaluations formats: additionalProperties: type: string type: object title: Formats type: object required: - version - checkpoints - logs - exports - evaluations - formats title: JobArtifactContractOut JobObservabilityContractOut: properties: mode: type: string title: Mode url: anyOf: - type: string - type: 'null' title: Url type: object required: - mode title: JobObservabilityContractOut JobMetricSemanticsOut: properties: direction: type: string title: Direction default: higher display: type: string title: Display default: number type: object title: JobMetricSemanticsOut description: |- 一个 canonical 指标「怎么读」。 direction: higher | lower | neutral —— neutral 表示两头都不好（策略熵、优势均值）。 display: ratio（0–1 占比，展示为百分比、差值为百分点）| number JobValidationContractOut: properties: sample_kind: type: string title: Sample Kind default: none reward_semantics: type: string title: Reward Semantics default: none type: object title: JobValidationContractOut description: 验证能力契约：驱动前端验证 Tab 的展示形态。 securitySchemes: HTTPBearer: type: http scheme: bearer ````