{"openapi":"3.1.0","info":{"title":"Pluckbox API","version":"1.0.0","description":"Turn PDFs, images and emails into the JSON fields you define, each with a confidence score. Every request carries an API key as Authorization: Bearer pbk_…","contact":{"email":"admin@onibaku.co.uk"}},"servers":[{"url":"https://pluckbox.onibaku.co.uk"}],"security":[{"bearer":[]}],"tags":[{"name":"Parsers","description":"A parser is a template of fields plus its own inbound email address."},{"name":"Documents","description":"Send documents, read results, review low-confidence fields."},{"name":"Webhooks","description":"Get each parsed document posted to you. Also Zapier REST hook subscribe/unsubscribe."},{"name":"Keys","description":"API keys with scopes, expiry and rotation."},{"name":"Account","description":"Plan and page usage."}],"paths":{"/v1/openapi.json":{"get":{"tags":["Account"],"summary":"This OpenAPI document.","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/me":{"get":{"tags":["Account"],"summary":"The key’s workspace, scopes and usage.","x-scope":"read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["workspaceId","scopes","usage"],"properties":{"workspaceId":{"type":"integer"},"email":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"usage":{"$ref":"#/components/schemas/Usage"}}}}}},"400":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/usage":{"get":{"tags":["Account"],"summary":"Pages used this month and the plan’s allowance.","x-scope":"read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"400":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/parsers":{"get":{"tags":["Parsers"],"summary":"List parsers.","x-scope":"read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Parser"}}}}}}},"400":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"tags":["Parsers"],"summary":"Create a parser.","x-scope":"parsers:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParserInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Parser"}}}},"400":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"The free plan’s parser limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/parsers/infer":{"post":{"tags":["Parsers"],"summary":"Propose a template from a sample document.","x-scope":"parsers:write","description":"Doesn’t create anything or use pages. Send the result to POST /v1/parsers. Limited to 20 a day.","requestBody":{"required":true,"description":"The file as the raw body (Content-Type names its type; ?filename= or X-Filename its name), or a multipart form with a `file` field.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}},"image/*":{"schema":{"type":"string","format":"binary"}},"message/rfc822":{"schema":{"type":"string","format":"binary"}},"text/plain":{"schema":{"type":"string"}},"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}},"required":["file"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["name","template"],"properties":{"name":{"type":"string"},"template":{"$ref":"#/components/schemas/Template"},"cost":{"type":"number"}}}}}},"400":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"No fields could be proposed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"AI parsing is off","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/parsers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"get":{"tags":["Parsers"],"summary":"Get a parser.","x-scope":"read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Parser"}}}},"400":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"patch":{"tags":["Parsers"],"summary":"Change a parser.","x-scope":"parsers:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParserInput"}}}},"description":"Send only what changes.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Parser"}}}},"400":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"tags":["Parsers"],"summary":"Delete a parser and its documents.","x-scope":"parsers:write","responses":{"204":{"description":"Deleted"},"400":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/parsers/{id}/export":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"get":{"tags":["Parsers"],"summary":"Export a parser’s documents as CSV or JSON.","x-scope":"read","parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["csv","json"],"default":"csv"}},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/Status"}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"until","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"expand","in":"query","description":"A table field: one CSV row per row of that table.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"text/csv":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Document"}}}}}}},"400":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/parsers/{id}/documents":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"post":{"tags":["Documents"],"summary":"Send a document to a parser.","x-scope":"documents:write","description":"Queues it and returns straight away; poll GET /v1/documents/{id} or use a webhook. Pages are counted now and refunded if it fails for good. Up to 20 MB and 50 pages.","parameters":[{"name":"filename","in":"query","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","description":"Sending the same key again returns the first document.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"The file as the raw body (Content-Type names its type; ?filename= or X-Filename its name), or a multipart form with a `file` field.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}},"image/*":{"schema":{"type":"string","format":"binary"}},"message/rfc822":{"schema":{"type":"string","format":"binary"}},"text/plain":{"schema":{"type":"string"}},"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}},"required":["file"]}}}},"responses":{"200":{"description":"Already received with this Idempotency-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"202":{"description":"Queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"400":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"Not enough pages left this month","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Too big","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Unsupported file type","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Unreadable file","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/documents":{"get":{"tags":["Documents"],"summary":"List documents, newest first.","x-scope":"read","description":"Also works as a Zapier polling trigger: deduplicate on id.","parameters":[{"name":"parser","in":"query","schema":{"type":"integer"}},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/Status"}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","total","limit","offset"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Document"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}},"400":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/documents/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"get":{"tags":["Documents"],"summary":"Get a document and its fields.","x-scope":"read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"400":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"patch":{"tags":["Documents"],"summary":"Review a document: correct fields or approve it.","x-scope":"documents:write","description":"Corrected fields get confidence 1 and the document becomes parsed. Fires document.reviewed.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true},"approve":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"400":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Not parsed yet","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"tags":["Documents"],"summary":"Delete a document and its file.","x-scope":"documents:write","responses":{"204":{"description":"Deleted"},"400":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/documents/{id}/retry":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"post":{"tags":["Documents"],"summary":"Parse a document again.","x-scope":"documents:write","responses":{"202":{"description":"Queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"400":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"Not enough pages left","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Already queued","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"410":{"description":"The file has been deleted","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/webhooks":{"get":{"tags":["Webhooks"],"summary":"List webhooks.","x-scope":"read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}}}}}},"400":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"tags":["Webhooks"],"summary":"Add a webhook (Zapier: subscribe).","x-scope":"webhooks:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"parserId":{"type":["integer","null"]},"events":{"type":"array","items":{"$ref":"#/components/schemas/Event"}}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Webhook"},{"type":"object","required":["secret"],"properties":{"secret":{"type":"string","description":"Signing secret, shown once."}}}]}}}},"400":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/webhooks/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"delete":{"tags":["Webhooks"],"summary":"Remove a webhook (Zapier: unsubscribe).","x-scope":"webhooks:write","responses":{"204":{"description":"Removed"},"400":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/webhooks/{id}/deliveries":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"get":{"tags":["Webhooks"],"summary":"The last 50 deliveries to a webhook.","x-scope":"read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"event":{"$ref":"#/components/schemas/Event"},"status":{"type":"string","enum":["pending","sending","delivered","failed"]},"attempts":{"type":"integer"},"lastStatus":{"type":["integer","null"]},"createdAt":{"type":"string","format":"date-time"}}}}}}}}},"400":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/keys":{"get":{"tags":["Keys"],"summary":"List API keys.","x-scope":"read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Key"}}}}}}},"400":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"tags":["Keys"],"summary":"Create an API key.","x-scope":"keys:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"scopes":{"type":"array","items":{"$ref":"#/components/schemas/Scope"}},"expiresInDays":{"type":"integer"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewKey"}}}},"400":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/keys/{id}/rotate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"post":{"tags":["Keys"],"summary":"Rotate a key.","x-scope":"keys:write","description":"Makes a new key with the same name and scopes. The old one keeps working for graceHours (default 24).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"graceHours":{"type":"integer","default":24}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/NewKey"},{"type":"object","properties":{"previous":{"$ref":"#/components/schemas/Key"}}}]}}}},"400":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/keys/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"delete":{"tags":["Keys"],"summary":"Revoke a key now.","x-scope":"keys:write","responses":{"204":{"description":"Revoked"},"400":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing or invalid key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"webhooks":{"document":{"post":{"summary":"A document event.","description":"Sent for document.parsed, document.failed and document.reviewed, with headers Pluckbox-Event, Pluckbox-Delivery and Pluckbox-Signature (t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<body>\" with your secret>). Answer 2xx within 10 seconds; anything else retries 8 times over about two days.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["event","createdAt"],"properties":{"event":{"$ref":"#/components/schemas/Event"},"createdAt":{"type":"string","format":"date-time"}}},{"$ref":"#/components/schemas/Document"}]}}}},"responses":{"200":{"description":"Received"}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"An API key, pbk_…"}},"schemas":{"Problem":{"type":"object","required":["title","status","detail"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}},"Status":{"type":"string","enum":["queued","processing","parsed","needs_review","failed"]},"Event":{"type":"string","enum":["document.parsed","document.failed","document.reviewed"]},"Scope":{"type":"string","enum":["read","documents:write","parsers:write","webhooks:write","keys:write"]},"Template":{"type":"object","description":"A JSON Schema object of the fields to extract. Fields are string (optionally format date, date-time, email or uri, or an enum), number, integer, boolean, an array of those, or an array of objects of those (a table). Up to 60 fields.","required":["type","properties"],"properties":{"type":{"const":"object"},"properties":{"type":"object","additionalProperties":{"type":"object"}},"required":{"type":"array","items":{"type":"string"},"description":"The fields a document must have. A required field left blank scores 0 and sends the document to review; a blank optional field has no score (null). Leave it out and every field is required."}},"examples":[{"type":"object","properties":{"invoice_number":{"type":"string"},"invoice_date":{"type":"string","format":"date"},"total":{"type":"number"},"lines":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"amount":{"type":"number"}}}}}}]},"ParserInput":{"type":"object","properties":{"name":{"type":"string","maxLength":100},"template":{"$ref":"#/components/schemas/Template"},"instructions":{"type":["string","null"],"maxLength":2000,"description":"Notes for the AI, e.g. \"Dates are UK format\"."},"confidenceThreshold":{"type":"number","minimum":0,"maximum":1,"default":0.7}}},"Parser":{"type":"object","required":["id","name","template","confidenceThreshold","inboundAddress","createdAt"],"properties":{"id":{"type":"integer"},"name":{"type":"string"},"template":{"$ref":"#/components/schemas/Template"},"instructions":{"type":["string","null"]},"confidenceThreshold":{"type":"number"},"inboundAddress":{"type":"string","description":"Email documents here; attachments and body are parsed together."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Document":{"type":"object","required":["id","parserId","status","needsReview","source","pages","data","confidence","lowConfidenceFields","createdAt"],"properties":{"id":{"type":"integer"},"parserId":{"type":"integer"},"parserName":{"type":["string","null"]},"status":{"$ref":"#/components/schemas/Status"},"needsReview":{"type":"boolean"},"source":{"type":"string","enum":["api","upload","email"]},"filename":{"type":["string","null"]},"mediaType":{"type":"string"},"pages":{"type":"integer","description":"Billable pages: PDF pages, 1 per image, 1 per 3,000 characters of text or email body."},"emailFrom":{"type":["string","null"]},"emailSubject":{"type":["string","null"]},"data":{"type":["object","null"],"additionalProperties":true,"description":"Field values, null until parsed."},"confidence":{"type":["object","null"],"additionalProperties":{"type":"number"},"description":"Each field’s confidence, 0 to 1."},"lowConfidenceFields":{"type":"array","items":{"type":"string"}},"model":{"type":["string","null"]},"attempts":{"type":"integer"},"error":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"finishedAt":{"type":["string","null"],"format":"date-time"},"reviewedAt":{"type":["string","null"],"format":"date-time"}}},"Usage":{"type":"object","required":["plan","pagesPerMonth","pagesUsed","pagesLeft"],"properties":{"plan":{"type":"string","enum":["free","pro"]},"blocks":{"type":"integer","description":"Blocks of 1,000 pages a month bought."},"pagesPerMonth":{"type":"integer"},"pagesUsed":{"type":"integer"},"pagesLeft":{"type":"integer"},"parsersAllowed":{"type":["integer","null"]},"history":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string"},"pages":{"type":"integer"}}}}}},"Webhook":{"type":"object","required":["id","url","events"],"properties":{"id":{"type":"integer"},"url":{"type":"string"},"parserId":{"type":["integer","null"]},"events":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"createdAt":{"type":"string","format":"date-time"},"lastStatus":{"type":["integer","null"]},"lastError":{"type":["string","null"]},"lastAttemptAt":{"type":["string","null"]}}},"Key":{"type":"object","required":["id","name","scopes","prefix"],"properties":{"id":{"type":"integer"},"name":{"type":"string"},"scopes":{"type":"array","items":{"$ref":"#/components/schemas/Scope"}},"prefix":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":["string","null"]},"lastUsedAt":{"type":["string","null"]},"requestCount":{"type":"integer"}}},"NewKey":{"allOf":[{"$ref":"#/components/schemas/Key"},{"type":"object","required":["key"],"properties":{"key":{"type":"string","description":"The key itself, shown once."}}}]}}}}