{"openapi":"3.1.0","info":{"title":"MicroPDF","version":"0.1.0","description":"Bounded English PDF extraction. Upload → quote → x402 payment → poll → result. Keep the document token secret. Page numbers are one-based. Tables and reading order are heuristic; always inspect warnings."},"servers":[{"url":"https://api.micropdf.cloud"}],"components":{"securitySchemes":{"documentToken":{"type":"http","scheme":"bearer","description":"Capability returned once at upload; authorizes all document quotes and jobs."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"Job":{"type":"object","required":["id","status","error","attempts","resultUrl","payment"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["quoted","settling","uncertain","paid","queued","running","succeeded","failed","deleted"]},"error":{"type":["string","null"]},"attempts":{"type":"integer","minimum":0},"resultUrl":{"type":["string","null"]},"payment":{"type":["object","null"],"properties":{"transaction":{"type":"string"},"network":{"type":"string"}}}}},"QuoteInput":{"type":"object","additionalProperties":false,"properties":{"pages":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"integer","minimum":1}},"ocr":{"type":"string","enum":["auto","never"],"default":"auto"}}},"Warning":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"page":{"type":"integer"}}},"Result":{"type":"object","required":["schemaVersion","pages","markdown","warnings","partial"],"properties":{"schemaVersion":{"const":"1.0"},"markdown":{"type":"string"},"partial":{"type":"boolean"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/Warning"}},"pages":{"type":"array","items":{"$ref":"#/components/schemas/Page"}}}},"Page":{"type":"object","required":["page","width","height","method","blocks","warnings"],"properties":{"page":{"type":"integer"},"width":{"type":"number"},"height":{"type":"number"},"method":{"enum":["native","ocr","failed"]},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/Warning"}},"blocks":{"type":"array","items":{"$ref":"#/components/schemas/Block"}}}},"Block":{"type":"object","properties":{"type":{"enum":["paragraph","heading","list","table"]},"text":{"type":"string"},"bbox":{"type":"object","description":"Coordinates in PDF points, top-left origin","properties":{"x":{"type":"number"},"y":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"}}},"rows":{"type":"array","items":{"type":"array","items":{"type":"string"}}}}}}},"paths":{"/health":{"get":{"operationId":"health","responses":{"200":{"description":"API alive"}}}},"/v1/capabilities":{"get":{"operationId":"capabilities","responses":{"200":{"description":"Current limits, pricing and supported features"}}}},"/v1/documents":{"post":{"operationId":"uploadDocument","description":"One PDF up to configured limits. Inspection is unpaid and rate-limited. Response includes the only copy of the bearer token.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"}}}},"application/json":{"schema":{"type":"object","required":["url"],"additionalProperties":false,"properties":{"url":{"type":"string","format":"uri","description":"Public HTTPS URL, no credentials, port 443 only"}}}}}},"responses":{"201":{"description":"Document, token, inspection and expiry","content":{"application/json":{"schema":{"type":"object","required":["id","token","expiresAt","inspection"],"properties":{"id":{"type":"string"},"token":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"inspection":{"type":"object"}}}}}},"400":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/documents/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"inspectDocument","security":[{"documentToken":[]}],"responses":{"200":{"description":"Inspection and expiry"},"400":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteDocument","security":[{"documentToken":[]}],"description":"Delete source and results. Already-running processing may finish before temporary working memory is released. Payment audit tombstones remain.","responses":{"204":{"description":"Deleted"},"400":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/documents/{id}/quotes":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"createQuote","security":[{"documentToken":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteInput"}}}},"responses":{"201":{"description":"Immutable quote; amount is atomic USDC (six decimals)","content":{"application/json":{"schema":{"type":"object","required":["id","amount","expiresAt","executeUrl"],"properties":{"id":{"type":"string"},"amount":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"executeUrl":{"type":"string","format":"uri"}}}}}},"400":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/quotes/{id}/execute":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"executeQuote","security":[{"documentToken":[]}],"description":"First request returns 402. Retry with SDK-signed PAYMENT-SIGNATURE and the same Idempotency-Key. No body options. 409 PAYMENT_UNCERTAIN means stop retrying payment and contact operator.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}},{"name":"PAYMENT-SIGNATURE","in":"header","schema":{"type":"string"}}],"responses":{"202":{"description":"Paid job accepted or existing job returned","headers":{"PAYMENT-RESPONSE":{"schema":{"type":"string"},"description":"Base64 x402 settlement receipt"}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"statusUrl":{"type":"string"}}}}}},"400":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required or invalid authorization","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64 x402 v2 payment requirements"}}},"404":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/jobs/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getJob","security":[{"documentToken":[]}],"responses":{"200":{"description":"Job/payment state, result URL and payment reference","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/jobs/{id}/result":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getResult","security":[{"documentToken":[]}],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","markdown"],"default":"json"}}],"responses":{"200":{"description":"Extraction result; check partial and warnings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}},"text/markdown":{"schema":{"type":"string"}}}},"400":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request rejected; see error code and message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}