Public API

The Public API is the sole public entry point to the Packt Platform. It exposes an HTTP REST/JSON interface that every client application uses — whether built by Packt or by a third party. There are no backdoors, admin endpoints, or internal-only shortcuts.

Base URL and Versioning

Property	Value
Base URL	`https://api.packtpub.services`
Path prefix	`/v0/`
Content type	`application/json`

All endpoints are prefixed with /v0/ while the API is in active development. The v0 prefix signals that the contract may change without notice. When the API stabilises it will move to /v1/.

Example request:

GET /v0/content/documents/doc_abc123 HTTP/1.1
Host: api.packtpub.services
X-Packt-Tenant-Id: tenant_xyz
Authorization: Bearer <api-key>

Authentication

During the development phase (/v0/), all requests are authenticated with an API key passed in the Authorization header as a Bearer token. Keys are scoped per tenant and can be revoked at any time.

When the API moves to /v1/, authentication will require a signed JWT containing tenant and user claims.

Tenant Identification

Every request must include an X-Packt-Tenant-Id header. All authorisation tokens are scoped to an individual tenant. If a client needs access to multiple tenants, it must manage authorisation client-side.

X-Packt-Tenant-Id: tenant_xyz

HTTP Status Codes

Code	Meaning
`200`	OK — request succeeded
`201`	Created — resource was created
`204`	No Content — action succeeded, no body
`304`	Not Modified — cached version is valid
`400`	Bad Request — malformed or invalid input
`401`	Unauthorised — missing or invalid credentials
`403`	Forbidden — valid credentials, insufficient access
`404`	Not Found — resource does not exist
`409`	Conflict — concurrent modification detected
`429`	Too Many Requests — rate limit exceeded
`500`	Internal Server Error
`503`	Service Unavailable — backend dependency down

Error responses include a JSON body with a machine-readable code, a human-readable message, and an optional details array for field-level validation errors.

Idempotency

The API supports idempotency for safely retrying mutation requests. Provide an Idempotency-Key header on any POST, PUT, or PATCH request:

POST /v0/content/documents HTTP/1.1
Idempotency-Key: 7c4a8d09-ca95-427b-a3b0-93f5e4a2f9d1

The API stores the response of the first request for a given key. Subsequent requests with the same key return the same result. Keys are client-generated (V4 UUIDs recommended) and expire after 24 hours.

GET and DELETE requests are idempotent by definition and do not require a key.

Caching

All cacheable responses include Cache-Control, ETag, and Last-Modified headers. Clients should send If-None-Match or If-Modified-Since on subsequent requests to receive 304 Not Modified when nothing has changed.

Most responses carry at least a one-second max-age directive to collapse concurrent requests for the same resource.

Client Permissions

All clients use the same API, but not every client has the same access level. Permissions are scoped to the API key (in v0) or JWT claims (in v1). When a client attempts an action it does not have permission for, the API returns 403 Forbidden.