OpenAPI Spec

The Pharlo publishes a live OpenAPI 3.0 spec, auto-generated from the codebase and always in sync with production.

Spec URLs

URL	Description
`https://pharlo.io/api/doc.json`	OpenAPI 3.0 JSON
`https://pharlo.io/api/doc`	Interactive Swagger UI

The spec is generated directly from PHP attributes in the codebase on every deploy — it is never written by hand. This means it always reflects what the API actually accepts and returns, including current validation constraints, required fields, and enum values.

Download

curl https://pharlo.io/api/doc.json -o openapi.json

Interactive Swagger UI

Open https://pharlo.io/api/doc in your browser to explore every endpoint with live request execution.

To authenticate in Swagger UI:

Click Authorize (top-right lock icon)
In the Bearer field enter your ds_live_... API key
Click Authorize → Close

All requests made from the UI will now include Authorization: Bearer ds_live_....

The Swagger UI is the fastest way to inspect request/response schemas, required fields, and enum values before writing any code. For testing whole workflows interactively, see Postman Collection.

Generate a typed client

Use openapi-generator-cli to scaffold a typed client in your language. The generator reads the spec and produces models, API classes, and serialization code — you don't write HTTP calls by hand.

openapi-generator-cli requires Java 11+. If you prefer not to install Java, use the Docker variant or a language-specific alternative listed below.

Download the spec

curl https://pharlo.io/api/doc.json -o openapi.json

Generate the client

npx @openapitools/openapi-generator-cli generate \
  -i openapi.json \
  -g typescript-fetch \
  -o ./delivery-api-client \
  --additional-properties=supportsES6=true,npmName=delivery-api-client

Use the generated client

import { AssignmentsApi, Configuration } from "./delivery-api-client";
 
const config = new Configuration({
  basePath: "https://pharlo.io",
  accessToken: process.env.DELIVERY_API_KEY,
});
 
const api = new AssignmentsApi(config);
 
const assignment = await api.createAssignment({
  connectionId: "7f3e1a2b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
  type: "video",
  mediaUrl: "https://cdn.example.com/demo.mp4",
  payload: JSON.stringify({ title: "Product Demo", privacy: "public" }),
});
 
console.log("Created:", assignment.id, assignment.status);

Docker

Generate without installing Java or Node.js:

docker run --rm \
  -v $(pwd):/local \
  openapitools/openapi-generator-cli generate \
  -i /local/openapi.json \
  -g typescript-fetch \
  -o /local/delivery-api-client

Language-specific alternatives

Some languages have generators that produce more idiomatic code than the general-purpose openapi-generator-cli:

Language	Tool	Install
Go	`oapi-codegen` (opens in a new tab)	`go install github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@latest`
Python	`openapi-python-client` (opens in a new tab)	`pip install openapi-python-client`
Rust	`openapi-generator` (rust-server) (opens in a new tab)	via `openapi-generator-cli`
TypeScript	`openapi-typescript` (opens in a new tab)	`npm i -D openapi-typescript`

Example — Go with oapi-codegen:

oapi-codegen \
  --package deliveryclient \
  --generate types,client \
  openapi.json > delivery_client.gen.go

Example — TypeScript types only with openapi-typescript:

npx openapi-typescript https://pharlo.io/api/doc.json \
  --output delivery-api.d.ts

This generates only TypeScript types (no HTTP client code) — useful if you want to keep your own fetch calls but get full type coverage.

Validate the spec

Use any of these validators to check the spec is well-formed before feeding it to a generator:

pip install openapi-spec-validator
openapi-spec-validator openapi.json

Use in CI

Keep a downloaded snapshot of the spec in your repository and validate it on each pull request to catch breaking changes early:

# .github/workflows/validate-spec.yml
name: Validate OpenAPI spec
 
on: [pull_request]
 
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Download current spec
        run: curl https://pharlo.io/api/doc.json -o openapi.json
 
      - name: Lint
        run: npx --yes @redocly/cli lint openapi.json
 
      - name: Diff against snapshot
        run: |
          if [ -f openapi.snapshot.json ]; then
            diff <(jq --sort-keys . openapi.snapshot.json) \
                 <(jq --sort-keys . openapi.json) \
              && echo "No breaking changes" \
              || echo "Spec changed — review the diff above"
          fi