API reference

Every call of the PennyCompute API in one place: how to send your key, what each endpoint does, the limits, and what comes back when a call is refused.

Base URL and key

Every call goes to https://api.pennycompute.com over HTTPS, with JSON bodies of up to 2 MB. Sign in to the dashboard, open Server API keys, name a key and create it. The key starts with pc_live_ and is shown once, so copy it then. Send it on every call as Authorization: Bearer followed by the key. Call the API from your server. GET /v1/services and GET /healthz need no key, and GET /v1/auth/me is a quick check that a key works.

A job from start to finish

Three calls make a file: submit the job, read it until its status is final, then ask for the link of the finished file. The Idempotency-Key is any value of 8 to 128 characters that you choose for this submission. The job reference says what each answer means, and each service’s page and the OpenAPI specification give its input.

A job in three calls
# 1. Submit. Sending this again with the same Idempotency-Key returns the same job.
curl https://api.pennycompute.com/v1/jobs \
  -H "Authorization: Bearer $PENNYCOMPUTE_API_KEY" \
  -H "Idempotency-Key: lighthouse-take-1" \
  -H "Content-Type: application/json" \
  -d '{"service_id":"h3.video.v1","input":{"prompt":"A lighthouse on a rocky headland at sunset. The camera pulls back slowly over the water. Soft wind and distant surf."}}'
# 201: {"id": "7d484be8-7f2f-411f-840e-9ff06b6f725a", "status": "queued", …}

# 2. Read the job until its status is succeeded, failed, cancelled or expired.
curl https://api.pennycompute.com/v1/jobs/$JOB_ID -H "Authorization: Bearer $PENNYCOMPUTE_API_KEY"
# {"id": "7d484be8-…", "status": "succeeded", "charged_fee_micros": "25000", "output_file": {"extension": "mp4", …}, …}

# 3. Get the link of the finished file, then download it. The link needs no key.
curl https://api.pennycompute.com/v1/jobs/$JOB_ID/output -H "Authorization: Bearer $PENNYCOMPUTE_API_KEY"
# {"url": "https://api.pennycompute.com/media/outputs/…/….mp4"}
curl -o clip.mp4 "$OUTPUT_URL"

Send a file or Remotion bundle

Every media file in a job input is a public https link, up to 1 GB. To host one file of up to 100 MB here, ask for a place with POST /v1/assets and PUT the bytes to upload_url. input_url is the same link: use it in the job input. Its type must be video/*, audio/*, a non-SVG image/*, application/octet-stream, application/json or text/plain, and every response is contained by Content-Security-Policy: sandbox; default-src 'none'. For a Remotion bundle, send the relative paths, byte lengths and SHA-256 values of every nonempty regular file to the same endpoint, PUT every upload it returns, and pass its serve_url to remotion.render.v1. Each bundle file can be up to 100 MB, the manifest can list up to 256 files, and all files together can be up to 1 GB. Uploaded files stop being served after 24 hours and are deleted after a further 48-hour margin; a finished file is kept for 3 days.

Upload a file
curl https://api.pennycompute.com/v1/assets \
  -H "Authorization: Bearer $PENNYCOMPUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content_type":"video/mp4"}'
# {"upload_url": "https://api.pennycompute.com/media/inputs/…", "input_url": "https://api.pennycompute.com/media/inputs/…"}

curl -X PUT "$UPLOAD_URL" -H "Content-Type: video/mp4" --data-binary @source.mp4
# 201. Use input_url in a job input.

Endpoints

Every call the API answers, by group. The OpenAPI specification gives the fields of each, and names each with an operationId for a generated client.

Jobs
CallWhat it does
POST /v1/jobsSubmit a job
GET /v1/jobsList your jobs
POST /v1/jobs/estimateCheck the price and capacity for a job
GET /v1/jobs/{id}Read job status and charges
GET /v1/jobs/{id}/outputGet the public link of the finished file
POST /v1/jobs/{id}/cancelCancel a job

Submit work, follow it and fetch the finished file. https://pennycompute.com/docs/jobs says what every answer means.

Services
CallWhat it does
GET /v1/servicesList enabled services
GET /v1/services/{service_id}/capacityRead how busy a service is

What is sold now and how busy each service is.

Uploads
CallWhat it does
POST /v1/assetsPrepare source uploads

Host a source file or a complete Remotion bundle for a job. Any public link works in a job input without an upload.

Webhooks
CallWhat it does
POST /v1/webhook-endpointsRegister a webhook endpoint
GET /v1/webhook-endpointsList webhook endpoints
DELETE /v1/webhook-endpoints/{id}Remove a webhook endpoint

Be told when a job reaches a final state.

Billing
CallWhat it does
GET /v1/billing/balanceRead the prepaid balance
GET /v1/usageList charges and usage entries
GET /v1/invoicesList invoices

The prepaid balance, charges and statements.

Account
CallWhat it does
GET /v1/auth/meRead who is calling

Who a key or a signed-in person belongs to.

Status
CallWhat it does
GET /healthzRead whether the API is up

Whether the API is up.

Dashboard
CallWhat it does
POST /v1/billing/top-upStart a card top-up
GET /v1/org/api-keysList server API keys
POST /v1/org/api-keysCreate a server API key
POST /v1/org/api-keys/{id}/revokeRevoke a server API key
GET /v1/org/membersList the people in the organization
POST /v1/org/members/{id}Change a role
DELETE /v1/org/members/{id}Remove a person
POST /v1/org/invitationsInvite a person
DELETE /v1/org/invitations/{id}Cancel an invitation

Calls the dashboard at https://app.pennycompute.com makes for a signed-in person: keys, top-ups and the people in the organization. A server API key cannot make them.

What a key may call

A key carries two scopes. jobs:write submits and cancels jobs, prepares uploads, and registers and removes webhook endpoints. jobs:read lists and reads jobs, usage, invoices and webhook endpoints. Estimates, capacity, the output link, the balance and GET /v1/auth/me need a key and no particular scope. Creating and revoking keys, adding funds and inviting people are done in the dashboard.

People and roles

The people of an organization sign in to the dashboard, each with one role. An owner or admin invites people by email, changes their roles and removes them; only an owner does this for another owner, and an organization keeps at least one owner. A developer sends jobs and makes server API keys. Billing adds funds and reads jobs, usage and statements. A call the role does not allow answers 403 missing_role.

Errors

A refused call answers with a 4xx or 5xx status and a JSON body {"error": "code"}. The code is stable, so branch on it. 400 invalid_request adds issues, a list of {field, message} that names each refused field. 401 unauthorized: no key was sent, or the key is unknown or revoked. 403 missing_scope: the key lacks the scope the call needs. 404 not_found: no such path, or nothing with that ID in your organization. 409 output_not_ready: the job has not succeeded, so it has no file. 429: a limit was passed. 500 internal_error and 502 supplier_unavailable are faults on our side: send the request again, with the same Idempotency-Key for a submit. The answers of a job submit are in the job reference.

Limits

A key may send 600 requests a minute and an address 1,200. Past that the answer is 429 rate_limited with Retry-After: 60. Job submissions, price checks and capacity reads are each limited to 120 a minute for a key. An organization can have 8 jobs running and 50 queued. Reading a job every few seconds is well inside these limits, and a webhook saves the reads.

Webhooks

POST /v1/webhook-endpoints with a name, a public HTTPS url and the events you want: job.succeeded, job.failed and job.cancelled. When one of your jobs reaches a final state, each endpoint subscribed to that event receives a POST like the one below. job.failed is also sent when a queued job expires, with status expired. Answer with any 2xx within ten seconds. After another answer the delivery is sent again after 5 seconds, 30 seconds, 2 minutes, 10 minutes, 1 hour, 6 hours and 12 hours: eight attempts in all, over about 19 hours. The first attempt is sent as soon as the job has ended, measured at 1.1 seconds after completed_at on 21 November 2026, and by then GET /v1/jobs/{id} already reads the final state, the charge and the output link, so a delivery is the moment to read the job. A job that ends with no word from a renderer, when it expires in the queue or its renderer stops answering, is sent within 3 seconds. The delivery ID is the same on every attempt, so act on it once. To send one job’s events to one endpoint only, pass webhook_endpoint_id beside service_id. A removed endpoint stays in the list as disabled; registering its url again brings it back active under the same id.

A delivery
POST /your/endpoint
Content-Type: application/json
X-PennyCompute-Event: job.succeeded
X-PennyCompute-Delivery: 5b0e6f0a-2c3d-4e5f-8a9b-0c1d2e3f4a5b
X-PennyCompute-Attempt: 1

{
  "id": "5b0e6f0a-2c3d-4e5f-8a9b-0c1d2e3f4a5b",
  "type": "job.succeeded",
  "data": {
    "job_id": "7d484be8-7f2f-411f-840e-9ff06b6f725a",
    "status": "succeeded"
  }
}

# A job that failed:
{
  "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "type": "job.failed",
  "data": {
    "job_id": "7d484be8-7f2f-411f-840e-9ff06b6f725a",
    "status": "failed",
    "failure_code": "download_failed",
    "message": "a link could not be fetched"
  }
}

Clients

The JavaScript client is one file with no dependencies. It has submit, wait, job, output, cancel, jobs, estimate, capacity, services, upload, uploadBundle, balance, usage, me, webhook, webhooks and removeWebhook. For another language, generate a client from the OpenAPI specification, or send the requests on this page as they are.