Skip to main content

Overview

The REST API lets your own system start and follow workflow runs in a governed AlphaAgent Studio deployment over HTTPS, with an API key instead of a signed-in person. Read this first if you are the integrator writing that system; administrators start at Programmatic access.

Steps​

The base URL is https://<app_domain>/api/v1, where <app_domain> is the address people use to open Studio. Nothing else is served under that prefix, and a Studio sign-in is not accepted there.

  1. Check the API is on. GET /health is the one call that needs no credentials:

    curl https://<app_domain>/api/v1/health

  2. Discover what your key can do. GET /me returns the key's scopes, workflows and limits; GET /workflows lists the active workflows it may run; GET /workflows/{workflow_id} and /parameters return the input contract and readiness.

  3. Start a run. POST /workflows/{workflow_id}/runs with the parameters, an optional free-text input_text, and an Idempotency-Key header.

  4. Follow it. GET /runs lists the runs your key created; GET /runs/{run_id} is one run in full; /steps, /approvals, /events and /pii-redaction give per-step state, the steps waiting for a person, the durable event log and the personally identifiable information (PII) redaction counts.

  5. Collect the outputs. GET /runs/{run_id}/outputs lists what a finished run produced; /outputs/{output_id}/content downloads one file, /outputs.zip all of them.

  6. Stop or erase. POST /runs/{run_id}/cancel stops a run; DELETE /runs/{run_id}/data erases a finished run's inputs, working files and outputs.

What you should see​

GET /health answers 200 in every state:

{"status": "ok", "deployment_id": "<deployment_id>", "api_version": "2026-09-24"}

status is ok when the deployment accepts keys and disabled when it is not governed or has no API key yet. api_version is the API contract date, also the version of the OpenAPI file.

Notes​

  • Governed deployments only. Ownership is set at creation and cannot change; a standard deployment answers 503 deployment_updating (details.reason not_governed, "Programmatic access requires a governed deployment.") on every authenticated route and disabled on /health. See Deploy your first Studio and Working in a governed deployment.
  • Keys come from the Organisations console, under Identity & Access Management, Programmatic Access, created by an Owner, an Operator or a ProgrammaticAccessAdministrator. Studio has no key screen.
  • It reads and runs; it does not build. Workflows, agents, connectors, environments and knowledge graphs are built in Studio only.
  • It never approves. Steps waiting for a person stay in Studio's Inbox; the API reads them and never releases them.
  • It sees only its own runs. A key lists and reads the runs it created; runs started in Studio or by another key answer 404 run_not_found.
  • Connectors need a passing test. A run is refused with 409 workflow_not_ready naming a connector until a passing Test connection is recorded for it; the test at creation counts.
  • No webhooks, no streaming. Poll GET /runs/{run_id} no more than every 5 seconds per run.
  • Per-key limits (60 requests a minute, 100 runs a day, 10 runs in flight by default), the other 503 reasons and every code are on Limits, errors and codes.