Mobius

Sign inGet started
GuidesAPI Reference
Sign inGet started

Guides

Use the Mobius HTTP API to create a workflow definition, launch runs from a backend service or script, and read the terminal result — without touching the dashboard.

Before you start

  • You have a Mobius API key exported as MOBIUS_API_KEY. See Create an API key if you do not.
  • Your project handle is exported as PROJECT and your API base URL as MOBIUS_BASE_URL.
  • At least one worker is registered and actively heartbeating in the project. Runs with worker actions stay in queued until a worker claims them.

Walkthrough

  1. Create the workflow definition with POST /v1/projects/{project}/workflows. The response is 201 Created and contains the definition's id. Record it as WORKFLOW_ID. The handle is auto-derived from name when omitted and must be unique within the org.

    curl -X POST "$MOBIUS_BASE_URL/v1/projects/$PROJECT/workflows" \
  -H "Authorization: Bearer $MOBIUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ingest document",
    "spec": {
      "name": "ingest-document",
      "steps": [
        { "name": "parse", "action": "doc.parse" },
        { "name": "index", "action": "doc.index" }
      ]
    }
  }'

  2. Start a run with POST /v1/projects/{project}/runs. Pass definition_id to target the saved definition. The response is 202 Accepted with status: queued. Record the run id as RUN_ID.

    curl -X POST "$MOBIUS_BASE_URL/v1/projects/$PROJECT/runs" \
  -H "Authorization: Bearer $MOBIUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"definition_id\": \"$WORKFLOW_ID\",
    \"external_id\": \"doc-abc123\",
    \"inputs\": {\"doc_url\": \"https://example.com/doc.pdf\"}
  }"

  3. Subscribe to the run's event stream with GET /v1/projects/{project}/runs/{id}/events. The server writes a seed run_updated frame on connection so reconnects never miss the latest state. Each frame carries {type, run_id, seq, timestamp, data} where type is run_updated, job_updated, or action_appended. Close the stream once you see run_updated with status: completed or status: failed.

    curl --no-buffer "$MOBIUS_BASE_URL/v1/projects/$PROJECT/runs/$RUN_ID/events" \
  -H "Authorization: Bearer $MOBIUS_API_KEY"

  4. Fetch the terminal state with GET /v1/projects/{project}/runs/{id}. A completed run returns status: completed. The result_b64 field carries the base64-encoded terminal result when the workflow produced output.

    curl "$MOBIUS_BASE_URL/v1/projects/$PROJECT/runs/$RUN_ID" \
  -H "Authorization: Bearer $MOBIUS_API_KEY"

Follow-ups

Do the same in the dashboard

Open Projects → <your project> → Workflows, click New workflow, then use the run inspector to launch and observe a run.

Troubleshooting

  • 409 on createWorkflow: a workflow with that name already exists in the project. Choose a different name or update the existing definition with PATCH /v1/projects/{project}/workflows/{id}.
  • 400 on startRun: the request contained both definition_id and spec, or neither. Provide exactly one.
  • Run stays in queued: no worker is registered or actively heartbeating for the queue this run targets. Runs use the default queue when none is specified. Verify at least one worker's last_heartbeat_at is recent.
  • 401 on any call: the key is missing or revoked. Re-issue with Create an API key and re-export MOBIUS_API_KEY.

See also