Runs — Ramteid Agent (`/a1/runs`)

Runs are asynchronous, repository-bound coding jobs: you hand a GitHub repository and a task prompt to a run-capable runtime, poll the run until it finishes, and receive the agent's summary plus (optionally) a pull-request URL. The first run-capable runtime is Ramteid Agent (ramteid-agent, see GET /a1/runtimes — entries with "runs": true).

Runs differ from /a1/agents/<name>/chat: no conversation, no streaming — a run is a job with a lifecycle (queued → running → succeeded | failed | cancelled | expired).

Prerequisites (all fail-closed)

The operator has enabled the runtime on the gateway (otherwise every call answers 403 ramteid_agent_disabled).
Your tenant has a repository allowlist (ramteid_agent_repos, operator-curated). Repositories outside it answer 403 ramteid_agent_repo_not_allowed.
Your token carries the scope ramteid_agent:use (granted per token via extra_scopes — it is part of no role preset).
Each POST /a1/runs needs an explicit consent header (below).

Consent (two-step confirm)

Starting a run sends the task and repository contents to an external coding runtime. The first POST without consent answers 409 cloud_consent_required; the body carries the required token in required_consents[0].content_hash (= sha256-hex of the canonical repository URL; the error message repeats it). Repeat the request with:

SPASS-Cloud-Consent: <token>

Endpoints

Method	Path	Purpose
POST	`/a1/runs`	Start a run (201; with `idempotency_key` an existing run answers 200)
GET	`/a1/runs?runtime=&status=&limit=`	Your runs, newest first
GET	`/a1/runs/{id}`	Status + result + `pr_url` (non-terminal runs are refreshed live)
POST	`/a1/runs/{id}/cancel`	Cancel an active run
GET	`/a1/runtimes/{id}/models`	Model slugs of the runtime
GET	`/a1/runtimes/{id}/repositories`	Repositories usable by your tenant

Create-request fields

{
  "runtime": "ramteid-agent",
  "repo": "https://github.com/<org>/<repo>",
  "prompt": "Fix the failing unit test in module X",
  "model": "<optional, see /a1/runtimes/ramteid-agent/models>",
  "mode": "agent",
  "auto_create_pr": false,
  "name": "optional display name",
  "starting_ref": "optional branch or commit",
  "idempotency_key": "optional caller key"
}

mode: "plan" produces a plan without writing changes — recommended for a first contact with a repository. SPASS-User-Id is required (ADR 0016); runs are strictly scoped to tenant + user (foreign ids answer 404).

Cost