Jobs

A Job is a saved configuration for an async unit of AI work. A Job Run is a single execution of that job with its own status, timestamps, and output.

Endpoints

Method	Path	Description
`GET`	`/jobs/schemas`	List available job types and config schemas
`POST`	`/jobs`	Create a job
`GET`	`/jobs`	List jobs
`GET`	`/jobs/{job_id}`	Get a job
`GET`	`/jobs/{job_id}/latest-run`	Get the most recent run for a job
`PATCH`	`/jobs/{job_id}`	Update a job
`DELETE`	`/jobs/{job_id}`	Delete a job
`POST`	`/job-runs`	Trigger a job run
`GET`	`/job-runs`	List job runs
`GET`	`/job-runs/{job_run_id}`	Get a job run
`POST`	`/job-runs/{job_run_id}/cancel`	Cancel a running or pending job run

Get job schemas

GET /jobs/schemas Returns all available job types with their full config schemas and field descriptions. Example request:

curl "https://spacex.atlas.arenaphysica.com/api/v1/jobs/schemas" \
  -H "Authorization: Bearer $ATLAS_TOKEN"

Response fields (array of objects):

Field	Type	Description
`job_type`	string	Job type identifier (use this as `job_type` in `POST /jobs`)
`display_name`	string	Human-readable name shown in the UI
`description`	string	Internal description of what the job does
`user_facing_description`	string	User-facing description
`json_schema`	object	Full JSON Schema for the `config` field when creating a job
`creatable_on_ui`	boolean	Whether users can create this job type from the UI
`creatable_by_agent`	boolean	Whether Atlas can create this job type automatically
`visible_on_ui`	boolean	Whether this job type appears in the UI

Example response:

[
  {
    "job_type": "metagraph_update",
    "display_name": "Metagraph Update",
    "description": "Updates the system metagraph based on uploaded documents.",
    "user_facing_description": "Analyzes uploaded documents and updates the system graph.",
    "json_schema": {
      "type": "object",
      "properties": {
        "job_type": {"type": "string"},
        "system_id_or_name": {"type": "string"},
        "additional_context": {"type": "string"}
      },
      "required": ["job_type", "system_id_or_name"]
    },
    "creatable_on_ui": true,
    "creatable_by_agent": true,
    "visible_on_ui": true
  }
]

Create a job

POST /jobs Request body:

Field	Required	Type	Description
`job_type`	Yes	string	Job type identifier (e.g. `metagraph_update`, `generate_issue`)
`config`	No	object	Job-type-specific config. Must include `job_type` matching the top-level field
`source_session_id`	No	UUID	Associate this job with a session
`source_project_id`	No	UUID	Associate this job with a project

Use GET /jobs/schemas to retrieve the full config schema for a job type before creating a job.

Example request:

curl -X POST "https://spacex.atlas.arenaphysica.com/api/v1/jobs" \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "job_type": "metagraph_update",
    "config": {
      "job_type": "metagraph_update",
      "system_id_or_name": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "additional_context": "Focus on the power distribution subsystem"
    }
  }'

Response fields:

Field	Type	Nullable	Description
`uuid`	UUID	No	Job identifier
`name`	string	No	Auto-generated job name
`description`	string	Yes	Job description
`config`	object	No	Full config object for this job
`is_deleted`	boolean	No	Soft-delete flag
`created_by`	string	No	Creator email
`created_at`	string	No	ISO 8601 creation timestamp
`updated_at`	string	Yes	ISO 8601 last-update timestamp
`source_session_id`	UUID	Yes	Associated session
`source_project_id`	UUID	Yes	Associated project

Example response:

{
  "uuid": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "name": "metagraph_update – Power Distribution Unit",
  "description": null,
  "config": {
    "job_type": "metagraph_update",
    "system_id_or_name": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "additional_context": "Focus on the power distribution subsystem"
  },
  "is_deleted": false,
  "created_by": "engineer@example.com",
  "created_at": "2026-04-13T10:10:00.000000",
  "updated_at": null,
  "source_session_id": null,
  "source_project_id": null
}

List jobs

GET /jobs Query parameters:

Parameter	Type	Description
`job_types`	string (repeatable)	Filter by job type
`created_by_users`	string (repeatable)	Filter by creator email
`source_session_ids`	UUID (repeatable)	Filter by source session
`created_after`	string	ISO 8601 lower bound
`created_before`	string	ISO 8601 upper bound

Example request:

curl "https://spacex.atlas.arenaphysica.com/api/v1/jobs" \
  -H "Authorization: Bearer $ATLAS_TOKEN"

Returns {"items": [...], "count": N} where each item is a job object with the same fields as the create response.

Get a job

GET /jobs/{job_id} Example request:

curl "https://spacex.atlas.arenaphysica.com/api/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $ATLAS_TOKEN"

Returns a job object with the same fields as the create response.

Get latest run

GET /jobs/{job_id}/latest-run Example request:

curl "https://spacex.atlas.arenaphysica.com/api/v1/jobs/$JOB_ID/latest-run" \
  -H "Authorization: Bearer $ATLAS_TOKEN"

Returns the most recent job run object with the same fields as the trigger response. Returns 204 No Content if the job has no runs yet.

Update a job

PATCH /jobs/{job_id} All fields are optional.

Field	Type	Description
`config`	object	Updated job config

Example request:

curl -X PATCH "https://spacex.atlas.arenaphysica.com/api/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"config": {"job_type": "metagraph_update", "additional_context": "Focus on power rail issues"}}'

Returns the updated job object with the same fields as the create response.

Delete a job

DELETE /jobs/{job_id} Soft-deletes a job. Example request:

curl -X DELETE "https://spacex.atlas.arenaphysica.com/api/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $ATLAS_TOKEN"

Example response:

{
  "message": "Job d4e5f6a7-b8c9-0123-defa-234567890123 soft deleted"
}

Trigger a job run

POST /job-runs Request body:

Field	Required	Type	Description
`job_id`	Yes	UUID	ID of the job to run
`config`	No	object	Runtime config overrides

Example request:

curl -X POST "https://spacex.atlas.arenaphysica.com/api/v1/job-runs" \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"job_id": "d4e5f6a7-b8c9-0123-defa-234567890123"}'

Response fields:

Field	Type	Nullable	Description
`uuid`	UUID	No	Job run identifier
`job_id`	UUID	No	Parent job
`job_name`	string	No	Name of the parent job
`config`	object	No	Config used for this run
`status`	string	No	Current run status (see below)
`created_by`	string	No	Creator email
`created_at`	string	No	ISO 8601 creation timestamp
`updated_at`	string	No	ISO 8601 last-update timestamp
`is_deleted`	boolean	No	Soft-delete flag
`output_references`	array	No	References to outputs produced by this run

Job run status values:

Value	Description
`pending`	Queued, not yet started
`running`	Currently executing
`paused`	Execution paused
`completed`	Finished successfully
`failed`	Encountered an error
`cancelled`	Stopped before completion

Example response:

{
  "uuid": "e5f6a7b8-c9d0-1234-efab-345678901234",
  "job_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "job_name": "metagraph_update – Power Distribution Unit",
  "config": {
    "job_type": "metagraph_update",
    "system_id_or_name": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "status": "pending",
  "created_by": "engineer@example.com",
  "created_at": "2026-04-13T10:11:00.000000",
  "updated_at": "2026-04-13T10:11:00.000000",
  "is_deleted": false,
  "output_references": []
}

Get a job run

GET /job-runs/{job_run_id} Example request:

curl "https://spacex.atlas.arenaphysica.com/api/v1/job-runs/$JOB_RUN_ID" \
  -H "Authorization: Bearer $ATLAS_TOKEN"

Returns a job run object with the same fields as the trigger response. Poll this endpoint until status reaches completed, failed, or cancelled.

List job runs

GET /job-runs Query parameters:

Parameter	Type	Description
`job_id`	UUID	Filter to runs for a specific job
`job_types`	string (repeatable)	Filter by job type
`statuses`	string (repeatable)	Filter by status
`created_after`	string	ISO 8601 lower bound
`created_before`	string	ISO 8601 upper bound

Example request:

curl "https://spacex.atlas.arenaphysica.com/api/v1/job-runs?job_id=$JOB_ID" \
  -H "Authorization: Bearer $ATLAS_TOKEN"

Returns {"items": [...], "count": N} where each item is a job run object with the same fields as the trigger response.

Cancel a job run

POST /job-runs/{job_run_id}/cancel Example request:

curl -X POST "https://spacex.atlas.arenaphysica.com/api/v1/job-runs/$JOB_RUN_ID/cancel" \
  -H "Authorization: Bearer $ATLAS_TOKEN"

Response fields:

Field	Type	Description
`message`	string	Confirmation message
`cancelled_count`	integer	Number of tasks cancelled

Example response:

{
  "message": "Job run e5f6a7b8-c9d0-1234-efab-345678901234 cancelled",
  "cancelled_count": 1
}

Overview

Resources

Endpoints

Get job schemas

Create a job

List jobs

Get a job

Get latest run

Update a job

Delete a job

Trigger a job run

Get a job run

List job runs

Cancel a job run

Overview

Resources

​Endpoints

​Get job schemas

​Create a job

​List jobs

​Get a job

​Get latest run

​Update a job

​Delete a job

​Trigger a job run

​Get a job run

​List job runs

​Cancel a job run

Endpoints

Get job schemas

Create a job

List jobs

Get a job

Get latest run

Update a job

Delete a job

Trigger a job run

Get a job run

List job runs

Cancel a job run