Warp Platform API quickstart

The Warp Platform API lets you run and manage cloud agents from CI/CD pipelines, backend services, scripts, or custom tooling without the Warp desktop app. Create your first run and check its status in about five minutes.

To dispatch work through a factory’s named agents and workflow, use factory endpoints after this quickstart. The run-management steps below also apply to the factory run those endpoints create.

Watch this short demo of how the REST API can power agent-backed apps like PowerFixer, an issue triage bot built by the Warp team:

Prerequisites

• A Warp API key from the Oz web app settings. See API keys.
• A configured cloud environment with the required repositories and dependencies. See the Cloud agents quickstart.

1. Set your API key

Use a personal key to attribute runs to you, or an agent key to attribute them to a cloud agent.

Export your API key so the API can authenticate your requests automatically — all commands in this guide reference the WARP_API_KEY environment variable.

export WARP_API_KEY="wk-..."

Replace wk-... with the key you created earlier.

2. Create your first run

Submit a prompt to start an agent run:

curl -X POST https://app.warp.dev/api/v1/agent/runs \
  -H "Authorization: Bearer $WARP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Scan the repo for outdated dependencies and summarize the findings.",
    "config": {
      "environment_id": "<ENV_ID>"
    }
  }'

Replace <ENV_ID> with your environment ID. Find it with oz environment list on the Oz CLI or in the Oz web app.

Note

Prefer typed requests? The official warp-platform-sdk Python package and @warp-dot-dev/warp-platform-sdk TypeScript package wrap the same API with typed models, retries, and error handling.

The API returns a run_id immediately. The agent starts asynchronously — you can check its status at any time using the run ID.

3. Check run status

Fetch the current state of the run with the following command. Replace <RUN_ID> with the run_id from step 2.

curl "https://app.warp.dev/api/v1/agent/runs/<RUN_ID>" \
  -H "Authorization: Bearer $WARP_API_KEY"

The state has the following possible values:

• QUEUED - The run is waiting to start.
• INPROGRESS - The agent is actively running.
• SUCCEEDED - The run completed successfully.
• FAILED - The run encountered an error. Check the status_message field in the response for details, then use the API error reference to interpret the error code.

These are the most common states. See the Agent & run endpoints and Warp Platform API reference for all possible values.

To list all recent runs:

curl "https://app.warp.dev/api/v1/agent/runs" \
  -H "Authorization: Bearer $WARP_API_KEY"

4. View the results

Once the run reaches SUCCEEDED, the response includes a session_link — a direct URL to the full run transcript, including commands executed, files changed, and agent output.

You can also view and manage all runs in the cloud agent dashboard.

Next steps

You created a cloud agent run over HTTP and tracked it from QUEUED to SUCCEEDED. From here:

• Read the endpoint guide - Agent & run endpoints documents the configuration and run lifecycle, while the Warp Platform API reference lists all parameters, query filters, and response schemas.
• Explore the SDKs - warp-platform-sdk for Python and @warp-dot-dev/warp-platform-sdk for TypeScript include typed request/response models, retries, and error handling.
• See a real-world example - Demo: Sentry monitoring with SDK shows how to build a webhook handler that triggers agents from production errors.
• Schedule and automate - See the Scheduled Agents quickstart to run agents on a cron, or the Integrations quickstart to trigger agents from Slack or Linear.