> For the complete documentation index, see [llms.txt](https://docs.warp.dev/llms.txt).
> Markdown versions of each page are available by appending .md to any URL.

# Warp Platform API quickstart

Create and monitor your first cloud agent run with the Warp Platform API in about five minutes.

Create your first cloud agent run with the Warp Platform API and check its status, in about five minutes. The API runs and manages cloud agents from CI pipelines, backend services, scripts, or custom tooling without the Warp desktop app.

To dispatch work through a factory’s named agents and workflow, use [factory endpoints](https://docs.warp.dev/factories/factory-api/) after this quickstart. The run-management steps below also apply to the factory run those endpoints create.

This short demo shows how the REST API can power agent-backed apps like [PowerFixer](https://github.com/warpdotdev/power-fixer-setup), an issue triage bot built by the Warp team.

![Warp Platform API quickstart video](https://i.ytimg.com/vi/N6qMe641K34/sddefault.jpg)

## Prerequisites

-   **A Warp API key** - Create one in the [Oz web app](https://oz.warp.dev/settings) and copy the raw value. Use a personal key if you want runs attributed to you, or an agent key to attribute runs to a [cloud agent](https://docs.warp.dev/platform/agents/). See [API Keys](https://docs.warp.dev/agents/cli/oz-cli/api-keys/) for the full flow.
-   **A 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](https://docs.warp.dev/platform/quickstart/) first.

## 1\. Set your API key

Export your API key so every command in this quickstart can authenticate through the `WARP_API_KEY` environment variable.

```bash
export WARP_API_KEY="YOUR_API_KEY"
```

Replace `YOUR_API_KEY` with the key you created earlier. Keys start with `wk-`.

## 2\. Create your first run

Submit a prompt to start an agent run:

```bash
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](https://oz.warp.dev).

Note

The official [`warp-platform-sdk` Python package](https://pypi.org/project/warp-platform-sdk/) and [`@warp-dot-dev/warp-platform-sdk` TypeScript package](https://www.npmjs.com/package/@warp-dot-dev/warp-platform-sdk) wrap the same API with typed models, retries, and error handling.

The API returns a `run_id` immediately. The agent starts asynchronously, and you can check its status at any time with the run ID.

## 3\. Check run status

Fetch the current state of the run. Replace `RUN_ID` with the `run_id` from step 2.

```bash
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](https://docs.warp.dev/factories/api-and-sdk/troubleshooting/errors/) to interpret the error code.

These are the most common states. See the [agent and run endpoints](https://docs.warp.dev/factories/api-and-sdk/) and the [Warp Platform API reference](https://docs.warp.dev/api) for all possible values.

To list all recent runs:

```bash
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](https://oz.warp.dev/runs).

## Next steps

You created a run from the command line and read its state and transcript back.

-   [Agent and run endpoints](https://docs.warp.dev/factories/api-and-sdk/) - The configuration options and run lifecycle, with the [Warp Platform API reference](https://docs.warp.dev/api) for every parameter, query filter, and response schema.
-   [`warp-platform-sdk` for Python](https://pypi.org/project/warp-platform-sdk/) and [`@warp-dot-dev/warp-platform-sdk` for TypeScript](https://www.npmjs.com/package/@warp-dot-dev/warp-platform-sdk) - Typed request and response models, retries, and error handling.
-   [Sentry monitoring demo](https://docs.warp.dev/factories/api-and-sdk/demo-sentry-monitoring-with-sdk/) - A webhook handler that starts agents from production errors.
-   [Scheduled agents quickstart](https://docs.warp.dev/platform/triggers/scheduled-agents-quickstart/) and [integrations quickstart](https://docs.warp.dev/platform/integrations/quickstart/) - Run agents on a schedule, or start them from Slack or Linear.