API: runs

Note

Generated from the OpenAPI contract — do not edit by hand. Interactive explorer with full schemas: https://entherium.duckdns.org:8443/reference; frozen spec for this build: openapi.json.

GET /api/v1/runs

List Runs

Open as a page →

filtered, paginated run list (default sort createtime:desc).

Auth: Authorization: Bearer <token> required

Parameter	In	Required	Type	Description
status	query	no	string | null
pipeline_id	query	no	string | null
entity	query	no	string | null
contract	query	no	integer | null
limit	query	no	integer
offset	query	no	integer
sort	query	no	string

Responses:

Code	Meaning	Body
200	Successful Response	RunListResponse
401	Missing or invalid authentication credentials	ErrorResponse
422	Validation Error	HTTPValidationError

POST /api/v1/runs

Launch Run

Open as a page →

validate, create a queued run, stage the fixture, enqueue the job.

Auth: Authorization: Bearer <token> required

Parameter	In	Required	Type	Description
Idempotency-Key	header	no	string	Optional.

Request body: application/json — schema RunLaunchRequest

Field	Type	Required	Description
allow_regenerate	boolean	no
entity	string	yes
guid	integer	yes
mode	"live" | "mock" | "replay"	no
params	object	no
pipeline_id	string	yes
pipeline_variant	string | null	no
pipeline_version	string | null	no
steps	array of string | null	no

Example:

{
  "allow_regenerate": false,
  "entity": "generated_articles",
  "guid": 31567,
  "mode": "live",
  "params": {},
  "pipeline_id": "generate"
}

Responses:

Code	Meaning	Body
201	Successful Response	PipelineRunRead
401	Missing or invalid authentication credentials	ErrorResponse
409	The record already generated successfully and allow_regenerate is false, or the entity is locked	ErrorResponse
422	Validation Error	HTTPValidationError
429	Agent token: the concurrent-run cap for this token is reached	ErrorResponse

Example response (201):

{
  "createtime": "2026-09-03T02:14:04Z",
  "current_step": "make_article_structure",
  "entity_guid": 31567,
  "entity_name": "generated_articles",
  "guid": 1842,
  "metrics": {
    "llm_calls": 11
  },
  "mode": "live",
  "pipeline_id": "generate",
  "started_at": "2026-09-03T02:14:05Z",
  "started_by": "agent@entherium.dev",
  "status": "running",
  "steps_done": 7,
  "steps_total": 18,
  "trigger": "api",
  "updatetime": "2026-09-03T02:19:40Z"
}

GET /api/v1/runs/pipelines

List Pipelines

Open as a page →

every registered pipeline definition.

Auth: Authorization: Bearer <token> required

Responses:

Code	Meaning	Body
200	Successful Response	array of PipelineDefRead
401	Missing or invalid authentication credentials	ErrorResponse

GET /api/v1/runs/pipelines/{pipeline_id}

Get Pipeline Def

Open as a page →

a single pipeline definition.

Auth: Authorization: Bearer <token> required

Parameter	In	Required	Type	Description
pipeline_id	path	yes	string

Responses:

Code	Meaning	Body
200	Successful Response	PipelineDefRead
401	Missing or invalid authentication credentials	ErrorResponse
422	Validation Error	HTTPValidationError

GET /api/v1/runs/preflight

Run Preflight

Open as a page →

Can this run launch? Returns can_launch + blocking reasons WITHOUT creating a run, so a caller can check quota, pool and pipeline state before spending a launch.

Auth: Authorization: Bearer <token> required

Parameter	In	Required	Type	Description
pipeline_id	query	yes	string
guid	query	yes	integer
entity	query	no	string | null

Responses:

Code	Meaning	Body
200	Successful Response	object
401	Missing or invalid authentication credentials	ErrorResponse
422	Validation Error	HTTPValidationError

GET /api/v1/runs/schedules

List Schedules

Open as a page →

every schedule, newest first.

Auth: Authorization: Bearer <token> required

Responses:

Code	Meaning	Body
200	Successful Response	array of RunScheduleRead
401	Missing or invalid authentication credentials	ErrorResponse

POST /api/v1/runs/schedules

Create Schedule

Open as a page →

create a schedule (validates pipeline + cron; computes next_fire_at).

Auth: Authorization: Bearer <token> required

Parameter	In	Required	Type	Description
Idempotency-Key	header	no	string	Optional.

Request body: application/json — schema RunScheduleCreate

Field	Type	Required	Description
cron	string	yes
enabled	boolean	no
entity	string	yes
max_targets_per_fire	integer	no
mode	string	no
name	string	yes
params	object	no
pipeline_id	string	yes
selector	object	yes
steps	array of string | null	no

Responses:

Code	Meaning	Body
201	Successful Response	RunScheduleRead
401	Missing or invalid authentication credentials	ErrorResponse
422	Validation Error	HTTPValidationError

DELETE /api/v1/runs/schedules/{schedule_id}

Delete Schedule

Open as a page →

delete a schedule (idempotent).

Auth: Authorization: Bearer <token> required

Parameter	In	Required	Type	Description
schedule_id	path	yes	integer
Idempotency-Key	header	no	string	Optional.

Responses:

Code	Meaning	Body
204	Successful Response	—
401	Missing or invalid authentication credentials	ErrorResponse
422	Validation Error	HTTPValidationError

GET /api/v1/runs/schedules/{schedule_id}

Get Schedule

Open as a page →

a single schedule.

Auth: Authorization: Bearer <token> required

Parameter	In	Required	Type	Description
schedule_id	path	yes	integer

Responses:

Code	Meaning	Body
200	Successful Response	RunScheduleRead
401	Missing or invalid authentication credentials	ErrorResponse
422	Validation Error	HTTPValidationError

PATCH /api/v1/runs/schedules/{schedule_id}

Update Schedule

Open as a page →

partial update; a changed cron recomputes next_fire_at.

Auth: Authorization: Bearer <token> required

Parameter	In	Required	Type	Description
schedule_id	path	yes	integer
Idempotency-Key	header	no	string	Optional.

Request body: application/json — schema RunScheduleUpdate

Field	Type	Required	Description
cron	string | null	no
enabled	boolean | null	no
max_targets_per_fire	integer | null	no
mode	string | null	no
name	string | null	no
params	object | null	no
selector	object | null	no
steps	array of string | null	no

Responses:

Code	Meaning	Body
200	Successful Response	RunScheduleRead
401	Missing or invalid authentication credentials	ErrorResponse
422	Validation Error	HTTPValidationError

POST /api/v1/runs/schedules/{schedule_id}/fire

Fire Now

Open as a page →

fire now (same seam as the tick-loop / an external Cloud Scheduler).

Auth: Authorization: Bearer <token> required

Parameter	In	Required	Type	Description
schedule_id	path	yes	integer
Idempotency-Key	header	no	string	Optional.

Responses:

Code	Meaning	Body
200	Successful Response	ScheduleFireResult
401	Missing or invalid authentication credentials	ErrorResponse
422	Validation Error	HTTPValidationError

GET /api/v1/runs/schedules/{schedule_id}/runs

Schedule Runs

Open as a page →

guids of the runs this schedule produced (params.schedule_id).

Auth: Authorization: Bearer <token> required

Parameter	In	Required	Type	Description
schedule_id	path	yes	integer

Responses:

Code	Meaning	Body
200	Successful Response	array of integer
401	Missing or invalid authentication credentials	ErrorResponse
422	Validation Error	HTTPValidationError

GET /api/v1/runs/{run_guid}

Get Run

Open as a page →

run record + its steps + target card + pipeline def.

Auth: Authorization: Bearer <token> required

Parameter	In	Required	Type	Description
run_guid	path	yes	integer

Responses:

Code	Meaning	Body
200	Successful Response	RunDetailResponse
401	Missing or invalid authentication credentials	ErrorResponse
422	Validation Error	HTTPValidationError

POST /api/v1/runs/{run_guid}/cancel

Cancel Run

Open as a page →

Cancel a run. A queued run is cancelled immediately; a run that is already executing is marked cancelled but finishes its current execution (mid-flight interruption is not implemented). Idempotent: a terminal run answers 409.

Auth: Authorization: Bearer <token> required

Parameter	In	Required	Type	Description
run_guid	path	yes	integer
Idempotency-Key	header	no	string	Optional.

Responses:

Code	Meaning	Body
200	Successful Response	PipelineRunRead
401	Missing or invalid authentication credentials	ErrorResponse
409	The run is already terminal	ErrorResponse
422	Validation Error	HTTPValidationError

Example response (200):

{
  "createtime": "2026-09-03T02:14:04Z",
  "current_step": "make_article_structure",
  "entity_guid": 31567,
  "entity_name": "generated_articles",
  "guid": 1842,
  "metrics": {
    "llm_calls": 11
  },
  "mode": "live",
  "pipeline_id": "generate",
  "started_at": "2026-09-03T02:14:05Z",
  "started_by": "agent@entherium.dev",
  "status": "running",
  "steps_done": 7,
  "steps_total": 18,
  "trigger": "api",
  "updatetime": "2026-09-03T02:19:40Z"
}

GET /api/v1/runs/{run_guid}/log

Get Run Log

Open as a page →

assembled log; step filters to one step, tail keeps last N.

Auth: Authorization: Bearer <token> required

Parameter	In	Required	Type	Description
run_guid	path	yes	integer
step	query	no	string | null
tail	query	no	integer | null

Responses:

Code	Meaning	Body
200	Successful Response	RunLogResponse
401	Missing or invalid authentication credentials	ErrorResponse
422	Validation Error	HTTPValidationError

POST /api/v1/runs/{run_guid}/retry

Retry Run

Open as a page →

create a new run; from_step resumes from a step snapshot.

Auth: Authorization: Bearer <token> required

Parameter	In	Required	Type	Description
run_guid	path	yes	integer
Idempotency-Key	header	no	string	Optional.

Request body: application/json — schema RunRetryRequest

Field	Type	Required	Description
from_step	string | null	no

Example:

{
  "from_step": "step_15_make_layout"
}

Responses:

Code	Meaning	Body
201	Successful Response	PipelineRunRead
401	Missing or invalid authentication credentials	ErrorResponse
409	The run cannot be retried from its current state	ErrorResponse
422	Validation Error	HTTPValidationError
429	Agent token: the concurrent-run cap for this token is reached	ErrorResponse

Example response (201):

{
  "createtime": "2026-09-03T02:14:04Z",
  "current_step": "make_article_structure",
  "entity_guid": 31567,
  "entity_name": "generated_articles",
  "guid": 1842,
  "metrics": {
    "llm_calls": 11
  },
  "mode": "live",
  "pipeline_id": "generate",
  "started_at": "2026-09-03T02:14:05Z",
  "started_by": "agent@entherium.dev",
  "status": "running",
  "steps_done": 7,
  "steps_total": 18,
  "trigger": "api",
  "updatetime": "2026-09-03T02:19:40Z"
}

GET /api/v1/runs/{run_guid}/steps

Get Run Steps

Open as a page →

the step rows of a run, ordered by seq/attempt.

Auth: Authorization: Bearer <token> required

Parameter	In	Required	Type	Description
run_guid	path	yes	integer

Responses:

Code	Meaning	Body
200	Successful Response	array of RunStepRead
401	Missing or invalid authentication credentials	ErrorResponse
422	Validation Error	HTTPValidationError