OpenAPI spec

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.

curl -o pozy-openapi.json https://pozy.ai/openapi.json

#What is in the spec

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

#Generate a client

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

# 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

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

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

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 $refs still resolve.

#Import into an API client

Use a read-only key while you explore, so a stray click on a POST cannot publish anything. See 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, or poll GET /v1/changelog (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:

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