REST API Overview

Press.js Cloud exposes a REST API for automating deploys, uploads, rendering, and PDF management. All API requests are authenticated with an API key and communicated over HTTPS.

Base URL

https://api.pressjs.dev/v1

All paths in this guide are relative to this base URL. For example, GET /v1/deploys means:

GET https://api.pressjs.dev/v1/deploys

API version

The current API version is v1. The version is embedded in the URL path (/v1/). Breaking changes will be introduced under a new version path; existing versions remain stable.

Authentication

All requests require a Bearer token in the Authorization header. The token is a Press.js Cloud API key with the prefix pcak_:

Authorization: Bearer pcak_Hxq7sN2mK4vR9wL3pB6tY8jD5fG1cV0

Create and manage API keys from the Press.js Cloud dashboard.

Caution

API keys grant full access to your account resources. Rotate keys regularly and never expose them in client-side code.

Headers

Content-Type

Requests with a body must set Content-Type: application/json.

Content-Type: application/json

Idempotency-Key

Create-type operations (render jobs, upload sessions) support an optional Idempotency-Key header. When provided, the server deduplicates concurrent or retried requests within a 24-hour window:

Idempotency-Key: render-2026-04-28-001

If a request fails (network error, timeout), retry with the same key — the server returns the original result instead of creating a duplicate resource.

Choose a key that is unique across your system, such as a UUID or a composite of your job identifier and date.

X-Upload-Token

Upload session operations (blob upload, commit) require the X-Upload-Token header. This opaque token is returned when the upload session is created and authenticates the caller as the owner of that session:

X-Upload-Token: ustk_L3pB6tY8jD5fG1cV0Hxq7sN2mK4vR9w

The token is separate from your API key and scoped to a single upload session.

JSON error format

All API errors follow a uniform JSON structure:

{
  "error": "deploy_not_found",
  "message": "The specified deploy does not exist or has been deleted."
}

Field	Type	Description
error	string	Machine-readable error code
message	string	Human-readable description of the problem

The HTTP status code indicates the error class:

Status	Meaning
400	Bad request — invalid input
401	Missing or invalid auth
403	Permission denied
404	Resource not found
409	Conflict — state mismatch
410	Gone — resource expired
500	Internal server error
501	Not implemented
503	Service unavailable

See Error Reference for the complete error catalog.

Cursor pagination

List endpoints use cursor-based pagination. Responses include a nextCursor field when more results are available:

{
  "items": [ ... ],
  "nextCursor": "eyJpZCI6ImRwbF8yIn0"
}

To fetch the next page, pass the cursor as a query parameter:

GET /v1/deploys?cursor=eyJpZCI6ImRwbF8yIn0

Cursors are opaque strings — do not interpret or construct them client-side. An absent nextCursor field (or null) means the last page.

Async render polling

Render jobs are processed asynchronously. After creating a job, poll its status with GET /v1/render-jobs/{jobId}:

GET /v1/render-jobs/rj_abc123

The job status transitions through these states:

queued → rendering → succeeded
                  → retry_scheduled → queued → rendering → succeeded/failed
                  → failed

Poll at a reasonable interval — every 2–5 seconds for short renders, longer intervals for batch operations. Use the Idempotency-Key on creation to safely retry the create call if it times out.