# OpenAPI spec

Download the Pozy OpenAPI 3.1 spec, generate a client in any language, and import the API into Postman, Insomnia or Bruno.

The whole Pozy API is described in one OpenAPI 3.1 document. The API reference and the MCP server's operation catalog are built from it, so it is always the most complete description of what the API does.

```bash Terminal
curl -o pozy-openapi.json https://pozy.ai/openapi.json
```

## What is in the spec

| Part | What you find |
| --- | --- |
| `servers` | `https://api.pozy.ai`. Paths start with `/v1`. |
| `paths` | Every endpoint, more than 1,100 of them, each with an `operationId`, a `summary`, one tag, parameters, request body and response schemas |
| `components.schemas` | Shared objects such as `Post`, `MediaItem` and `SocialAccount` |
| `components.securitySchemes` | `bearerAuth` (your `pz_live_` key) and `connectToken` (the `X-Connect-Token` header used by [headless connect](https://pozy.ai/docs/connect/headless) steps) |
| `webhooks` | Every webhook event and its payload schema. See the [events reference](https://pozy.ai/docs/webhooks/events). |
| `info.version` | The spec version. It changes when endpoints or fields are added. |

### Areas: `x-pozy-area`

Each operation and each tag carries an `x-pozy-area` extension that places it in a product area. The API reference groups endpoints the same way.

| `x-pozy-area` | Covers |
| --- | --- |
| `accounts` | Profiles, connected accounts, connect flows, account settings |
| `publishing` | Posts, media, queues, validation, blogs |
| `analytics` | Post, account and inbox analytics |
| `inbox` | DMs, comments, reviews, mentions |
| `automations` | Comment-to-DM, workflows, sequences, broadcasts, contacts |
| `ads` | Campaigns, ads, audiences, conversions, tracking tags |
| `commerce` | Store products and orders |
| `google-business` | Google Business Profile management |
| `whatsapp` | WhatsApp numbers, templates, flows, calling, business agent |
| `messaging` | SMS, RCS, iMessage, Discord, Slack |
| `telephony` | Phone numbers, calls, voice agents, branded calling |
| `creators` | Creator campaigns and payouts |
| `productivity` | Email, calendar and files |
| `workspace` | API keys, users, webhooks, usage, logs |

## Generate a client

Any OpenAPI 3.1 generator can build a client. Two common choices:

```bash TypeScript types
# Types only, used with a tiny fetch wrapper (openapi-fetch)
npx openapi-typescript https://pozy.ai/openapi.json -o src/pozy.d.ts
npm install openapi-fetch
```
```bash OpenAPI Generator
# Full client in Python, Go, Java, Ruby, PHP, C# and more
npx @openapitools/openapi-generator-cli generate \
  -i https://pozy.ai/openapi.json \
  -g python \
  -o ./pozy-client
```

With the TypeScript types and `openapi-fetch`, every call is checked against the spec:

```ts
import createClient from "openapi-fetch";
import type { paths } from "./pozy.d.ts";

const pozy = createClient<paths>({
  baseUrl: "https://api.pozy.ai",
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});

const { data, error } = await pozy.GET("/v1/posts", {
  params: { query: { status: "scheduled", limit: 20 } },
});
if (error) throw new Error(error.error);
console.log(data.posts?.length);
```

If you would rather not generate anything, [Node.js](https://pozy.ai/docs/sdks/node) shows plain `fetch` calls and a small wrapper you can copy.

### Generate a smaller client

The full spec is large. If you only need one part of the API, cut the spec down to one area before generating. This keeps the publishing endpoints:

```bash Terminal
jq '.paths |= (with_entries(.value |= with_entries(select(.value["x-pozy-area"]? == "publishing")))
              | with_entries(select(.value | length > 0)))' \
  pozy-openapi.json > pozy-publishing.json
```

Point your generator at `pozy-publishing.json`. Shared schemas stay in `components`, so `$ref`s still resolve.

## Import into an API client

| Tool | How |
| --- | --- |
| Postman | **Import → Link**, paste `https://pozy.ai/openapi.json`. Set the collection's auth to **Bearer Token** with `{{POZY_API_KEY}}` and define that variable in an environment. |
| Insomnia | **Create → Import → URL**, paste the spec URL. Add `Authorization: Bearer pz_live_...` in the base environment. |
| Bruno | **Import collection → OpenAPI V3 spec**, choose the downloaded file, then set the bearer token on the collection. |

Use a read-only key while you explore, so a stray click on a `POST` cannot publish anything. See [Authentication](https://pozy.ai/docs/getting-started/authentication).

## Keep up with changes

Pozy adds endpoints and fields often. Additive changes do not break existing clients, so a generated client keeps working, but it will not know about new fields until you regenerate.

- Compare `info.version` with the version you generated from, and regenerate when it moves.
- Read the [changelog](https://pozy.ai/docs/changelog), or poll [`GET /v1/changelog`](https://pozy.ai/docs/api/listChangelog) (no key needed) and filter on `type=breaking_change`. Each entry also says its `impact`, so you can skip the ones marked as needing no action.
- Operations marked `deprecated: true` still work. Move off them when you can, and watch the changelog for removal dates.

## operationIds are the shared vocabulary

The `operationId` of an endpoint is the name it has everywhere:

| Surface | `createPost` becomes |
| --- | --- |
| API reference | [/docs/api/createPost](https://pozy.ai/docs/api/createPost) |
| MCP server | `call_tool` with `id: "createPost"` |

Generators use the same ids for method names, so code generated in any language reads like the reference.