# Warp Platform API quickstart

> Create and monitor your first cloud agent run via the Warp Platform API in ~5 minutes.

- 网址：https://funcoding.ai/agents/warp/factories/api-and-sdk/quickstart/
- 来源：Warp 官方文档原文（英文），MIT 许可，同步于 2026-10-11
- 官方原文：https://docs.warp.dev/factories/api-and-sdk/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. This quickstart walks you through creating your first run and checking its status.

To dispatch work through a factory's named agents and workflow, use [factory endpoints](https://funcoding.ai/agents/warp/factories/factory-api/) 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](https://github.com/warpdotdev/power-fixer-setup), an issue triage bot built by the Warp team:

---

## Prerequisites

* **A Warp API key** - Create one in the <a href=$https://oz.warp.dev/settings>Oz web app</a> 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://funcoding.ai/agents/warp/platform/agents/). See [API Keys](https://funcoding.ai/agents/warp/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://funcoding.ai/agents/warp/platform/quickstart/) first.

---

## 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.

```bash
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:

```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 `` with your environment ID. Find it with `oz environment list` on the Oz CLI or in the <a href=https://oz.warp.dev>Oz web app</a>.

<div class="callout callout-note">

Prefer typed requests? 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.

</div>

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 `` 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://funcoding.ai/agents/warp/factories/api-and-sdk/troubleshooting/errors/) to interpret the error code.

These are the most common states. See the [Agent & run endpoints](https://funcoding.ai/agents/warp/factories/api-and-sdk/) and [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 <a href=$https://oz.warp.dev/runs>cloud agent dashboard</a>.

---

## Next steps

* **Read the endpoint guide** - [Agent & run endpoints](https://funcoding.ai/agents/warp/factories/api-and-sdk/) documents the configuration and run lifecycle, while the [Warp Platform API reference](https://docs.warp.dev/api) lists all parameters, query filters, and response schemas.
* **Explore the SDKs** - [`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) include typed request/response models, retries, and error handling.
* **See a real-world example** - [Demo: Sentry monitoring with SDK](https://funcoding.ai/agents/warp/factories/api-and-sdk/demo-sentry-monitoring-with-sdk/) shows how to build a webhook handler that triggers agents from production errors.
* **Schedule and automate** - See [Scheduled Agents Quickstart](https://funcoding.ai/agents/warp/platform/triggers/scheduled-agents-quickstart/) to run agents on a cron, or [Integrations Quickstart](https://funcoding.ai/agents/warp/platform/integrations/quickstart/) to trigger agents from Slack or Linear.