DEVELOPER DOCS

REST API

Authentication, the jobs endpoint, error codes.

Base URL

All engine endpoints are rooted at:

https://api.babbage.owlgcorp.com

Authentication

Every /v1/* call needs one of:

Method	Header	Purpose
`Authorization: Bearer …`	Firebase ID Token	Web UI — auto attached
`X-API-Key: babbage_…`	API Key	External servers / CLIs

If a key is leaked, revoke it from the dashboard immediately. Revocation propagates to the engine within ~5 minutes.

About API keys

Keys are issued as stateless JWTs (HS256). The raw key is shown once in the dashboard — store it in a secret manager.

Format: babbage_<jwt>. The workspace ID is encoded in the JWT — one key = one workspace.
No expiration. Revoke from the dashboard at any time; the engine refreshes its revocation list every 5 minutes.
Verification is signature-only — no DB round-trip on the hot path.

format

babbage_eyJhbGciOiJIUzI1NiIsImtpZCI6IjQ4M2…

POST /v1/jobs

Bind data into a PPTX template and produce a result file.

`POST /v1/jobs`

Request body

{
  "jobId": "doc-id",
  "workspaceId": "<wsId>",
  "inputTemplateSignedUrl": "https://…/source.pptx",
  "inputDataSignedUrl": null,
  "data": { /* JSON */ },
  "outputSignedUrl": "https://…/result.pptx",
  "outputType": "pptx"
}

Response 202 (immediate)

{
  "jobId": "doc-id",
  "status": "running"
}

Processing is asynchronous. The Firestore doc at workspaces/{wsId}/jobs/{jobId} flips status from running to done or failed, and the result is PUT to outputSignedUrl.

Field reference

Field	Type	Description
`jobId`	string	docs.fJobId
`workspaceId`	string	docs.fWsId
`inputTemplateSignedUrl`	string	docs.fTpl
`inputDataSignedUrl`	string \| null	docs.fData
`data`	object \| null	docs.fDataInline
`outputSignedUrl`	string	docs.fOut
`outputType`	"pptx" \| "pdf"	docs.fType

Error codes

Code	Meaning	Response
`400`	request body validation failed	Fix missing fields per response message
`401`	Missing or expired Authorization / X-API-Key	Reissue key or refresh ID Token
`402`	Monthly quota exceeded (quota_exceeded)	Upgrade plan or wait for next cycle
`403`	Not a workspace member, or key belongs to another workspace	Check workspace ID / key permission
`404`	Template or job not found	Verify ID or storage path
`500`	Engine internal error	Check jobs doc's error field; retry with backoff

After async processing, the engine writes failures to the error field on the job doc. Subscribe to the Firestore doc to surface them.

Usage tracking

Each successful render counts against the workspace's monthly bind quota. Failed jobs (engine error, validation) are NOT counted.

locale=en