JobsService

Hand over work that is bigger than one call: analyze ten thousand rows, move forty thousand files, write to a hundred records. You submit a plan and read receipts; the rows themselves stay on our side and never travel back to you. A job outlives the request that started it, so it is submitted once and read back later.

Every call is a POST to https://api.atmon.ai/automaton.v1.JobsService/<Call> with a JSON body, and authenticates with Authorization: Bearer <your project key>. Field names in JSON are lowerCamelCase, so the field written tool_slug below is toolSlug on the wire. How to call the API has the whole convention.

Calls

SubmitJob

Request SubmitJobRequest, response SubmitJobResponse.

POST /automaton.v1.JobsService/SubmitJob HTTP/1.1
Host: api.atmon.ai
Authorization: Bearer amk_your_project_key
Content-Type: application/json

{
  "programJson": "{}",
  "idempotencyKey": "...",
  "mode": "...",
  "simulateFirst": true
}

The response:

{
  "job": {
    "id": "...",
    "status": "JOB_STATUS_PENDING_PLAN_APPROVAL",
    "programJson": "{}",
    "programHash": "...",
    "estimate": { ... },
    "planApprovalId": "...",
    "park": { ... },
    "stepReceipts": [{ ... }],
    "receipt": { ... },
    "lastError": "...",
    "createdAt": "2026-01-31T09:15:00Z",
    "updatedAt": "2026-01-31T09:15:00Z",
    "finishedAt": "2026-01-31T09:15:00Z",
    "pendingAsk": { ... },
    "saga": { ... },
    "mode": "...",
    "simulatedFrom": "...",
    "skillSlug": "..."
  }
}

GetJob

Request GetJobRequest, response GetJobResponse.

POST /automaton.v1.JobsService/GetJob HTTP/1.1
Host: api.atmon.ai
Authorization: Bearer amk_your_project_key
Content-Type: application/json

{
  "id": "..."
}

The response:

{
  "job": {
    "id": "...",
    "status": "JOB_STATUS_PENDING_PLAN_APPROVAL",
    "programJson": "{}",
    "programHash": "...",
    "estimate": { ... },
    "planApprovalId": "...",
    "park": { ... },
    "stepReceipts": [{ ... }],
    "receipt": { ... },
    "lastError": "...",
    "createdAt": "2026-01-31T09:15:00Z",
    "updatedAt": "2026-01-31T09:15:00Z",
    "finishedAt": "2026-01-31T09:15:00Z",
    "pendingAsk": { ... },
    "saga": { ... },
    "mode": "...",
    "simulatedFrom": "...",
    "skillSlug": "..."
  },
  "simulation": {
    "id": "...",
    "status": "JOB_STATUS_PENDING_PLAN_APPROVAL",
    "programJson": "{}",
    "programHash": "...",
    "estimate": { ... },
    "planApprovalId": "...",
    "park": { ... },
    "stepReceipts": [{ ... }],
    "receipt": { ... },
    "lastError": "...",
    "createdAt": "2026-01-31T09:15:00Z",
    "updatedAt": "2026-01-31T09:15:00Z",
    "finishedAt": "2026-01-31T09:15:00Z",
    "pendingAsk": { ... },
    "saga": { ... },
    "mode": "...",
    "simulatedFrom": "...",
    "skillSlug": "..."
  }
}

ListJobs

Request ListJobsRequest, response ListJobsResponse.

POST /automaton.v1.JobsService/ListJobs HTTP/1.1
Host: api.atmon.ai
Authorization: Bearer amk_your_project_key
Content-Type: application/json

{
  "status": "JOB_STATUS_PENDING_PLAN_APPROVAL",
  "pageSize": 0,
  "pageToken": "...",
  "mode": "...",
  "skillSlug": "..."
}

The response:

{
  "jobs": [{
    "id": "...",
    "status": "JOB_STATUS_PENDING_PLAN_APPROVAL",
    "programJson": "{}",
    "programHash": "...",
    "estimate": { ... },
    "planApprovalId": "...",
    "park": { ... },
    "stepReceipts": [{ ... }],
    "receipt": { ... },
    "lastError": "...",
    "createdAt": "2026-01-31T09:15:00Z",
    "updatedAt": "2026-01-31T09:15:00Z",
    "finishedAt": "2026-01-31T09:15:00Z",
    "pendingAsk": { ... },
    "saga": { ... },
    "mode": "...",
    "simulatedFrom": "...",
    "skillSlug": "..."
  }],
  "nextPageToken": "..."
}

ListJobEvents

ListJobEvents reads one job's log in sequence order, each entry naming the chain that caused it. It is the attribution surface over the engine, and a job of another project reads as missing.

Request ListJobEventsRequest, response ListJobEventsResponse.

POST /automaton.v1.JobsService/ListJobEvents HTTP/1.1
Host: api.atmon.ai
Authorization: Bearer amk_your_project_key
Content-Type: application/json

{
  "jobId": "..."
}

The response:

{
  "events": [{
    "jobId": "...",
    "seq": 0,
    "type": "...",
    "stepId": "...",
    "at": "2026-01-31T09:15:00Z",
    "payloadJson": "{}",
    "principalChain": ["..."]
  }]
}

AnswerAsk

AnswerAsk is how a person answers a question a job addressed to them.

Request AnswerAskRequest, response AnswerAskResponse.

POST /automaton.v1.JobsService/AnswerAsk HTTP/1.1
Host: api.atmon.ai
Authorization: Bearer amk_your_project_key
Content-Type: application/json

{
  "jobId": "...",
  "requestId": "...",
  "principalId": "...",
  "continuation": "...",
  "overridesJson": "{}",
  "note": "...",
  "deliveryId": "..."
}

The response:

{
  "job": {
    "id": "...",
    "status": "JOB_STATUS_PENDING_PLAN_APPROVAL",
    "programJson": "{}",
    "programHash": "...",
    "estimate": { ... },
    "planApprovalId": "...",
    "park": { ... },
    "stepReceipts": [{ ... }],
    "receipt": { ... },
    "lastError": "...",
    "createdAt": "2026-01-31T09:15:00Z",
    "updatedAt": "2026-01-31T09:15:00Z",
    "finishedAt": "2026-01-31T09:15:00Z",
    "pendingAsk": { ... },
    "saga": { ... },
    "mode": "...",
    "simulatedFrom": "...",
    "skillSlug": "..."
  }
}

ListAsks

ListAsks reads the questions a project has addressed to people: what is outstanding, who holds it, what was answered and by whom. Until it existed an ask was visible only by listing jobs and reading pending_ask, so an answered one was visible only by reading a log.

Request ListAsksRequest, response ListAsksResponse.

POST /automaton.v1.JobsService/ListAsks HTTP/1.1
Host: api.atmon.ai
Authorization: Bearer amk_your_project_key
Content-Type: application/json

{
  "state": "ASK_STATE_PENDING",
  "principalId": "...",
  "jobId": "...",
  "standingProgramId": "...",
  "pageSize": 0,
  "pageToken": "..."
}

The response:

{
  "asks": [{
    "pointId": "...",
    "principalId": "...",
    "hopIndex": 0,
    "deliveredPrincipals": ["..."],
    "toolSlug": "...",
    "entityId": "...",
    "toolCallId": "...",
    "deliveredAt": "2026-01-31T09:15:00Z",
    "deadlineAt": "2026-01-31T09:15:00Z",
    "approvalId": "...",
    "exhausted": true,
    "jobId": "...",
    "requestId": "...",
    "state": "ASK_STATE_PENDING",
    "question": "...",
    "answerSchemaJson": "{}",
    "continuations": ["..."],
    "escalation": [{ ... }],
    "askedAt": "2026-01-31T09:15:00Z",
    "decision": { ... },
    "stepId": "...",
    "delivery": "..."
  }],
  "nextPageToken": "..."
}

GetAsk

GetAsk reads one of them.

Request GetAskRequest, response GetAskResponse.

POST /automaton.v1.JobsService/GetAsk HTTP/1.1
Host: api.atmon.ai
Authorization: Bearer amk_your_project_key
Content-Type: application/json

{
  "jobId": "...",
  "requestId": "..."
}

The response:

{
  "ask": {
    "pointId": "...",
    "principalId": "...",
    "hopIndex": 0,
    "deliveredPrincipals": ["..."],
    "toolSlug": "...",
    "entityId": "...",
    "toolCallId": "...",
    "deliveredAt": "2026-01-31T09:15:00Z",
    "deadlineAt": "2026-01-31T09:15:00Z",
    "approvalId": "...",
    "exhausted": true,
    "jobId": "...",
    "requestId": "...",
    "state": "ASK_STATE_PENDING",
    "question": "...",
    "answerSchemaJson": "{}",
    "continuations": ["..."],
    "escalation": [{ ... }],
    "askedAt": "2026-01-31T09:15:00Z",
    "decision": { ... },
    "stepId": "...",
    "delivery": "..."
  }
}

Messages

AnswerAskRequest

AnswerAskRequest lands one principal's answer to an outstanding ask. The answer selects a continuation the program declared and nothing else, and the answering key comes from the authenticated request: an approval ask resolves its approval through policy, and policy refuses a key without the approver role and the very key whose plan parked there.

AnswerAskResponse

Ask

Ask is one outstanding question addressed to a named principal: who holds it now, the channel call that carried it, and when the engine stops waiting. An ask is a judgment point whose handler is a principal, not a separate mechanism, so what releases the job is still an answer naming one of the continuations the program declared.

The question text is not repeated here. It is on the pending judgment this ask belongs to, and a job carries one of each.

AskDecision

AskDecision is the recorded answer to an ask: which continuation it picked, who picked it, and where the answer arrived from. Every surface records the same entry, which is what keeps replay from a recorded answer a pure function.

AskHopSpec

AskHopSpec is one rung of a declared escalation ladder: who it reaches and how long they hold the question. The arguments template is not on the wire, since it is the delivery's business and not the reader's.

CompensationReceipt

CompensationReceipt is one act step's unwind, told honestly: how many of its committed rows the saga tried to undo, how many it undid, and the ones it could not, named. A stranded row is an external resource with no owner until a human takes it, which is why the count is never rounded away.

Cost

Cost is what a step or a job spent. Model spend is metered in micro-USD (one millionth of a dollar) because one row's map call costs less than a cent, and action_count is external effects, the unit an action budget is written in.

CostEstimate

CostEstimate is the projection a human approves.

GetAskRequest

GetAskRequest reads one ask. request_id is optional: naming no request reads the ask the job is waiting on now.

GetAskResponse

GetJobRequest

GetJobResponse

Job

Job is the folded state of one job's event log.

JobEvent

JobEvent is one entry of a job's append-only log, which is the audit answer to "what did this job do". Rows never cross this surface: payload_json is the entry's own payload (a checkpoint, a receipt, a park reason), and the rows a step read or wrote live in collections.

ListAsksRequest

ListAsksRequest pages one project's asks. Every filter narrows; an empty one does not. Asks of another project are absent rather than forbidden, which is the read rule every surface here follows.

ListAsksResponse

ListJobEventsRequest

ListJobEventsResponse

ListJobsRequest

ListJobsResponse

Park

Park is why a running job stopped. approval_id names an approval in the policy queue, judgment the question a job waits on; both are set when the approval was delivered as an ask.

PendingJudgment

PendingJudgment is a declared pause waiting on an answer. It carries the question and the continuations the program declared, never rows: a decision sees counts and reasons.

ProjectedEffect

ProjectedEffect is one line of what a plan would do to the world, derived statically from the program before anything executes. access_class is the catalog's blast-radius class, and a destructive one is what makes a plan park for approval.

Receipt

Receipt is the failure-honesty contract: how many rows went in, how many came out, what was dropped and why, whether the producer saw everything it was supposed to, and what it cost. A job receipt is the fold of its step receipts, so it cannot claim more than the steps proved.

SagaState

SagaState is the same account for the whole job: what its act steps landed and still stands, what was undone, and what is stranded. It is derived from the act steps' outcome collections and the log's compensation entries, and it is unset for a job that never unwound anything.

StepReceipt

StepReceipt is one step's receipt plus what it produced.

SubmitJobRequest

SubmitJobResponse

Enums

JobStatus

AskState

AskState is what an ask is doing now. exhausted is not a state: an ask whose ladder ran out is still pending or escalated, because it still owes a person's answer, and the exhausted flag says nothing more will be delivered.