# Process Cart API

> Start a run, set its fields and complete a task from curl in five minutes — then read the conventions every endpoint follows.

Source: https://developers.processcart.com/

The Process Cart REST API gives your code, your no-code tools and your AI agents the same workspace your team uses: workflows, runs, tasks, field values, comments, files, saved views, webhooks, schedules, automation rules and the member directory. It is a plain JSON API over HTTPS with API keys, cursor pagination, RFC 9457 errors and Standard Webhooks, described by an [OpenAPI 3.1 document](https://developers.processcart.com/openapi.json).

- **Base URL:** `https://app.processcart.com/api/v1`
- **Authentication:** `Authorization: Bearer <api key>` — keys are created in **Settings → API** by an Admin ([Authentication & API keys](https://developers.processcart.com/guides/authentication)).
- **Included on every plan**, no approval needed ([Plans, limits & access](https://developers.processcart.com/guides/plans)).
- **Reference:** [every endpoint](https://developers.processcart.com/reference), [errors](https://developers.processcart.com/errors), [events](https://developers.processcart.com/reference/events), [limits](https://developers.processcart.com/reference/limits). AI tools: [llms.txt](https://developers.processcart.com/llms.txt) and a `.md` twin of every page.

**Prefer TypeScript?** The [SDK](https://developers.processcart.com/guides/sdk) wraps every call below in a typed method — `npm install @processcart/sdk` — with pagination, idempotency keys, retries and webhook verification built in.

## Quickstart

Everything below is curl. Replace `pc_live_…` with a key from Settings → API; the key needs the `runs:read`, `runs:write` and `workflows:read` scopes (or full access).

### 1. Identify your key

```bash
curl https://app.processcart.com/api/v1/me \
  -H "Authorization: Bearer pc_live_…"
```

```json
{
  "org": { "id": "0f7c4b3e-…", "name": "Acme", "slug": "acme", "timezone": "America/Los_Angeles", "sandbox": false },
  "key": { "id": "6a1f0c2d-…", "name": "Zapier", "prefix": "pc_live_ab12", "readOnly": false,
           "scopes": ["runs:read", "runs:write", "workflows:read"], "createdAt": "2026-10-01T17:03:11.000Z", "lastUsedAt": null },
  "rateLimit": { "limit": 600, "windowSeconds": 60 }
}
```

Every response carries `X-Request-Id` (quote it to support) and, once authenticated, the `RateLimit-*` headers.

### 2. Find a workflow

```bash
curl "https://app.processcart.com/api/v1/workflows" \
  -H "Authorization: Bearer pc_live_…"
```

Pick a workflow with a `publishedVersion`; its `id` goes into the next call. `GET /v1/workflows/{id}/schema` tells you which fields a run accepts at start and what each one takes.

### 3. Start a run

```bash
curl -X POST https://app.processcart.com/api/v1/runs \
  -H "Authorization: Bearer pc_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: start-7f2c1c2e" \
  -d '{
    "workflowId": "3c1d9e2a-…",
    "name": "Order 1042",
    "fields": { "customer_email": "ada@example.com", "amount": 1700.5 }
  }'
```

The answer is `201 Created` with a `Location` header and the full Run (`revision: 1`): every task with its state, every field with its canonical `value` and display `formatted`. A number is sent as a JSON number (currency in whole units, percent as a fraction); a string is parsed by the field's format — `"$1,700.50"` works too ([Field values & typing](https://developers.processcart.com/guides/field-values)). The `Idempotency-Key` makes a retry safe: the same request again replays the stored answer instead of starting a second run ([Idempotency](https://developers.processcart.com/guides/idempotency)).

### 4. Set field values

```bash
curl -X PATCH https://app.processcart.com/api/v1/runs/{id}/fields \
  -H "Authorization: Bearer pc_live_…" \
  -H "Content-Type: application/json" \
  -H "Expected-Revision: 1" \
  -d '{ "ship_date": "2026-10-09", "approved": true }'
```

One transaction, all-or-nothing: a bad key fails the whole request with every problem listed in `errors[]`. `Expected-Revision` refuses the write if someone changed the run since you read it (409 `revision_mismatch`, whose body names `currentRevision`) — [Concurrency](https://developers.processcart.com/guides/concurrency).

### 5. Complete a task

```bash
curl -X POST "https://app.processcart.com/api/v1/runs/{id}/tasks/{taskKey}/complete" \
  -H "Authorization: Bearer pc_live_…" \
  -H "Idempotency-Key: complete-7f2c1c2e-review"
```

The engine applies the same gates the app does: the task must be visible and unlocked, and its required fields satisfied — otherwise a 422 `required_fields_unsatisfied` names every offender. Approvals are decided with `/approve` and `/reject` under the `approvals:decide` scope ([Tasks, approvals & files](https://developers.processcart.com/guides/tasks-approvals-files)).

### 6. Hear about changes

Subscribe a webhook to `*` (or to specific events) and receive signed deliveries, retried on failure ([Webhooks](https://developers.processcart.com/webhooks)) — or poll `GET /v1/runs?updatedSince=…` ([Incremental sync](https://developers.processcart.com/guides/incremental-sync)).

## Where to go next

| If you want to… | Read |
| --- | --- |
| Understand keys, scopes, read-only keys and allowlists | [Authentication & API keys](https://developers.processcart.com/guides/authentication) |
| Test without touching live data | [Sandbox workspaces](https://developers.processcart.com/guides/sandbox) |
| Read and write runs, tasks and fields | [Runs](https://developers.processcart.com/guides/runs) · [Field values & typing](https://developers.processcart.com/guides/field-values) · [Tasks, approvals & files](https://developers.processcart.com/guides/tasks-approvals-files) |
| Page through and sync large collections | [Pagination](https://developers.processcart.com/guides/pagination) · [Incremental sync](https://developers.processcart.com/guides/incremental-sync) |
| Retry safely and avoid lost updates | [Idempotency](https://developers.processcart.com/guides/idempotency) · [Concurrency](https://developers.processcart.com/guides/concurrency) |
| Handle failures | [Errors](https://developers.processcart.com/errors) · [Rate limits](https://developers.processcart.com/guides/rate-limits) |
| Call the API from TypeScript | [TypeScript SDK](https://developers.processcart.com/guides/sdk) |
| Generate a client | [OpenAPI](https://developers.processcart.com/guides/openapi) |
| Know what will change, and when | [Versioning & deprecation](https://developers.processcart.com/guides/versioning) · [Changelog](https://developers.processcart.com/changelog) |