Skip to content
Warp

Reference > API & SDK

API & SDK quickstart

Open in ChatGPT ↗
Ask ChatGPT about this page
Open in Claude ↗
Ask Claude about this page
Copied!

Create and monitor your first cloud agent run via the Oz API or SDK in ~5 minutes.

The Oz API lets you run and manage cloud agents from anywhere — CI/CD pipelines, backend services, scripts, or custom tooling — without the Warp desktop app. This quickstart walks you through creating your first run and checking its status.

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

Section titled “Prerequisites”
  • A Warp API key - In the Warp app, click your profile photo, then go to Settings > Cloud platform > Oz Cloud API Keys to create a key and copy the raw value. See API Keys for step-by-step instructions.
  • An Oz cloud environment - Agents run inside a configured environment that includes repos and other dependencies. If you don’t have an environment yet, follow the Cloud Agents Quickstart first.

1. Set your API key

Section titled “1. Set your API key”

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

Terminal window
export WARP_API_KEY="wk-..."

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

2. Create your first run

Section titled “2. Create your first run”

Submit a prompt to start an agent run:

Terminal window
curl -X POST https://app.warp.dev/api/v1/agent/run \
  -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.

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

Section titled “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.

Terminal window
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.

These are the most common states. See the full API reference for all possible values.

To list all recent runs:

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

4. View the results

Section titled “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 Oz dashboard.

Next steps

Section titled “Next steps”