# OpenAPI

> The OpenAPI 3.1 document — JSON and YAML, generated from the same schemas the API validates with — and how to use it for code generation.

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

The whole API is described by one OpenAPI 3.1 document, generated from the request and response schemas the server validates with, so it cannot drift from the code:

- **JSON:** [`/openapi.json`](https://developers.processcart.com/openapi.json)
- **YAML:** [`/openapi.yaml`](https://developers.processcart.com/openapi.yaml)

Both are served live; the same document is browsable in the [interactive reference](https://developers.processcart.com/reference).

## What is in it

- Every operation with its `operationId`, parameters, request body, every response status it can answer and the exact error `code` list per status — the same list the contract tests hold the routes to.
- Every component schema (`Run`, `RunField`, `Problem`, …), with growable enums marked `x-processcart-open-enum: true`.
- The security schemes (`bearerAuth`, `apiKeyHeader`), the request headers `Idempotency-Key` and `Expected-Revision`, and the response headers: `X-Request-Id`, `RateLimit-*`, `Retry-After`, `Idempotent-Replayed`, `Location`, `Deprecation`, `Sunset`.
- Worked request and response examples captured from real responses by the contract tests, redacted.
- The **`webhooks` object**: one entry per event type with the Standard Webhooks headers (`webhook-id`, `webhook-timestamp`, `webhook-signature`, `x-processcart-event`), the envelope and the per-event `data` schema, and the retry schedule.
- Vendor extensions: `x-processcart-scope` (the scope an operation needs), `x-processcart-allowlist`, `x-processcart-paginated`, `x-processcart-idempotency-key`, and on `info` the rate limit and the webhook retry minutes.

`servers` is `https://app.processcart.com/api` and every path starts with `/v1`.

## Generating a client

The document validates against the OpenAPI 3.1 meta-schema and works with the usual generators — `openapi-typescript`, `openapi-generator`, `kiota`, Postman and Insomnia imports. Keep three conventions in mind:

- **Problem responses** are `application/problem+json`; the `Problem` schema is shared by every error status, narrowed per operation to the codes it can answer.
- **Field values** are typed per field at runtime (`GET /v1/workflows/{id}/schema`), not in the static document: `RunField.value` is the union of every canonical shape. Generate the per-workflow schema when you need exact types.
- **Open enums**: generate them as strings (or add an "unknown" arm) so a new status or event type does not break deserialization.

The official TypeScript SDK, [`@processcart/sdk`](https://developers.processcart.com/guides/sdk), is typed from this document (its types and operations table are generated from it; the methods are written against them): one typed method per operation, plus cursor pagination, idempotency keys, retries and webhook signature verification.