{"openapi":"3.1.0","info":{"title":"Ausfüllpilot API","version":"2026-02-09","description":"AI form detection and filling for any PDF — fillable, flat or scanned. API version 2026-02-09. Call it with any HTTP client; see the quickstart for cURL, TypeScript and Python examples.\n\nWebhooks: `edit_run.processed|failed`, `form_detection_run.processed|failed`, `batch.completed`, signed with `x-formfill-signature: t=,v1=.\")>`."},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key (ff_live_… / ff_test_…) or a Ausfüllpilot session token."}},"schemas":{"Error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string","example":"INVALID_OPTIONS"},"message":{"type":"string"},"retryable":{"type":"boolean"},"requestId":{"type":"string"}}},"File":{"type":"object","properties":{"object":{"enum":["file"]},"id":{"type":"string"},"name":{"type":"string"},"type":{"enum":["PDF","IMG","TXT","OTHER"]},"mediaType":{"type":"string"},"size":{"type":"integer"},"parentFileId":{"type":"string"},"metadata":{"type":"object","properties":{"pageCount":{"type":"integer"}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"EditRequest":{"type":"object","required":["file"],"properties":{"file":{"type":"object","description":"One of id (uploaded file), url (public http(s) URL, SSRF-guarded) or data (base64).","properties":{"id":{"type":"string","example":"file_2mB4v1QoKx9Xx0aLJbF7aQ"},"url":{"type":"string","format":"uri"},"data":{"type":"string","description":"Base64 file content (extension)"},"name":{"type":"string"},"settings":{"type":"object","properties":{"password":{"type":"string"}}}}},"config":{"type":"object","properties":{"engineVersion":{"type":"string","enum":["1.0.0","latest"]},"instructions":{"type":"string","description":"Natural-language instructions (who, what, which options)."},"schema":{"type":"object","description":"Edit schema with extend_edit:* keywords; extend_edit:value presets values."},"schemaGenerationInstructions":{"type":"string"},"advancedOptions":{"type":"object","properties":{"flattenPdf":{"type":"boolean","default":true},"tableParsingEnabled":{"type":"boolean","default":false},"radioEnumsEnabled":{"type":"boolean","default":true},"nativeFieldsOnly":{"type":"boolean","default":false},"conditionalGenerationEnabled":{"type":"boolean","default":false}}},"data":{"description":"Extension: any JSON to fill from."},"documents":{"type":"array","items":{"type":"object","description":"One of id (uploaded file), url (public http(s) URL, SSRF-guarded) or data (base64).","properties":{"id":{"type":"string","example":"file_2mB4v1QoKx9Xx0aLJbF7aQ"},"url":{"type":"string","format":"uri"},"data":{"type":"string","description":"Base64 file content (extension)"},"name":{"type":"string"},"settings":{"type":"object","properties":{"password":{"type":"string"}}}}},"description":"Extension: supporting documents (ID scans, letters, earlier forms)."},"checkStyle":{"enum":["check","cross"]},"signatureFont":{"enum":["signature","handwriting"]},"today":{"type":"string","format":"date"},"makeFillable":{"type":"boolean","description":"Extension: return an editable PDF with every detected field as an (empty) AcroForm field."},"aiAssisted":{"type":"boolean","description":"Extension: the values were produced with AI help before this request (e.g. an assistant); the output gets the machine-readable AI marking (XMP ffai:aiAssisted, EU AI Act Art. 50). Requests whose values the model generates are marked automatically."}}}}},"DetectRequest":{"type":"object","required":["file"],"properties":{"file":{"type":"object","description":"One of id (uploaded file), url (public http(s) URL, SSRF-guarded) or data (base64).","properties":{"id":{"type":"string","example":"file_2mB4v1QoKx9Xx0aLJbF7aQ"},"url":{"type":"string","format":"uri"},"data":{"type":"string","description":"Base64 file content (extension)"},"name":{"type":"string"},"settings":{"type":"object","properties":{"password":{"type":"string"}}}}},"config":{"type":"object","properties":{"engineVersion":{"type":"string","enum":["1.0.0","latest"]},"instructions":{"type":"string"},"inputSchema":{"type":"object","description":"Map your own schema onto the form → output.mappingResult."},"advancedOptions":{"type":"object","properties":{"flattenPdf":{"type":"boolean","default":true},"tableParsingEnabled":{"type":"boolean","default":false},"radioEnumsEnabled":{"type":"boolean","default":true},"nativeFieldsOnly":{"type":"boolean","default":false},"conditionalGenerationEnabled":{"type":"boolean","default":false}}}}}}},"EditRun":{"type":"object","properties":{"object":{"enum":["edit_run"]},"id":{"type":"string","example":"edr_…"},"file":{"$ref":"#/components/schemas/File"},"status":{"enum":["PROCESSING","PROCESSED","FAILED","CANCELLED"]},"config":{"type":"object"},"output":{"type":["object","null"],"properties":{"editedFile":{"type":"object","properties":{"id":{"type":"string"},"presignedUrl":{"type":"string","description":"Valid for 15 minutes."}}},"filledValues":{"type":"object"},"schema":{"type":"object"},"review":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"reason":{"type":"string"}}}},"warnings":{"type":"array","items":{"type":"object"}}}},"metrics":{"type":["object","null"]},"usage":{"type":["object","null"]},"failureReason":{"type":"string","enum":["UNABLE_TO_DOWNLOAD_FILE","FILE_TYPE_NOT_SUPPORTED","FILE_SIZE_TOO_LARGE","CORRUPT_FILE","PASSWORD_PROTECTED_FILE","INVALID_OPTIONS","OUT_OF_CREDITS","SCHEMA_VALIDATION_ERROR","LLM_NOT_CONFIGURED","INTERNAL_ERROR"]},"failureMessage":{"type":"string"},"progress":{"type":"object","description":"While PROCESSING: current stage and page."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"FormDetectionRun":{"type":"object","properties":{"object":{"enum":["form_detection_run"]},"id":{"type":"string","example":"fdr_…"},"file":{"$ref":"#/components/schemas/File"},"status":{"enum":["PROCESSING","PROCESSED","FAILED","CANCELLED"]},"config":{"type":"object"},"output":{"type":["object","null"],"properties":{"schema":{"type":"object"},"annotatedSchema":{"type":"object"},"mappingResult":{"type":["object","null"]},"pages":{"type":"array","items":{"type":"object"}},"warnings":{"type":"array","items":{"type":"object"}}}},"metrics":{"type":["object","null"]},"usage":{"type":["object","null"]},"failureReason":{"type":"string"},"failureMessage":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"List":{"type":"object","properties":{"object":{"enum":["list"]},"data":{"type":"array","items":{}},"nextPageToken":{"type":["string","null"]}}}}},"paths":{"/health":{"get":{"summary":"Liveness","tags":["Meta"],"responses":{"200":{"description":"Default Response"}}}},"/health/ready":{"get":{"summary":"Readiness (database reachable)","tags":["Meta"],"responses":{"200":{"description":"Default Response"}}}},"/config":{"get":{"summary":"Server capabilities","tags":["Meta"],"responses":{"200":{"description":"Default Response"}}}},"/files/upload":{"post":{"summary":"Upload a file (multipart/form-data, field \"file\")","tags":["Forms API"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Uploaded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/File"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Quota or plan limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}},"required":["file"]}}}}}},"/files/{id}":{"get":{"summary":"Retrieve a file","tags":["Forms API"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"File","content":{"application/json":{"schema":{"$ref":"#/components/schemas/File"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Quota or plan limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a file","tags":["Forms API"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Deleted"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Quota or plan limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/files/{id}/content":{"get":{"summary":"Download file content (API key or presigned URL)","tags":["Forms API"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"File bytes","content":{"application/pdf":{}}},"403":{"description":"Presigned URL expired"}}}},"/edit":{"post":{"summary":"Fill a form (synchronous)","tags":["Forms API"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Finished edit run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditRun"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Quota or plan limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Retries with the same key within 24 h return the original response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditRequest"}}}}}},"/edit_runs":{"post":{"summary":"Fill a form (asynchronous run)","tags":["Forms API"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Created (PROCESSING)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditRun"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Quota or plan limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Retries with the same key within 24 h return the original response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditRequest"}}}}},"get":{"summary":"List edit runs","tags":["Forms API"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Edit runs, newest first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/List"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Quota or plan limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/edit_runs/{id}":{"get":{"summary":"Retrieve an edit run","tags":["Forms API"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Edit run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditRun"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Quota or plan limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete an edit run (and its output)","tags":["Forms API"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Deleted"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Quota or plan limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/detect_form":{"post":{"summary":"Detect form fields (synchronous)","tags":["Forms API"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Finished detection run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormDetectionRun"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Quota or plan limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Retries with the same key within 24 h return the original response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetectRequest"}}}}}},"/form_detection_runs":{"post":{"summary":"Detect form fields (asynchronous run)","tags":["Forms API"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Created (PROCESSING)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormDetectionRun"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Quota or plan limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Retries with the same key within 24 h return the original response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetectRequest"}}}}},"get":{"summary":"List form detection runs","tags":["Forms API"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Detection runs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/List"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Quota or plan limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/form_detection_runs/{id}":{"get":{"summary":"Retrieve a form detection run","tags":["Forms API"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Detection run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormDetectionRun"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Quota or plan limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a form detection run","tags":["Forms API"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Deleted"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Quota or plan limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/samples":{"get":{"summary":"List bundled sample forms","tags":["Forms API"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/samples/{name}":{"post":{"summary":"Copy a sample form into your files","tags":["Forms API"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"path","name":"name","required":true}],"responses":{"200":{"description":"Default Response"}}}}},"servers":[{"url":"https://api.ausfuellpilot.de"}],"tags":[{"name":"Forms API","description":"Files, edit runs and form detection runs."},{"name":"Meta","description":"Health and capabilities."}]}