{"openapi":"3.1.0","info":{"title":"Parser API","version":"1.0.0","description":"The product API on api.parserai.co, all at the root (no /v1 or /api prefix): auth, documents, entities, extraction, billing."},"paths":{"/auth/login":{"post":{"tags":["Auth"],"summary":"Login","description":"Authenticate with email and password to receive an access token. Accepts both JSON and form-data.","operationId":"login_auth_login_post","requestBody":{"content":{"application/json":{"schema":{"properties":{"email":{"type":"string","format":"email","example":"user@example.com"},"password":{"type":"string","example":"your_password"}},"type":"object","required":["email","password"]}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{},"example":{"access_token":"your_access_token","token_type":"bearer"}}}},"403":{"description":"Email not confirmed yet (self-service signup) — \"Please verify your email before signing in.\""}}}},"/auth/logout":{"post":{"tags":["Auth"],"summary":"Logout","description":"Sign out the current user and invalidate their session","operationId":"logout_auth_logout_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{},"example":{"message":"Successfully logged out"}}}}},"security":[{"OAuth2PasswordBearer":[]}]}},"/auth/session":{"get":{"tags":["Auth"],"summary":"Get Session","description":"Get current user session information","operationId":"get_session_auth_session_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Response Get Session Auth Session Get"},"example":{"user":{"id":"your_user_id","email":"user@example.com","user_metadata":{"email":"user@example.com","email_verified":true,"phone_verified":false,"role":"user","sub":"your_user_id"}}}}}}},"security":[{"OAuth2PasswordBearer":[]}]}},"/auth/forgot-password":{"post":{"tags":["Auth"],"summary":"Forgot Password","description":"Send password reset email to the user","operationId":"forgot_password_auth_forgot_password_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForgotPasswordRequest","properties":{"email":{"type":"string","format":"email","example":"user@example.com"},"cf-turnstile-response":{"type":"string","example":"TURNSTILE_TOKEN"}},"type":"object","required":["email","cf-turnstile-response"]}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{},"example":{"message":"If an account with this email exists, a password reset link has been sent."}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/auth/reset-password":{"post":{"tags":["Auth"],"summary":"Reset Password","description":"Reset user's password using the token received via email","operationId":"reset_password_auth_reset_password_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResetPasswordRequest","properties":{"token":{"type":"string","example":"your_access_token"},"password":{"type":"string","example":"new_secure_password_123"}},"type":"object","required":["token","password"]}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{},"example":{"message":"Password updated successfully."}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/auth/signup":{"post":{"tags":["Auth"],"summary":"Signup","description":"Create an account (Free plan). The account stays unconfirmed — and /auth/login answers 403 — until the link e-mailed to the address is opened (POST /auth/verify-email). Same response whether or not the address already has an account; an existing confirmed owner is e-mailed a notice instead. Password: 8–72 bytes.","operationId":"signup_auth_signup_post","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","example":"user@example.com"},"password":{"type":"string","example":"secure_password_123"},"full_name":{"type":["string","null"],"example":"Jane Doe"},"cf-turnstile-response":{"type":"string","example":"TURNSTILE_TOKEN"},"plan":{"type":["string","null"],"enum":["starter","pro",null],"description":"The plan picked before signing up. It does not change the account's plan (always Free): it rides in the e-mailed link so the console offers that plan's checkout once the account is confirmed.","example":"starter"},"interval":{"type":["string","null"],"enum":["month","year",null],"description":"Billing interval of that checkout. Ignored without plan.","example":"month"},"signup_proof":{"type":"string","description":"Optional random per-browser value (16–200 chars); /auth/verify-email from the same browser then needs no password."}},"required":["email","password","cf-turnstile-response"]}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{},"example":{"message":"Check your email — we've sent a link to finish setting up your account."}}}},"400":{"description":"Password too short/long or invalid Turnstile token"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"503":{"description":"Turnstile not configured/unreachable (fails closed)"}}}},"/auth/verify-email":{"post":{"tags":["Auth"],"summary":"Verify Email","description":"Confirm the e-mail address with the token from the signup e-mail (single use, 24h) and sign the user in — same response as /auth/login. Signs in without a password only when signup_proof matches the one sent at signup (the same browser); otherwise send the account's password. A link stops working once the account's password changes.","operationId":"verify_email_auth_verify_email_post","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","example":"token_from_the_email_link"},"signup_proof":{"type":"string","description":"The random per-browser value sent with /auth/signup or /auth/resend-verification."},"password":{"type":"string","description":"The account's password; required when signup_proof is missing or does not match."}},"required":["token"]}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{},"example":{"access_token":"eyJhbGciOi...","token_type":"bearer"}}}},"400":{"description":"Invalid or expired confirmation link"},"403":{"description":"Password required (no matching signup_proof) or wrong password; the link stays valid"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/auth/resend-verification":{"post":{"tags":["Auth"],"summary":"Resend Verification","description":"Send a new confirmation link to an account that has not confirmed its e-mail yet. Generic response whatever the address's state; at most one e-mail per account per minute.","operationId":"resend_verification_auth_resend_verification_post","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","example":"user@example.com"},"cf-turnstile-response":{"type":"string","example":"TURNSTILE_TOKEN"},"plan":{"type":["string","null"],"enum":["starter","pro",null],"description":"The plan picked before signing up. It does not change the account's plan (always Free): it rides in the e-mailed link so the console offers that plan's checkout once the account is confirmed.","example":"starter"},"interval":{"type":["string","null"],"enum":["month","year",null],"description":"Billing interval of that checkout. Ignored without plan.","example":"month"},"signup_proof":{"type":"string","description":"Optional random per-browser value (16–200 chars); /auth/verify-email from the same browser then needs no password."}},"required":["email","cf-turnstile-response"]}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{},"example":{"message":"If this email has an account waiting for confirmation, a new link has been sent."}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/auth/google/start":{"get":{"tags":["Auth"],"summary":"Google Sign-In Start","description":"Begin \"Continue with Google\": redirects (302) to Google's consent screen (authorization code + PKCE). Redirects back to the SPA with an `error` when Google sign-in is not configured for this environment.","operationId":"google_start_auth_google_start_get","responses":{"302":{"description":"Redirect to Google (or to the SPA with #error=unavailable)"}}}},"/auth/google/callback":{"get":{"tags":["Auth"],"summary":"Google Sign-In Callback","description":"Google's redirect target. Validates state/nonce, exchanges the code, then finds, links (by verified e-mail) or creates the account and redirects (302) to the SPA with a single-use `#code=` (or `#error=`).","operationId":"google_callback_auth_google_callback_get","responses":{"302":{"description":"Redirect to the SPA with #code=… or #error=…"}}}},"/auth/google/exchange":{"post":{"tags":["Auth"],"summary":"Google Sign-In Exchange","description":"Trade the single-use code from the Google callback redirect (valid 60 s) for a session — same response as /auth/login.","operationId":"google_exchange_auth_google_exchange_post","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","example":"code_from_the_redirect"}},"required":["code"]}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{},"example":{"access_token":"eyJhbGciOi...","token_type":"bearer"}}}},"400":{"description":"Invalid or expired sign-in code"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/auth/user":{"get":{"tags":["Auth"],"summary":"Get User Profile","operationId":"get_user_profile_auth_user_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResponse"},"example":{"id":"your_user_id","email":"user@example.com","role":"user","created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T10:30:00Z","user_metadata":{"Data":"Data"}}}}}},"security":[{"OAuth2PasswordBearer":[]}]}},"/documents/upload-limits":{"get":{"tags":["Documents"],"summary":"Get Upload Limits","description":"Get the caller's document allowance for the current monthly window, from their plan.\n\n`subscription_plan` is the plan in force (a lapsed paid plan reads \"free\"). There is no daily cap: `daily_limit` is always \"unlimited\" and `remaining_uploads` is what is left of the month's document allowance (\"unlimited\" when the plan has none). No plan limits documents per month today (volume is measured in credits, see `GET /plan/usage`), so `has_limit` is false and `monthly_limit` / `monthly_used` / `monthly_remaining` are null.","operationId":"get_upload_limits_documents_upload_limits_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadLimitResponse"},"example":{"subscription_plan":"free","uploads_today":1,"daily_limit":"unlimited","remaining_uploads":"unlimited","has_limit":false,"monthly_limit":null,"monthly_used":null,"monthly_remaining":null}}}},"404":{"description":"Not found"}},"security":[{"OAuth2PasswordBearer":[]}]}},"/documents/":{"get":{"tags":["Documents"],"summary":"List Documents","description":"Lists documents for the authenticated user with pagination and search.\n\nArgs:\n    page: Page number (1-based)\n    limit: Number of documents per page (max 100)\n    search: Search term to filter documents by title\n    status_filter: Filter by document status\n    document_id: Filter by document id\n    created_from: Filter documents created on/after this datetime (inclusive)\n    created_to: Filter documents created on/before this datetime (inclusive); a date-only value (YYYY-MM-DD) covers the whole day\n    entity_group_id: Filter by the entity group (template) used in the document's latest extraction","operationId":"list_documents_documents__get","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1,"title":"Page"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":10,"title":"Limit"}},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search"}},{"name":"status_filter","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status Filter"}},{"name":"status_group","in":"query","required":false,"description":"Only the documents of one status bucket of GET /documents/stats: attention (failed), processing or completed.","schema":{"type":"string","enum":["attention","processing","completed"],"title":"Status Group"}},{"name":"include_total","in":"query","required":false,"description":"false skips counting the matching documents: pagination.total_count and total_pages are null and has_next comes from reading one row past the page. Cheaper on large accounts.","schema":{"type":"string","enum":["true","false"],"default":"true","title":"Include Total"}},{"name":"document_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Id"}},{"name":"created_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created From"}},{"name":"created_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created To"}},{"name":"entity_group_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Group Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Documents Documents  Get"},"example":{"documents":[{"title":"exemple.pdf","file_path":"documents/user-uuid/exemple.pdf","file_type":"application/pdf","file_size":245632,"status":"completed","page_count":3,"id":"your-document-id","created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T10:35:00Z","entity_group_id":"your-entity-group-id","entity_group_name":"Invoices","credits_estimate_low":null,"credits_estimate_high":null,"credits_charged":1.11}],"total":1,"page":1,"pages":1}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/documents/counts":{"get":{"tags":["Documents"],"summary":"Get Document Counts","description":"Get document and page statistics for the authenticated user.\n\nReturns document counts and page counts:\n- total_documents: Total count of all documents\n- documents_current_month: Count of documents uploaded in the current month\n- documents_current_day: Count of documents uploaded today\n- total_pages: Total page count across all documents\n- pages_current_month: Total pages for documents uploaded in the current month\n- pages_current_day: Total pages for documents uploaded today","operationId":"get_document_counts_documents_counts_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentCountResponse"},"example":{"total_documents":85,"documents_current_month":48,"documents_current_day":1,"total_pages":85,"pages_current_month":48,"pages_current_day":1}}}},"404":{"description":"Not found"}},"security":[{"OAuth2PasswordBearer":[]}]}},"/documents/stats":{"get":{"tags":["Documents"],"summary":"Get Document Stats","description":"Get optimized document statistics for dashboard cards.\n\nReturns a single request with all status counts:\n- total: Total count of all documents\n- completed: Count of completed/processed documents\n- processing: Count of processing/validating documents\n- failed: Count of failed documents","operationId":"get_document_stats_documents_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":{"type":"integer"},"type":"object","title":"Response Get Document Stats Documents Stats Get"},"example":{"total":85,"completed":62,"processing":1,"failed":22}}}},"404":{"description":"Not found"}},"security":[{"OAuth2PasswordBearer":[]}]}},"/documents/{document_id}":{"get":{"tags":["Documents"],"summary":"Get Document By Id Route","description":"Gets a specific document by ID.","operationId":"get_document_by_id_route_documents__document_id__get","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Document Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"},"example":{"title":"exemple.pdf","file_path":"r2://parser-documents/documents/your-user-id/example.pdf","file_type":"application/pdf","file_size":22581,"status":"completed","page_count":1,"id":"exemple-document-id","created_at":"2025-10-29T19:38:17.184145Z","updated_at":"2025-10-29T19:38:39.288059Z","user_id":"your-user-id"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["Documents"],"summary":"Update Document Route","description":"Updates document metadata (e.g., title, status).","operationId":"update_document_route_documents__document_id__put","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Document Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentUpdate"},"example":{"title":"new_title.pdf"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"},"example":{"title":"new_title.pdf","file_path":"r2://parser-documents/documents/your-user-id/new_title.pdf","file_type":"application/pdf","file_size":1024000,"status":"completed","page_count":5,"id":"your-document-id","created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T10:40:00Z","user_id":"your-user-id"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Documents"],"summary":"Delete Document Route","description":"Deletes a document and its associated file.","operationId":"delete_document_route_documents__document_id__delete","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Document Id"}}],"responses":{"204":{"description":"Successful Response"},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/documents/status/{document_id}":{"get":{"tags":["Documents"],"summary":"Get Document Status Route","description":"Gets the processing status of a specific document.","operationId":"get_document_status_route_documents_status__document_id__get","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Document Id"}}],"responses":{"200":{"description":"Document processing status","content":{"application/json":{"schema":{"type":"string","title":"Response Get Document Status Route Documents Status  Document Id  Get"},"example":"completed"}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/documents/{document_id}/reprocess":{"post":{"tags":["Documents"],"summary":"Reprocess Document Route","description":"Triggers reprocessing of a document without requiring a new upload.\n\nEligible statuses: 'failed', 'too large', 'limit reached', 'insufficient credits', 'completed'.\nThe document must belong to the authenticated user.\nA reprocess is a new run: it is judged like a new document — the monthly fair-use limit and the credit balance are checked BEFORE anything is reset, and a refused reprocess answers 403 with the reason and leaves the document and its results exactly as they were — and it is charged credits again when it succeeds (it adds no second usage count).\n\nOptional body (enterprise_byok only): pass ``gemini_model`` to override the model\nused for this reprocess run. Omit the body or omit the field to keep the model\nstored from the original upload. Sending ``null`` does not clear a stored override;\npass an explicit allowed model name (e.g. ``gemini-2.5-pro``) to use the default.","operationId":"reprocess_document_route_documents__document_id__reprocess_post","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Document Id"}}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ReprocessRequest"},{"type":"null"}],"title":"Request"},"example":{"gemini_model":"gemini-3.1-pro-preview"}}}},"responses":{"202":{"description":"Document accepted for reprocessing","content":{"application/json":{"schema":{},"example":{"message":"Document reprocessing started."}}}},"403":{"description":"A reprocess the account cannot take now: the monthly fair-use limit is reached, or the balance does not cover the document (the reason is in `detail`; nothing was reset); or Gemini model selection requires enterprise_byok subscription."},"404":{"description":"Document not found"},"409":{"description":"Document cannot be reprocessed: ineligible status or concurrent modification (safe to retry for concurrent cases)"},"422":{"description":"Document cannot be reprocessed (missing template or invalid path)"},"503":{"description":"Queue temporarily unavailable — safe to retry"}}}},"/documents/upload/generate-signed-url":{"post":{"tags":["Documents"],"summary":"Generate Signed Url For Upload Endpoint","description":"Generates a signed upload URL for a large file.\n\nThis endpoint creates the document records in the database first, then returns a short-lived worker-signed URL (PUT /uploads/{token}, valid for 30 minutes). PUT the raw file body to that URL to store the file and start extraction. Suitable for large files to avoid request timeouts.","operationId":"generate_signed_url_for_upload_endpoint_documents_upload_generate_signed_url_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignedUrlRequest"},"example":{"file_name":"exemple.pdf","entity_group_id":"your-entity-group-id"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignedUrlResponse"},"example":{"signed_url":"https://api.parserai.co/uploads/eyJkIjoi...token...","document_id":"your-document-id","extracted_document_id":"your-extracted-document-id","gcs_path":"r2://parser-documents/documents/user-uuid/example.pdf"}}}},"403":{"description":"Gemini model selection requires enterprise_byok subscription."},"404":{"description":"Not found"},"422":{"description":"Requested Gemini model is not in the allowed list."}},"security":[{"OAuth2PasswordBearer":[]}]}},"/documents/upload/generate-signed-url-template-creation":{"post":{"tags":["Documents"],"summary":"Generate Signed Url For Template Creation Endpoint","description":"Same as /documents/upload/generate-signed-url, but for the template-creation flow: completing the upload generates a template (entity group + entities) from the document before extracting it.","operationId":"generate_signed_url_for_template_creation_endpoint_documents_upload_generate_signed_url_template_creation_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateCreationSignedUrlRequest"},"example":{"file_name":"exemple.pdf"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateCreationSignedUrlResponse"},"example":{"signed_url":"https://api.parserai.co/uploads/eyJkIjoi...token...","document_id":"your-document-id","gcs_path":"r2://parser-documents/documents/user-uuid/example.pdf"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]}]}},"/documents/upload-template-creation":{"post":{"tags":["Documents"],"summary":"Upload Document For Template Creation Endpoint","description":"Direct upload endpoint for automatic template creation (useful for local testing).\n\nUpload a document without specifying an entity group.\nThe AI will analyze the document and automatically create a template with relevant entities,\nincluding generating the template name and description automatically.\nAfter template creation, the document will be processed using the newly created template.\n\n32MB file size limit.","operationId":"upload_document_for_template_creation_endpoint_documents_upload_template_creation_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_document_for_template_creation_endpoint_documents_upload_template_creation_post"}}},"required":true},"responses":{"202":{"description":"Document accepted for template creation","content":{"application/json":{"schema":{},"example":{"message":"Document uploaded successfully. Template creation scheduled.","documentId":"your-document-id"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]}]}},"/documents/upload":{"post":{"tags":["Documents"],"summary":"Upload Document Endpoint","description":"Synchronous upload endpoint with a 32MB file size limit.","operationId":"upload_document_endpoint_documents_upload_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_document_endpoint_documents_upload_post"}}},"required":true},"responses":{"202":{"description":"Document accepted for processing","content":{"application/json":{"schema":{},"example":{"message":"Document accepted for processing.","documentId":"your-document-id","extractedDocumentId":"your-extracted-document-id","entityGroupId":"your-entity-group-id"}}}},"403":{"description":"Gemini model selection requires enterprise_byok subscription."},"404":{"description":"Not found"},"422":{"description":"Requested Gemini model is not in the allowed list."}},"security":[{"OAuth2PasswordBearer":[]}]}},"/documents/upload/rate-limit-status":{"get":{"tags":["Documents"],"summary":"Get Upload Rate Limit Status","description":"Get current rate limit status for uploads for the authenticated user.\n\nReturns information about current usage and remaining quota.","operationId":"get_upload_rate_limit_status_documents_upload_rate_limit_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{},"example":{"user_id":"your-user-id","rate_limit":{"limit":100,"remaining":100,"window_seconds":60},"message":"You can make 100 more upload requests in the next 60 seconds"}}}},"404":{"description":"Not found"}},"security":[{"OAuth2PasswordBearer":[]}]}},"/entities/":{"get":{"tags":["Entities"],"summary":"List Entities","description":"Retrieve all entities for the current user.","operationId":"list_entities_entities__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/Entity"},"type":"array","title":"Response List Entities Entities  Get"},"example":[{"id":"your-entity-id","created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T10:30:00Z","name":"Exemple Entity","description":"Your description here","prompt":"Your prompt here","user_id":"your-user-id"}]}}}},"security":[{"OAuth2PasswordBearer":[]}]},"post":{"tags":["Entities"],"summary":"Create Entity","description":"Create a new entity.","operationId":"create_entity_entities__post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityCreate"},"example":{"name":"Exemple Entity","description":"Your description here","prompt":"Your prompt here"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entity"},"example":{"id":"your-entity-id","created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T10:30:00Z","name":"Exemple Entity","description":"Your description here","prompt":"Your prompt here","user_id":"your-user-id"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]}]}},"/entities/grouping-stats":{"get":{"tags":["Entities"],"summary":"Get Entity Grouping Stats","description":"Get statistics about entity grouping to optimize frontend loading.","operationId":"get_entity_grouping_stats_entities_grouping_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Get Entity Grouping Stats Entities Grouping Stats Get"},"example":{"total_entities":8,"grouped_entities":8,"ungrouped_entities":0,"has_ungrouped":false}}}}},"security":[{"OAuth2PasswordBearer":[]}]}},"/entities/with-grouping":{"get":{"tags":["Entities"],"summary":"Get Entities With Grouping","description":"Get entities with their grouping information in a single optimized request.","operationId":"get_entities_with_grouping_entities_with_grouping_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Get Entities With Grouping Entities With Grouping Get"},"example":{"entities":[{"id":"your-entity-id-1","name":"Data","description":"","created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T10:30:00Z","user_id":"your-user-id","prompt":"Extract date from transaction"}],"groups":[{"id":"your-group-id-1","name":"bank_transactions","user_id":"your-user-id","created_at":"2024-01-15T10:00:00Z","updated_at":"2024-01-15T10:00:00Z"}],"group_to_entities":{"your-group-id-1":[{"id":"your-entity-id-1","name":"Data","description":"","created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T10:30:00Z","user_id":"your-user-id","prompt":"Extract date from transaction"}]},"ungrouped_entities":[],"entity_to_group":{"your-entity-id-1":"your-group-id-1"}}}}}},"security":[{"OAuth2PasswordBearer":[]}]}},"/entities/{entity_id}":{"get":{"tags":["Entities"],"summary":"Get Entity","description":"Retrieve a specific entity by ID.","operationId":"get_entity_entities__entity_id__get","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"entity_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Entity Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entity"},"example":{"id":"your-entity-id","created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T10:30:00Z","name":"Exemple Entity","description":"Your description here","prompt":"Your prompt here","user_id":"your-user-id"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["Entities"],"summary":"Update Entity","description":"Update an existing entity.","operationId":"update_entity_entities__entity_id__put","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"entity_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Entity Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityUpdate"},"example":{"name":"Updated Entity Name","description":"Updated description","prompt":"Updated prompt"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entity"},"example":{"id":"your-entity-id","created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T11:30:00Z","name":"Updated Entity Name","description":"Updated description","prompt":"Updated prompt","user_id":"your-user-id"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Entities"],"summary":"Delete Entity","description":"Delete an entity.","operationId":"delete_entity_entities__entity_id__delete","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"entity_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Entity Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/entity-groups/":{"get":{"tags":["Entity Groups"],"summary":"List Entity Groups","description":"Retrieve all entity groups for the current user.","operationId":"list_entity_groups_entity_groups__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/EntityGroup"},"type":"array","title":"Response List Entity Groups Entity Groups  Get"},"example":[{"id":"your-entity-group-id-1","created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T10:30:00Z","name":"Exemple Entity Group","description":"Your description here","user_id":"your-user-id"},{"id":"your-entity-group-id-2","created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T10:30:00Z","name":"Exemple Entity Group","description":"Your description here","user_id":"your-user-id","webhook_id":"your-webhook-id"}]}}}},"security":[{"OAuth2PasswordBearer":[]}]},"post":{"tags":["Entity Groups"],"summary":"Create Entity Group","description":"Create a new entity group.","operationId":"create_entity_group_entity_groups__post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityGroupCreate"},"example":{"name":"Exemple Entity Group","description":"Your description here"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityGroup"},"example":{"id":"your-entity-group-id","created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T10:30:00Z","name":"Financial Documents","description":"Group for financial document entities","user_id":"your-user-id"}}}},"403":{"description":"The plan's template limit is reached (\"Your Free plan includes up to N templates. Upgrade to add more.\")","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]}]}},"/entity-groups/with-entities":{"post":{"tags":["Entity Groups"],"summary":"Create With Entities","description":"Create entity group with entities. All entities are automatically linked to the group.","operationId":"create_with_entities_entity_groups_with_entities_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityGroupWithEntitiesCreate"},"example":{"name":"Financial Documents","description":"Group for financial entities","entities":[{"name":"Invoice Number","description":"Extract invoice number","prompt":"Extract the invoice number"},{"name":"Total Amount","description":"Extract total","prompt":"Extract the total amount"}]}}},"required":true},"responses":{"201":{"description":"Entity group created with all entities linked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityGroupWithEntities"},"example":{"id":"group-uuid","created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T10:30:00Z","name":"Financial Documents","description":"Group for financial entities","user_id":"user-uuid","entities":[{"id":"entity-uuid-1","created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T10:30:00Z","name":"Invoice Number","description":"Extract invoice number","prompt":"Extract the invoice number","user_id":"user-uuid"}]}}}},"403":{"description":"The plan's template limit is reached (\"Your Free plan includes up to N templates. Upgrade to add more.\")","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]}]}},"/entity-groups/{group_id}":{"get":{"tags":["Entity Groups"],"summary":"Get Entity Group","description":"Retrieve a specific entity group by ID.","operationId":"get_entity_group_entity_groups__group_id__get","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"group_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Group Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityGroup"},"example":{"id":"your-entity-group-id","created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T10:30:00Z","name":"Exemple Entity Group","description":"Your description here","user_id":"your-user-id"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["Entity Groups"],"summary":"Update Entity Group","description":"Update an existing entity group.","operationId":"update_entity_group_entity_groups__group_id__put","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"group_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Group Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityGroupUpdate"},"example":{"name":"Updated Group Name","description":"Updated description","webhook_id":"your-webhook-id"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityGroup"},"example":{"id":"your-entity-group-id","name":"Updated Group Name","description":"Updated description","user_id":"your-user-id","webhook_id":"your-webhook-id","created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T11:30:00Z"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Entity Groups"],"summary":"Delete Entity Group","description":"Delete an entity group.\n\nBy default, also deletes all entities belonging to this group.\nSet delete_entities=false to keep the entities (they will become ungrouped).","operationId":"delete_entity_group_entity_groups__group_id__delete","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"group_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Group Id"}},{"name":"delete_entities","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Delete Entities"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/entity-groups/{group_id}/entities/{entity_id}":{"post":{"tags":["Entity Groups"],"summary":"Add Entity To Group","description":"Add an entity to an entity group.","operationId":"add_entity_to_group_entity_groups__group_id__entities__entity_id__post","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"group_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Group Id"}},{"name":"entity_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Entity Id"}}],"responses":{"201":{"description":"Entity added to group successfully","content":{"application/json":{"schema":{},"example":{"message":"Entity added to group successfully"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Entity Groups"],"summary":"Remove Entity From Group","description":"Remove an entity from an entity group.","operationId":"remove_entity_from_group_entity_groups__group_id__entities__entity_id__delete","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"group_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Group Id"}},{"name":"entity_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Entity Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/entity-groups/{group_id}/entities":{"get":{"tags":["Entity Groups"],"summary":"List Entities In Group","description":"List all entities within a specific entity group.","operationId":"list_entities_in_group_entity_groups__group_id__entities_get","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"group_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Group Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Entity"},"title":"Response List Entities In Group Entity Groups  Group Id  Entities Get"},"example":[{"id":"your-entity-id","created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T10:30:00Z","name":"Exemple Entity","description":"Your description here","prompt":"Your prompt here","user_id":"your-user-id"}]}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/extracted-documents/":{"post":{"tags":["Extracted Documents"],"summary":"Create Extracted Document Route","description":"Create a new extracted document record.","operationId":"create_extracted_document_route_extracted_documents__post","security":[{"OAuth2PasswordBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractedDocumentCreate"},"example":{"document_id":"your-document-id","entity_group_id":"your-entity-group-id","extracted_data":[],"extraction_status":"pending"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractedDocument"},"example":{"id":"your-extracted-document-id","document_id":"your-document-id","entity_group_id":"your-entity-group-id","extracted_data":[],"extraction_status":"pending","created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T10:30:00Z"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["Extracted Documents"],"summary":"List Extracted Documents Route","description":"List extracted documents for the current user with optional filters.","operationId":"list_extracted_documents_route_extracted_documents__get","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"skip","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Skip"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":10,"title":"Limit"}},{"name":"document_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Filter by original document ID","title":"Document Id"},"description":"Filter by original document ID"},{"name":"document_ids","in":"query","required":false,"schema":{"type":"string","description":"1 to 100 comma-separated document UUIDs: the rows of those documents only","title":"Document Ids"},"description":"1 to 100 comma-separated document UUIDs: the rows of those documents only"},{"name":"entity_group_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Filter by entity group ID","title":"Entity Group Id"},"description":"Filter by entity group ID"},{"name":"extraction_status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by extraction status (e.g., pending, completed, error)","title":"Extraction Status"},"description":"Filter by extraction status (e.g., pending, completed, error)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ExtractedDocument"},"title":"Response List Extracted Documents Route Extracted Documents  Get"},"example":[{"id":"your-extracted-document-id","document_id":"your-document-id","entity_group_id":"your-entity-group-id","extracted_data":[{"field1":"value1","field2":"value2"}],"extraction_status":"success","model_version":"parser-ai-5.0","total_token_count":2000,"prompt_token_count":600,"thoughts_token_count":1200,"candidates_token_count":200,"created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T10:35:00Z"}]}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/extracted-documents/by-template/{entity_group_id}":{"get":{"tags":["Extracted Documents"],"summary":"List Extractions By Template Route","description":"List all extractions for a specific template (entity group) with document metadata.\n\nThis endpoint is designed for the Results page to display extractions in a \nspreadsheet-like format with pagination support for large datasets.","operationId":"list_extractions_by_template_route_extracted_documents_by_template__entity_group_id__get","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"entity_group_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Entity Group Id"}},{"name":"skip","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of records to skip","default":0,"title":"Skip"},"description":"Number of records to skip"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Maximum number of records to return","default":100,"title":"Limit"},"description":"Maximum number of records to return"},{"name":"extraction_status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by extraction status (e.g., success, error, pending)","title":"Extraction Status"},"description":"Filter by extraction status (e.g., success, error, pending)"}],"responses":{"200":{"description":"Successful Response - Returns extractions for the specified template with pagination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractionsByTemplateResponse"},"example":{"data":[{"id":"extraction-uuid","document_id":"document-uuid","entity_group_id":"template-uuid","extracted_data":[{"field1":"value1","field2":"value2"}],"extraction_status":"success","model_version":"parser-ai-5.0","total_token_count":1500,"prompt_token_count":500,"thoughts_token_count":800,"candidates_token_count":200,"created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T10:35:00Z","document_title":"Invoice_001.pdf","document_file_type":"application/pdf","document_created_at":"2024-01-15T10:00:00Z"}],"total_count":50,"skip":0,"limit":100,"has_more":false}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/extracted-documents/{extracted_document_id}":{"get":{"tags":["Extracted Documents"],"summary":"Get Extracted Document Route","description":"Get a specific extracted document by its ID.","operationId":"get_extracted_document_route_extracted_documents__extracted_document_id__get","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"extracted_document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Extracted Document Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractedDocument"},"example":{"document_id":"your-document-id","entity_group_id":"your-entity-group-id","extracted_data":[{"field1":"value1","field2":"value2"}],"extraction_status":"success","model_version":"parser-ai-5.0","total_token_count":900,"prompt_token_count":600,"thoughts_token_count":50,"candidates_token_count":250,"id":"your-extracted-document-id","created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T10:35:00Z"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["Extracted Documents"],"summary":"Update Extracted Document Route","description":"Update an extracted document (e.g., status or corrected data).","operationId":"update_extracted_document_route_extracted_documents__extracted_document_id__put","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"extracted_document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Extracted Document Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractedDocumentUpdate"},"example":{"extracted_data":[{"field1":"value1","field2":"value2"}],"extraction_status":"success"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractedDocument"},"example":{"document_id":"your-document-id","entity_group_id":"your-entity-group-id","extracted_data":[{"field1":"value1","field2":"value2"}],"extraction_status":"success","model_version":"parser-ai-5.0","total_token_count":900,"prompt_token_count":600,"thoughts_token_count":50,"candidates_token_count":250,"id":"your-id","created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T10:40:00Z"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Extracted Documents"],"summary":"Delete Extracted Document Route","description":"Delete a specific extracted document.","operationId":"delete_extracted_document_route_extracted_documents__extracted_document_id__delete","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"extracted_document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Extracted Document Id"}}],"responses":{"204":{"description":"Successful Response"},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/profiles/me":{"get":{"tags":["Profiles"],"summary":"Get My Profile","description":"Get the current user's profile with only essential fields.","operationId":"get_my_profile_profiles_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileMe"},"example":{"id":"your-user-id","role":"user","subscription_plan":"pro","has_api_key_configured":false,"onboarding_tutorial":true}}}}},"security":[{"OAuth2PasswordBearer":[]}]}},"/profiles/update-api-key":{"patch":{"tags":["Profiles"],"summary":"Update Api Key","description":"Update the current user's API key.","operationId":"update_api_key_profiles_update_api_key_patch","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeminiAPIKeyUpdate"},"example":{"gemini_api_key":"your-gemini-api-key"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Profile"},"example":{"id":"your-user-id","role":"user","has_enabled_mfa":false,"gemini_api_key":"****","subscription_plan":"enterprise_byok","stripe_customer_id":"cus_xxxxx","initial_credits_granted":true,"enrolled_factors":{},"created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T11:30:00Z"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]}]}},"/profiles/update-llm-defaults":{"patch":{"tags":["Profiles"],"summary":"Update Llm Defaults","description":"Set the caller's default LLM as a model ref — canonical 'provider/model' (e.g. 'gemini/gemini-2.5-pro') or a bare catalog model. PATCH semantics: omitted = keep, null = clear back to the platform default. enterprise_byok only.","operationId":"update_llm_defaults_profiles_update_llm_defaults_patch","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LlmDefaultsUpdate"},"example":{"default_model":"gemini/gemini-2.5-pro"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Profile"},"example":{"id":"your-user-id","role":"user","has_enabled_mfa":false,"gemini_api_key":"****","subscription_plan":"enterprise_byok","stripe_customer_id":"cus_xxxxx","initial_credits_granted":true,"enrolled_factors":{},"default_llm_model":"gemini/gemini-2.5-pro","created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T11:30:00Z"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]}]}},"/profiles/complete-onboarding":{"patch":{"tags":["Profiles"],"summary":"Complete Onboarding","description":"Mark the onboarding tutorial as completed for the current user.","operationId":"complete_onboarding_profiles_complete_onboarding_patch","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnboardingTutorialUpdate"},"example":{"onboarding_tutorial":true}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileMe"},"example":{"id":"your-user-id","role":"user","subscription_plan":"pro","has_api_key_configured":false,"onboarding_tutorial":true}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]}]}},"/webhooks/":{"post":{"tags":["Webhooks"],"summary":"Create Webhook","description":"Create a new webhook for the authenticated user.","operationId":"create_webhook_webhooks__post","security":[{"OAuth2PasswordBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreate"},"example":{"name":"Document Processing Webhook","url":"https://your-domain.com/webhook","events":["document.completed","document.failed"],"is_active":true,"headers":{"X-Custom-Header":"your-value"}}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookInDB"},"example":{"id":"your-webhook-id","name":"Document Processing Webhook","url":"https://your-domain.com/webhook","events":["document.completed","document.failed"],"is_active":true,"headers":{"X-Custom-Header":"your-value"},"user_id":"your-user-id","created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T10:30:00Z"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["Webhooks"],"summary":"List Webhooks","description":"List all webhooks for the authenticated user.","operationId":"list_webhooks_webhooks__get","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"skip","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Skip"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WebhookInDB"},"title":"Response List Webhooks Webhooks  Get"},"example":[{"id":"your-webhook-id","name":"Document Processing Webhook","url":"https://your-domain.com/webhook","events":["document.completed","document.failed"],"is_active":true,"headers":{"X-Custom-Header":"your-value"},"user_id":"your-user-id","created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T10:30:00Z"}]}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/webhooks/logs":{"get":{"tags":["Webhooks"],"summary":"List Webhook Logs","description":"Returns paginated logs for a webhook owned by the authenticated user.\n\n- **webhook_id** (required): the webhook whose logs you want to query.\n- **document_id** (optional): filter logs by a specific document.\n- **extracted_document_id** (optional): filter logs by a specific extraction.","operationId":"list_webhook_logs_webhooks_logs_get","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"webhook_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"Webhook Id"}},{"name":"document_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Document Id"}},{"name":"extracted_document_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Extracted Document Id"}},{"name":"skip","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Skip"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}}],"responses":{"200":{"description":"Paginated list of webhook call logs","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WebhookLogInDB"},"title":"Response List Webhook Logs Webhooks Logs Get"}}}},"404":{"description":"Webhook not found or access denied"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/webhooks/{webhook_id}":{"get":{"tags":["Webhooks"],"summary":"Get Webhook","description":"Get a specific webhook by ID, ensuring it belongs to the authenticated user.","operationId":"get_webhook_webhooks__webhook_id__get","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Webhook Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookInDB"},"example":{"id":"9754c929-71a9-4532-9c18-08446b1eca82","name":"Document Processing Webhook","url":"https://webhook.site/915c7ce2-4cc1-4dcb-9053-bc21c0501a74","events":["document.completed","document.failed"],"is_active":true,"headers":{"X-Custom-Header":"your-value"},"user_id":"a392c975-036d-4619-815b-cbc7e6ea595f","created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T10:30:00Z"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["Webhooks"],"summary":"Update Webhook","description":"Update a webhook by ID, ensuring it belongs to the authenticated user.","operationId":"update_webhook_webhooks__webhook_id__put","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Webhook Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookUpdate"},"example":{"name":"Updated Webhook Name","url":"https://your-domain.com/webhook-updated","events":["document.completed"],"is_active":true,"headers":{"X-Custom-Header":"updated-value"}}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookInDB"},"example":{"id":"your-webhook-id","name":"Updated Webhook Name","url":"https://your-domain.com/webhook-updated","events":["document.completed"],"is_active":true,"headers":{"X-Custom-Header":"updated-value"},"user_id":"your-user-id","created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-15T11:30:00Z"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Webhooks"],"summary":"Delete Webhook","description":"Delete a webhook by ID, ensuring it belongs to the authenticated user.","operationId":"delete_webhook_webhooks__webhook_id__delete","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Webhook Id"}}],"responses":{"204":{"description":"Successful Response"},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/stripe/credits/buy":{"post":{"tags":["Stripe"],"summary":"Buy Credits","description":"Start a one-time Stripe Checkout (payment mode) for a credit pack and redirect the user to `url`. Send only `pack_usd`, one of the packs the account's plan can buy (`credits.topup.packs` of `GET /plan/usage`, `credit_packs_usd` of `GET /plan/catalog`): the credits it buys depend on the account's plan at this moment and are worked out server-side (the better the plan, the more credits per dollar). The credits are added to the purchased balance only once Stripe confirms the payment through the webhook, never by the redirect back; a full refund takes them back. 400 when `pack_usd` is not an offered pack; 403 for enterprise (contract) accounts, which have no credits, and while an admin impersonates the user; 502 when Stripe is unavailable.","operationId":"buy_credits_stripe_credits_buy_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditPackCheckoutRequest"},"example":{"pack_usd":25}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditPackCheckoutResponse"},"example":{"url":"https://checkout.stripe.com/c/pay/cs_test_xxxxx"}}}},"400":{"description":"`pack_usd` is not one of the offered packs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Enterprise (contract) account, or an admin impersonating the user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"502":{"description":"Stripe is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"OAuth2PasswordBearer":[]}]}},"/stripe/webhooks":{"post":{"tags":["Stripe"],"summary":"Stripe Webhook","description":"Stripe webhook receiver (signature-verified; no bearer token). Handles `customer.subscription.created|updated|deleted` (syncs the account's plan from the subscription), `checkout.session.completed` and `checkout.session.async_payment_succeeded` (a paid credit pack, `metadata.type=credits_pack`, adds its credits to the purchased balance once per payment, so a redelivery or the two events of one payment book once; a checkout of the old pay-as-you-go product paid after the switch converts at USD 0.10 per credit once; a subscription session only links the Stripe customer), and `charge.refunded` (a full refund of a credit pack takes its credits back once; a partial refund changes no balance and is logged for review). Everything else is ignored with 200. Never answers 5xx for an event it cannot place (unknown customer, price or pack) so Stripe does not retry it forever; a failing database write does answer 5xx, and the idempotent booking converges on the retry.","operationId":"stripe_webhook_stripe_webhooks_post","requestBody":{"content":{"application/json":{"schema":{"type":"object","description":"Stripe webhook event payload"},"example":{"id":"evt_your_event_id","type":"customer.subscription.updated","created":1790000000,"data":{"object":{"id":"sub_your_subscription_id","customer":"cus_your_customer_id","status":"active","cancel_at_period_end":false,"billing_cycle_anchor":1790000000,"metadata":{"user_id":"00000000-0000-4000-8000-000000000000"},"items":{"data":[{"current_period_end":1792592000,"price":{"lookup_key":"starter_monthly"}}]}}}}}},"required":true},"responses":{"200":{"description":"Successful Response. `{status: \"ignored\"}` when the event is not one this endpoint acts on or cannot be placed (unknown customer or price).","content":{"application/json":{"schema":{},"example":{"status":"success","processed":true}}}}}}},"/health":{"get":{"tags":["Health"],"summary":"Health Check","description":"Check if the API is running.","operationId":"health_check_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{},"example":{"status":"healthy"}}}}}}},"/uploads/{token}":{"put":{"tags":["Documents"],"summary":"Upload File To Signed Url","description":"PUT target of the URLs returned by the generate-signed-url endpoints. No Authorization header — the HMAC token in the path is the credential (expires 30 minutes after issuance). Send the raw file bytes as the request body with a Content-Type header. Completing the upload stores the file and enqueues extraction (or template creation).","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","title":"Token"},"description":"Signed upload token issued by generate-signed-url."}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"File stored; extraction enqueued. Empty body."},"403":{"description":"Invalid or expired upload URL"}}}},"/auth/change-password":{"post":{"tags":["Auth"],"summary":"Change Password","description":"Change the authenticated user's password. Requires the current password.","operationId":"change_password_auth_change_password_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangePasswordRequest"},"example":{"current_password":"old_password","new_password":"new_secure_password_123"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{},"example":{"message":"Password updated successfully."}}}},"400":{"description":"Wrong current password or new password too short"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]}]}},"/admin/users":{"get":{"tags":["Admin"],"summary":"List Users","description":"List users (admin only). Optional case-insensitive search (q) over email/full_name/user id, optional role/plan filters (ANDed with q), server-side sorting via sort/dir, paginated with limit/offset. Each row carries the stored plan (`subscription_plan`), the plan in force (`effective_plan`), `plan_status`, `plan_expires_at`, `stripe_managed` and this period's usage (`documents_this_period`, `pages_this_period`). Each row carries `credits`: the balance right now as `{plan, purchased, held, available}` in credits, or null for an Enterprise account (own API key, no credits).","operationId":"list_users_admin_users_get","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"}},{"name":"role","in":"query","required":false,"schema":{"type":"string","enum":["user","admin"]}},{"name":"plan","in":"query","required":false,"description":"`none` matches accounts with no subscription plan.","schema":{"type":"string","enum":["free","starter","pro","enterprise_byok","none"]}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","default":"created","enum":["created","last_login","name","email","role","plan","documents"]}},{"name":"dir","in":"query","required":false,"schema":{"type":"string","default":"desc","enum":["asc","desc"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"OAuth2PasswordBearer":[]}]},"post":{"tags":["Admin"],"summary":"Create User","description":"Create a new user account (admin only): an auth_users row (bcrypt password) + a profiles row. The account is Free unless `subscription_plan` is given; `starter`/`pro` is a comp grant, optionally until `plan_expires_at` (ISO date or date-time; omitted/null = no expiry). No Stripe customer is created until the user first subscribes.","operationId":"create_user_admin_users_post","requestBody":{"required":true,"content":{"application/json":{"schema":{},"example":{"email":"new.user@example.com","password":"changeme123","full_name":"New User","role":"user","subscription_plan":"starter","plan_expires_at":"2026-12-31"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"OAuth2PasswordBearer":[]}]}},"/admin/users/{user_id}":{"get":{"tags":["Admin"],"summary":"Get User","description":"Fetch a single user with profile, plan (stored and in force), current-period usage, credit balance (`credits`, null for an Enterprise account) and document count (admin only).","operationId":"get_user_admin_users__user_id__get","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"OAuth2PasswordBearer":[]}]},"delete":{"tags":["Admin"],"summary":"Delete User","description":"IRREVERSIBLE (admin only): erases the user and every trace of them — all D1 rows (documents, extracted documents, templates, entities, mappings, webhooks, webhook logs, credits and their ledger, BYOK keys, profile, account) plus every stored file in R2. Requires `confirm_email` to match the target's e-mail. An admin cannot delete their own account, and the last remaining admin cannot be deleted. An account with a live Stripe subscription is refused with 409: cancel it in Stripe first. Returns the per-table deleted row counts. Note: the Stripe customer and its payment history are NOT touched.","operationId":"delete_user_admin_users__user_id__delete","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{},"example":{"confirm_email":"user.to.delete@example.com"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{},"example":{"message":"User and all associated data deleted.","user_id":"00000000-0000-4000-8000-000000000000","email":"user.to.delete@example.com","deleted":{"extracted_documents":12,"webhook_logs":3,"entity_group_mapping":4,"documents":12,"webhooks":1,"entities_group":2,"entities":4,"user_credits":5,"credit_ledger":3,"credit_accounts":1,"credit_holds":0,"llm_provider_keys":0,"profiles":1,"auth_users":1},"files":{"r2":12,"failed":0}}}}}},"security":[{"OAuth2PasswordBearer":[]}]},"patch":{"tags":["Admin"],"summary":"Update User","description":"Edit a user's full_name, role, subscription_plan and plan expiry (admin only). PATCH semantics: omitted fields are kept. Setting `starter`/`pro` is a comp grant, optionally until `plan_expires_at`; `free`/`enterprise_byok` clear the paid state. 409 when the account has an active Stripe subscription (change or cancel it in Stripe). An admin cannot remove their own admin role.","operationId":"update_user_admin_users__user_id__patch","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{},"example":{"full_name":"Jane Doe","role":"admin","subscription_plan":"pro","plan_expires_at":"2026-12-31T23:59:59Z"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"OAuth2PasswordBearer":[]}]}},"/admin/users/{user_id}/impersonate":{"post":{"tags":["Admin"],"summary":"Impersonate User","description":"Mint a session token for another account (admin only). The token is a full session for the target — same permissions and same writes, including irreversible ones — and carries the acting admin's id so api.request and the admin.* audit events name the operator. Ordinary 1h TTL, no refresh. 422 when the target is the caller.","operationId":"impersonate_user_admin_users__user_id__impersonate_post","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"OAuth2PasswordBearer":[]}]}},"/admin/users/{user_id}/credits":{"post":{"tags":["Admin"],"summary":"Grant Credits","description":"Give an account credits (admin only): support goodwill, a manual top-up, a settled dispute. They go to the purchased balance (spent after the plan credits, never expire) as an admin grant in the ledger carrying the acting admin and the optional `note`, and are audited. Every call adds credits: a repeated request is a second gift. Returns the account's new balance. 404 for an unknown user; 409 for an Enterprise account (own API key, no credits); 422 for `credits` <= 0 or above 1,000,000.","operationId":"grant_credits_admin_users__user_id__credits_post","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminCreditsGrantRequest"},"example":{"credits":50,"note":"Goodwill: extraction failed twice"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminCreditsGrantResponse"},"example":{"user_id":"00000000-0000-4000-8000-000000000000","granted":50,"balance":{"plan":10,"purchased":50,"held":0,"available":60}}}}},"403":{"description":"Admin privileges required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"User not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The account is on an Enterprise contract and has no credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]}]}},"/admin/users/{user_id}/reset-password":{"post":{"tags":["Admin"],"summary":"Reset User Password","description":"Directly set a user's password (admin only), no e-mail round-trip. Minimum 6 characters.","operationId":"reset_user_password_admin_users__user_id__reset_password_post","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{},"example":{"new_password":"changeme123"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"OAuth2PasswordBearer":[]}]}},"/profiles/update-profile":{"patch":{"tags":["Profiles"],"summary":"Update Profile","description":"Update the current user's profile fields (full_name). PATCH semantics: omitted = keep, null = clear.","operationId":"update_profile_profiles_update_profile_patch","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileUpdate"},"example":{"full_name":"Jane Doe"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileMe"},"example":{"id":"your-user-id","full_name":"Jane Doe","role":"user","subscription_plan":"pro","has_api_key_configured":false,"onboarding_tutorial":false,"default_llm_model":null,"deletion_requested_at":null}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]}]}},"/profiles/request-deletion":{"post":{"tags":["Profiles"],"summary":"Request Account Deletion","description":"Record an account-deletion request and notify the team. Idempotent — a second call keeps the original timestamp. Body is optional.","operationId":"request_deletion_profiles_request_deletion_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountDeletionRequest"},"example":{"reason":"No longer needed"}}},"required":false},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileMe"},"example":{"id":"your-user-id","full_name":"Jane Doe","role":"user","subscription_plan":"pro","has_api_key_configured":false,"onboarding_tutorial":false,"default_llm_model":null,"deletion_requested_at":"2026-07-23T12:00:00.000Z"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]}]}},"/profiles/cancel-deletion":{"post":{"tags":["Profiles"],"summary":"Cancel Account Deletion Request","description":"Clear a pending account-deletion request.","operationId":"cancel_deletion_profiles_cancel_deletion_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileMe"},"example":{"id":"your-user-id","full_name":"Jane Doe","role":"user","subscription_plan":"pro","has_api_key_configured":false,"onboarding_tutorial":false,"default_llm_model":null,"deletion_requested_at":null}}}}},"security":[{"OAuth2PasswordBearer":[]}]}},"/plan/summary":{"get":{"tags":["Plan"],"summary":"Get Plan Summary","description":"The plan that applies now and the credit balance: exactly the `entitlement` and `credits` blocks of `GET /plan/usage`, without its document volume, 12-month history and storage numbers (which read every document of the account). Use this to show the plan and the balance; `GET /plan/usage` for the monthly usage report. Reading `credits` opens the plan's monthly window: the first read of a window grants its plan credits.","operationId":"get_plan_summary_plan_summary_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanSummary"}}}}},"security":[{"OAuth2PasswordBearer":[]}]}},"/plan/usage":{"get":{"tags":["Plan"],"summary":"Get Plan Usage","description":"Usage of a billing month (documents, pages, stored bytes, 12-month history) plus, for accounts on the enterprise contract, the contracted service levels and where the month sits against them. Defaults to the month in progress; `month=YYYY-MM` reports a closed month instead — that month's volume with the end-of-month storage snapshot, which is the view a period is checked against its invoice with and does not move when files are freed later. No monetary values are returned for the contract: enterprise fees are negotiated per contract. `entitlement` is the plan that applies now — its limits and what the current monthly window has used — and `credits` is the credit balance now (null on the enterprise contract: its own API key, no credits), whatever month is asked for. Reading `credits` opens the plan's monthly window: the first read of a window grants its plan credits.","operationId":"get_plan_usage_plan_usage_get","parameters":[{"name":"month","in":"query","required":false,"description":"Report this calendar month (YYYY-MM, UTC) instead of the one in progress. Must be one of the 12 months the response's own history covers — anything else is a 422, never a silent fall back to the current month.","schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$","title":"Month"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanUsage"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]}]}},"/plan/storage/purge":{"post":{"tags":["Plan"],"summary":"Purge Stored Files","description":"Delete the stored files of the caller's documents older than `older_than_days`, keeping the document rows and their extracted data. Irreversible. One call processes one bounded batch — repeat while `remaining` is above 0.","operationId":"purge_stored_files_plan_storage_purge_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoragePurgeRequest"},"example":{"older_than_days":7}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoragePurgeResponse"},"example":{"purged":1000,"freed_bytes":41203948123,"failed":0,"remaining":3412,"cutoff":"2026-07-30T12:00:00.000+00:00"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]}]}},"/plan/catalog":{"get":{"tags":["Plan"],"summary":"Get Plan Catalog","description":"The self-serve plans (Free, Starter, Pro) with their monthly and annual list prices in USD, their limits and what they give in credits: the credits granted every month, the bonus a top-up earns on that plan and the price of one credit on that plan. `credit_packs_usd` are the top-up pack sizes every plan can buy (`POST /stripe/credits/buy`). null = unlimited. Enterprise is a contract plan (own API key, no credits) and is not listed.","operationId":"get_plan_catalog_plan_catalog_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanCatalog"},"example":{"plans":[{"key":"free","name":"Free","price_monthly_usd":0,"price_annual_usd":0,"limits":{"documents_per_month":null,"max_pages_per_document":10,"pages_per_month":null,"parallel_documents":1,"templates":3},"credits_per_month":10,"topup_bonus_percent":0,"price_per_credit_usd":0.1},{"key":"starter","name":"Starter","price_monthly_usd":9.9,"price_annual_usd":95,"limits":{"documents_per_month":null,"max_pages_per_document":100,"pages_per_month":null,"parallel_documents":3,"templates":25},"credits_per_month":125,"topup_bonus_percent":25,"price_per_credit_usd":0.08},{"key":"pro","name":"Pro","price_monthly_usd":100,"price_annual_usd":960,"limits":{"documents_per_month":null,"max_pages_per_document":1000,"pages_per_month":null,"parallel_documents":10,"templates":null},"credits_per_month":1500,"topup_bonus_percent":50,"price_per_credit_usd":0.0667}],"credit_packs_usd":[10,25,50,100]}}}}},"security":[{"OAuth2PasswordBearer":[]}]}},"/stripe/checkout":{"post":{"tags":["Stripe"],"summary":"Create Subscription Checkout","description":"Start a Stripe Checkout (subscription mode) for the caller to subscribe to a paid plan; redirect the user to `checkout_url`. The plan only changes once Stripe confirms the payment through the webhook. 403 for enterprise (contract) accounts and while an admin impersonates the user; 409 when the account already has an active subscription, including one whose webhook has not landed yet (change or cancel it through the billing portal); any Checkout page the account left open is expired, so only the newest can be paid; 502 when Stripe is unavailable.","operationId":"create_subscription_checkout_stripe_checkout_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionCheckoutRequest"},"example":{"plan":"starter","interval":"month"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionCheckoutResponse"},"example":{"checkout_url":"https://checkout.stripe.com/c/pay/cs_test_xxxxx","session_id":"cs_test_xxxxx"}}}},"403":{"description":"Enterprise (contract) account, or an admin impersonating the user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The account already has an active subscription","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"502":{"description":"Stripe is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"OAuth2PasswordBearer":[]}]}},"/stripe/portal":{"post":{"tags":["Stripe"],"summary":"Create Billing Portal Session","description":"Open the Stripe Billing Portal for the caller's own Stripe customer (change plan, payment method, cancel, invoices); redirect the user to `portal_url`. 403 for enterprise (contract) accounts and while an admin impersonates the user; 409 when the account has no billing account yet (it never started a checkout); 502 when Stripe is unavailable.","operationId":"create_billing_portal_stripe_portal_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingPortalResponse"},"example":{"portal_url":"https://billing.stripe.com/p/session/xxxxx"}}}},"403":{"description":"Enterprise (contract) account, or an admin impersonating the user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"No billing account yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Stripe is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"OAuth2PasswordBearer":[]}]}},"/credits/estimate":{"post":{"tags":["Credits"],"summary":"Estimate Credits","description":"About how many credits a document of `pages` pages would cost on a template, and whether the balance covers it. An estimate, not a quote: a run is charged for what it really costs once it succeeds (a range here, the exact figure in `credits_charged` of the extraction), and the check that decides whether a document starts is the one made when it does (status `insufficient credits` when the balance does not cover its hold). Credits only. A template without entities never reaches the model and is estimated at 0. Accounts on their own API key (enterprise_byok) have no credits: 404.","operationId":"estimate_credits_credits_estimate_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditsEstimateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditsEstimate"},"example":{"low":1,"high":3.48,"hold":3.48,"available":7.5,"enough":true}}}},"404":{"description":"The template does not exist or is not yours, or the account runs on its own API key (no credits)."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]}]}},"/auth/api-keys":{"get":{"tags":["Auth"],"summary":"List API Keys","description":"The account's active long-lived API keys, newest first. The key itself is never returned again after creation. Session token only: an API key gets 403.","operationId":"list_api_keys_auth_api_keys_get","security":[{"OAuth2PasswordBearer":[]}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}},"example":[{"id":"3f2b6c1e-8a4d-4f7e-9c2a-1b5d6e7f8a9b","name":"Billing sync","prefix":"prs_Xk3m9Qa2","created_at":"2026-10-19T12:00:00+00:00","last_used_at":null}]}}},"403":{"description":"Called with an API key"}}},"post":{"tags":["Auth"],"summary":"Create API Key","description":"Create a long-lived API key (`prs_…`). Send it as `Authorization: Bearer <key>` on any endpoint that takes the session token, except /auth/api-keys and /admin. The `key` is returned once and never stored. At most 10 active keys per account. Session token only: an API key gets 403. Refused while impersonating.","operationId":"create_api_key_auth_api_keys_post","security":[{"OAuth2PasswordBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreate"},"example":{"name":"Billing sync"}}}},"responses":{"201":{"description":"Created; `key` is shown only in this response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreated"},"example":{"id":"3f2b6c1e-8a4d-4f7e-9c2a-1b5d6e7f8a9b","name":"Billing sync","prefix":"prs_Xk3m9Qa2","created_at":"2026-10-19T12:00:00+00:00","last_used_at":null,"key":"prs_Xk3m9Qa2…"}}}},"403":{"description":"Called with an API key, or while impersonating"},"409":{"description":"The account already holds 10 active keys"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/auth/api-keys/{key_id}":{"delete":{"tags":["Auth"],"summary":"Revoke API Key","description":"Revoke a key: it stops authenticating at once and leaves the list. Session token only: an API key gets 403. Refused while impersonating.","operationId":"revoke_api_key_auth_api_keys__key_id__delete","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Key Id"}}],"responses":{"204":{"description":"Successful Response"},"403":{"description":"Called with an API key, or while impersonating"},"404":{"description":"Not found (or already revoked)"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/entity-groups/{group_id}/schema":{"get":{"tags":["Entity Groups"],"summary":"Get Template Schema","description":"The template's field tree (typed, nested) and its current version.","operationId":"get_template_schema","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"group_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateSchema"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["Entity Groups"],"summary":"Replace Template Schema","description":"Replaces the whole field tree and writes the next version. 409 when `base_version` is not the current version.","operationId":"put_template_schema","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"group_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateSchemaUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateSchema"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/entity-groups/{group_id}/versions":{"get":{"tags":["Entity Groups"],"summary":"List Template Versions","description":"Every version of the template's field tree, newest first.","operationId":"list_template_versions","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"group_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateVersionList"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/entity-groups/{group_id}/versions/{version}":{"get":{"tags":["Entity Groups"],"summary":"Get Template Version","description":"One version's field tree.","operationId":"get_template_version","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"group_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"version","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateVersion"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/entity-groups/{group_id}/versions/{version}/restore":{"post":{"tags":["Entity Groups"],"summary":"Restore Template Version","description":"Makes an old version's field tree current again — as the NEXT version (history is never rewritten).","operationId":"restore_template_version","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"group_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"version","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateSchema"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/template-ai/runs":{"post":{"tags":["Template AI"],"summary":"Create Template AI Run","description":"Generate a template (no `base_template_id`) or propose improvements to one, from 1–5 sources: documents already uploaded and/or new files. Starts at once when there is nothing to upload; otherwise PUT each file to its `upload_url` and call /start. Charged in credits when the proposal is ready.","operationId":"create_template_ai_run","security":[{"OAuth2PasswordBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateAiRunCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateAiRunCreated"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["Template AI"],"summary":"List Template AI Runs","description":"Your runs, newest first; `template_id` narrows to one template's.","operationId":"list_template_ai_runs","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"template_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"minimum":1,"maximum":100}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TemplateAiRun"}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/template-ai/runs/{run_id}":{"get":{"tags":["Template AI"],"summary":"Get Template AI Run","description":"The run, its sources and (when ready) its proposal.","operationId":"get_template_ai_run","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateAiRun"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Template AI"],"summary":"Dismiss Template AI Run","description":"Hides the run and deletes its uploaded files. 409 while it is analyzing.","operationId":"dismiss_template_ai_run","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/template-ai/runs/{run_id}/start":{"post":{"tags":["Template AI"],"summary":"Start Template AI Run","description":"Starts a run once its new files are uploaded (idempotent).","operationId":"start_template_ai_run","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateAiRun"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/template-ai/runs/{run_id}/apply":{"post":{"tags":["Template AI"],"summary":"Apply Template AI Proposal","description":"Accept or reject each proposed item. generate → creates the template (plan template cap applies); improve → the accepted changes become the template's next version (409 if a changed field no longer exists).","operationId":"apply_template_ai_run","security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateAiApply"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateAiApplied"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/.well-known/oauth-authorization-server":{"get":{"tags":["OAuth"],"summary":"Authorization Server Metadata","description":"RFC 8414 metadata for the OAuth server MCP clients (Claude, Claude Code, Cursor) sign in with: endpoints, PKCE S256, public clients, Dynamic Client Registration and Client ID Metadata Documents.","operationId":"oauth_authorization_server_metadata","responses":{"200":{"description":"Successful Response"}}}},"/.well-known/oauth-protected-resource":{"get":{"tags":["OAuth"],"summary":"Protected Resource Metadata","description":"RFC 9728 metadata for the MCP server at /mcp: the resource and its authorization server.","operationId":"oauth_protected_resource_metadata","responses":{"200":{"description":"Successful Response"}}}},"/.well-known/oauth-protected-resource/mcp":{"get":{"tags":["OAuth"],"summary":"Protected Resource Metadata (/mcp)","description":"Same document, at the path-suffixed location MCP clients try first.","operationId":"oauth_protected_resource_metadata_mcp","responses":{"200":{"description":"Successful Response"}}}},"/.well-known/agent-skills/index.json":{"get":{"tags":["Agent Skills"],"summary":"Agent Skills Index","description":"Agent Skills discovery index (agentskills.io schema 0.2.0): each skill with its URL and sha256 digest. `npx skills add https://api.parserai.co` reads it to install the parser-api skill, which teaches coding agents (Claude Code, Codex, Cursor) to integrate this API. Public.","operationId":"agent_skills_index","responses":{"200":{"description":"Successful Response","content":{"application/json":{"example":{"$schema":"https://schemas.agentskills.io/discovery/0.2.0/schema.json","skills":[{"name":"parser-api","type":"skill-md","description":"Integrate the Parser document-extraction REST API…","url":"parser-api/SKILL.md","digest":"sha256:…"}]}}}}}}},"/.well-known/agent-skills/{name}/SKILL.md":{"get":{"tags":["Agent Skills"],"summary":"Get Agent Skill","description":"The skill file (Markdown with YAML frontmatter). Public.","operationId":"agent_skill_file","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"},"example":"parser-api"}],"responses":{"200":{"description":"Successful Response","content":{"text/markdown":{}}},"404":{"description":"No skill with that name"}}}},"/oauth2/register":{"post":{"tags":["OAuth"],"summary":"Register OAuth Client","description":"Dynamic Client Registration (RFC 7591). Public clients only (token_endpoint_auth_method none). redirect_uris: https, loopback http (any port at authorize time), or an app scheme. Rate limited per IP.","operationId":"oauth_register","responses":{"201":{"description":"Registered","content":{"application/json":{"example":{"client_id":"mcp_Xk3m9Qa2b7Lp0Rt4Vw8Yz1Cd","client_name":"Claude","redirect_uris":["https://claude.ai/api/mcp/auth_callback"],"grant_types":["authorization_code"],"response_types":["code"],"token_endpoint_auth_method":"none"}}}},"400":{"description":"invalid_redirect_uri / invalid_client_metadata"},"429":{"description":"Too many registrations from this address"}},"requestBody":{"required":true,"content":{"application/json":{"example":{"client_name":"Claude","redirect_uris":["https://claude.ai/api/mcp/auth_callback"]}}}}}},"/oauth2/authorize":{"get":{"tags":["OAuth"],"summary":"Authorize","description":"Authorization endpoint (code flow, PKCE S256 required). Validates the client and redirect_uri, then redirects the browser to the console's consent page (/oauth/consent?request=…), where the signed-in user approves. Errors after the redirect_uri is validated go back to it.","operationId":"oauth_authorize","responses":{"302":{"description":"To the consent page, or back to the client with an error"},"400":{"description":"Unknown client or redirect_uri"}},"parameters":[{"name":"response_type","in":"query","required":true,"schema":{"type":"string"}},{"name":"client_id","in":"query","required":true,"schema":{"type":"string"}},{"name":"redirect_uri","in":"query","required":false,"schema":{"type":"string"}},{"name":"code_challenge","in":"query","required":true,"schema":{"type":"string"}},{"name":"code_challenge_method","in":"query","required":true,"schema":{"type":"string"}},{"name":"state","in":"query","required":false,"schema":{"type":"string"}},{"name":"scope","in":"query","required":false,"schema":{"type":"string"}},{"name":"resource","in":"query","required":false,"schema":{"type":"string"}}]}},"/oauth2/consent/{request_id}":{"get":{"tags":["OAuth"],"summary":"Get Consent Request","description":"What the consent page shows for a pending authorization: the app's name and where it redirects. Session token only.","operationId":"oauth_consent_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"example":{"client_name":"Claude","client_id":"mcp_Xk3m9Qa2b7Lp0Rt4Vw8Yz1Cd","verified_host":null,"redirect_off_domain":false,"redirect_host":"claude.ai","email":"alice@example.com","at_key_limit":false,"impersonating":false}}}},"404":{"description":"Request expired"}},"security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string"}}]},"post":{"tags":["OAuth"],"summary":"Decide Consent Request","description":"Approve or deny a pending authorization. Returns where to send the browser: the client's redirect_uri with a one-time code (approve) or error=access_denied. Session token only; refused while impersonating; 409 when the account holds the maximum of active API keys and none of them belongs to this app.","operationId":"oauth_consent_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"example":{"redirect":"https://claude.ai/api/mcp/auth_callback?code=…&state=…&iss=https%3A%2F%2Fround-lake.dustinice.workers.dev%3A443%2Fhttps%2Fapi.parserai.co"}}}},"403":{"description":"Impersonating"},"404":{"description":"Request expired"},"409":{"description":"API key limit reached"}},"security":[{"OAuth2PasswordBearer":[]}],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"approve":true}}}}}},"/oauth2/token":{"post":{"tags":["OAuth"],"summary":"Token","description":"Exchange an authorization code (with its PKCE code_verifier) for an access token. Form-encoded (JSON accepted). The access token is an API key (prs_…) named after the app: it does not expire and is revoked on the API keys page. Each connection gets its own key; at the 10-key cap the same app's least recently used key is retired. The code is single-use, redeemed atomically.","operationId":"oauth_token","responses":{"200":{"description":"Successful Response","content":{"application/json":{"example":{"access_token":"prs_…","token_type":"Bearer","scope":"parser"}}}},"400":{"description":"invalid_grant / invalid_request / unsupported_grant_type"}},"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"example":"grant_type=authorization_code&code=…&code_verifier=…&client_id=…&redirect_uri=…"}}}}}},"components":{"schemas":{"Body_upload_document_endpoint_documents_upload_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File","description":"The document file (PDF, TXT, JSON, DOCX, CSV, XLSX)"},"entity_group_id":{"type":"string","format":"uuid","title":"Entity Group Id","description":"The ID of the entity group to associate with the document"},"custom_metadata_json":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Custom Metadata Json","description":"Custom metadata for the document in JSON string format"},"gemini_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gemini Model","description":"Override the Gemini model used for this document's extraction. Only accepted for enterprise_byok users. Must be one of the allowed models."}},"type":"object","required":["file","entity_group_id"],"title":"Body_upload_document_endpoint_documents_upload_post"},"Body_upload_document_for_template_creation_endpoint_documents_upload_template_creation_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File","description":"The document file (PDF, TXT, JSON, DOCX, CSV, XLSX)"}},"type":"object","required":["file"],"title":"Body_upload_document_for_template_creation_endpoint_documents_upload_template_creation_post"},"Document":{"properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"file_path":{"type":"string","title":"File Path"},"file_type":{"type":"string","title":"File Type"},"file_size":{"type":"integer","title":"File Size"},"status":{"type":"string","title":"Status"},"page_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page Count"},"id":{"type":"string","format":"uuid","title":"Id"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"},{},{"type":"null"}],"title":"Metadata"},"user_id":{"type":"string","format":"uuid","title":"User Id"},"file_purged_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"File Purged At","description":"When the stored file was released by POST /plan/storage/purge. Null while the original file is still stored; non-null means the extraction results are intact but the file is gone (and the document can no longer be reprocessed)."}},"type":"object","required":["file_path","file_type","file_size","status","user_id"],"title":"Document"},"DocumentCountResponse":{"properties":{"total_documents":{"type":"integer","title":"Total Documents"},"documents_current_month":{"type":"integer","title":"Documents Current Month"},"documents_current_day":{"type":"integer","title":"Documents Current Day"},"total_pages":{"type":"integer","title":"Total Pages"},"pages_current_month":{"type":"integer","title":"Pages Current Month"},"pages_current_day":{"type":"integer","title":"Pages Current Day"}},"type":"object","required":["total_documents","documents_current_month","documents_current_day","total_pages","pages_current_month","pages_current_day"],"title":"DocumentCountResponse","description":"Response model for document count and pages endpoint"},"DocumentUpdate":{"properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"file_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"File Path"},"file_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"File Type"},"file_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"File Size"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"},"page_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page Count"}},"type":"object","title":"DocumentUpdate"},"Entity":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prompt"},"user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"User Id"},"type":{"type":"string","enum":["text","number","boolean","date","object","list"],"title":"Type","default":"text"},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Parent Id","description":"The enclosing object/list field (null = top level). Edited through PUT /entity-groups/{group_id}/schema."},"position":{"type":"integer","title":"Position","description":"Order among siblings."}},"type":"object","required":["name"],"title":"Entity"},"EntityCreate":{"properties":{"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prompt"},"type":{"type":"string","enum":["text","number","boolean","date","object","list"],"title":"Type","description":"Field type (default text). object/list fields hold nested fields."}},"type":"object","required":["name"],"title":"EntityCreate"},"EntityGroup":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"User Id"},"webhook_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Webhook Id"},"current_version":{"type":"integer","title":"Current Version","description":"Latest version of the template's field tree (0 = not versioned yet; the first read or change takes v1)."},"record_mode":{"type":"string","enum":["auto","single","list"],"title":"Record Mode","description":"What one document yields: single = exactly one record (the template is one object); list = a list of records shaped like the template; auto = the model decides. The extracted data is always an array of records."}},"type":"object","required":["name"],"title":"EntityGroup"},"EntityGroupCreate":{"properties":{"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"webhook_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Webhook Id"},"record_mode":{"type":"string","enum":["auto","single","list"],"title":"Record Mode","description":"What one document yields: single = exactly one record (the template is one object); list = a list of records shaped like the template; auto = the model decides. The extracted data is always an array of records."}},"type":"object","required":["name"],"title":"EntityGroupCreate"},"EntityGroupUpdate":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"webhook_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Webhook Id"},"record_mode":{"type":"string","enum":["auto","single","list"],"title":"Record Mode","description":"What one document yields: single = exactly one record (the template is one object); list = a list of records shaped like the template; auto = the model decides. The extracted data is always an array of records."}},"type":"object","title":"EntityGroupUpdate"},"EntityGroupWithEntities":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"User Id"},"webhook_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Webhook Id"},"entities":{"items":{"$ref":"#/components/schemas/Entity"},"type":"array","title":"Entities"}},"type":"object","required":["name","entities"],"title":"EntityGroupWithEntities","description":"Response: entity group with its linked entities."},"EntityGroupWithEntitiesCreate":{"properties":{"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"webhook_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Webhook Id"},"entities":{"items":{"$ref":"#/components/schemas/EntityCreate"},"type":"array","title":"Entities"},"record_mode":{"type":"string","enum":["auto","single","list"],"title":"Record Mode","description":"What one document yields: single = exactly one record (the template is one object); list = a list of records shaped like the template; auto = the model decides. The extracted data is always an array of records."}},"type":"object","required":["name","entities"],"title":"EntityGroupWithEntitiesCreate","description":"Request: create entity group with entities (auto-linked)."},"EntityUpdate":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prompt"},"type":{"type":"string","enum":["text","number","boolean","date","object","list"],"title":"Type","description":"Field type (default text). object/list fields hold nested fields."}},"type":"object","title":"EntityUpdate"},"ExtractedDocument":{"properties":{"document_id":{"type":"string","format":"uuid","title":"Document Id"},"entity_group_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Group Id"},"extracted_data":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Extracted Data"},"extraction_status":{"type":"string","title":"Extraction Status","default":"pending"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"},"custom_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Custom Metadata"},"model_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model Version"},"total_token_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Token Count"},"prompt_token_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Prompt Token Count"},"thoughts_token_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Thoughts Token Count"},"candidates_token_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Candidates Token Count"},"id":{"type":"string","format":"uuid","title":"Id"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"credits_estimate_low":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Credits Estimate Low","description":"The cheap end of the credit estimate of this run (credits), set when it is validated; null before that and for accounts on their own API key."},"credits_estimate_high":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Credits Estimate High","description":"The expensive end of the credit estimate of this run (credits)."},"credits_charged":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Credits Charged","description":"What this extraction was charged (credits), set when it succeeds; null until then, after a failure and for accounts on their own API key. A reprocess is a new run: it charges again and replaces this figure."}},"type":"object","required":["document_id","id","created_at","updated_at"],"title":"ExtractedDocument"},"ExtractedDocumentCreate":{"properties":{"document_id":{"type":"string","format":"uuid","title":"Document Id"},"entity_group_id":{"type":"string","format":"uuid","title":"Entity Group Id"},"extracted_data":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Extracted Data"},"extraction_status":{"type":"string","title":"Extraction Status","default":"pending"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"},"custom_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Custom Metadata"},"model_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model Version"},"total_token_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Token Count"},"prompt_token_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Prompt Token Count"},"thoughts_token_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Thoughts Token Count"},"candidates_token_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Candidates Token Count"}},"type":"object","required":["document_id","entity_group_id"],"title":"ExtractedDocumentCreate"},"ExtractedDocumentUpdate":{"properties":{"extracted_data":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Extracted Data"},"extraction_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Extraction Status"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"},"custom_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Custom Metadata"},"model_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model Version"},"total_token_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Token Count"},"prompt_token_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Prompt Token Count"},"thoughts_token_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Thoughts Token Count"},"candidates_token_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Candidates Token Count"}},"type":"object","title":"ExtractedDocumentUpdate"},"ExtractionWithDocumentInfo":{"properties":{"id":{"type":"string","title":"Id"},"document_id":{"type":"string","title":"Document Id"},"entity_group_id":{"type":"string","title":"Entity Group Id"},"extracted_data":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Extracted Data"},"extraction_status":{"type":"string","title":"Extraction Status"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"},"custom_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Custom Metadata"},"model_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model Version"},"total_token_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Token Count"},"prompt_token_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Prompt Token Count"},"thoughts_token_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Thoughts Token Count"},"candidates_token_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Candidates Token Count"},"created_at":{"type":"string","title":"Created At"},"updated_at":{"type":"string","title":"Updated At"},"document_title":{"type":"string","title":"Document Title"},"document_file_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document File Type"},"document_created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Created At"},"credits_estimate_low":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Credits Estimate Low","description":"The cheap end of the credit estimate of this run (credits), set when it is validated; null before that and for accounts on their own API key."},"credits_estimate_high":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Credits Estimate High","description":"The expensive end of the credit estimate of this run (credits)."},"credits_charged":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Credits Charged","description":"What this extraction was charged (credits), set when it succeeds; null until then, after a failure and for accounts on their own API key. A reprocess is a new run: it charges again and replaces this figure."}},"type":"object","required":["id","document_id","entity_group_id","extracted_data","extraction_status","created_at","updated_at","document_title"],"title":"ExtractionWithDocumentInfo","description":"Extended extraction model with document metadata for batch results view"},"ExtractionsByTemplateResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/ExtractionWithDocumentInfo"},"type":"array","title":"Data"},"total_count":{"type":"integer","title":"Total Count"},"skip":{"type":"integer","title":"Skip"},"limit":{"type":"integer","title":"Limit"},"has_more":{"type":"boolean","title":"Has More"}},"type":"object","required":["data","total_count","skip","limit","has_more"],"title":"ExtractionsByTemplateResponse","description":"Paginated response for extractions by template"},"ForgotPasswordRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email"},"cf-turnstile-response":{"type":"string","title":"Cf-Turnstile-Response"}},"type":"object","required":["email","cf-turnstile-response"],"title":"ForgotPasswordRequest"},"GeminiAPIKeyUpdate":{"properties":{"provider":{"type":"string","title":"Provider","description":"LLM provider the key belongs to. Defaults to 'gemini'."},"api_key":{"type":"string","title":"Api Key","description":"The provider API key."},"gemini_api_key":{"type":"string","title":"Gemini Api Key","description":"Legacy alias for 'api_key' (api_key wins when both are sent)."}},"type":"object","title":"GeminiAPIKeyUpdate","description":"BYOK key update: send 'api_key' (+ optional 'provider', default gemini). 'gemini_api_key' is the legacy alias for 'api_key'; one of the two is required."},"GoogleSigninRequest":{"properties":{"cf-turnstile-response":{"type":"string","title":"Cf-Turnstile-Response"}},"type":"object","required":["cf-turnstile-response"],"title":"GoogleSigninRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"LlmDefaultsUpdate":{"properties":{"default_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Default Model","description":"Model ref: 'provider/model' or a bare catalog model. null clears the preference."}},"type":"object","title":"LlmDefaultsUpdate"},"OnboardingTutorialUpdate":{"properties":{"onboarding_tutorial":{"type":"boolean","title":"Onboarding Tutorial","description":"Whether user has completed the onboarding tutorial"}},"type":"object","required":["onboarding_tutorial"],"title":"OnboardingTutorialUpdate","description":"Used when updating just the onboarding tutorial status"},"Profile":{"properties":{"full_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Full Name"},"avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar Url"},"role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Role"},"has_enabled_mfa":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Enabled Mfa"},"gemini_api_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gemini Api Key"},"subscription_plan":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subscription Plan"},"stripe_customer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stripe Customer Id"},"initial_credits_granted":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Initial Credits Granted"},"id":{"type":"string","format":"uuid","title":"Id"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"enrolled_factors":{"anyOf":[{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"},{"type":"null"}],"title":"Enrolled Factors"}},"type":"object","required":["id","created_at","updated_at"],"title":"Profile","description":"Complete profile model with all fields"},"ProfileMe":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Role"},"subscription_plan":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subscription Plan"},"has_api_key_configured":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Api Key Configured"},"onboarding_tutorial":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Onboarding Tutorial"},"full_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Full Name"},"default_llm_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Default Llm Model","description":"Canonical 'provider/model' ref; null = platform default."},"deletion_requested_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deletion Requested At","description":"ISO timestamp of a pending account-deletion request; null = none."}},"type":"object","required":["id"],"title":"ProfileMe","description":"Optimized profile model for /profiles/me endpoint - includes only essential fields"},"ReprocessRequest":{"properties":{"gemini_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gemini Model","description":"Override the Gemini model used when reprocessing this document. Only accepted for enterprise_byok users. Must be one of the allowed models. Omit this field to keep the model stored from the original upload; sending null does not clear the override — use an explicit allowed model name (e.g. gemini-2.5-pro) to switch back to the worker default."}},"type":"object","title":"ReprocessRequest"},"ResetPasswordRequest":{"properties":{"token":{"type":"string","title":"Token"},"password":{"type":"string","title":"Password"}},"type":"object","required":["token","password"],"title":"ResetPasswordRequest"},"SignedUrlRequest":{"properties":{"file_name":{"type":"string","title":"File Name","description":"The name of the file to be uploaded."},"entity_group_id":{"type":"string","format":"uuid","title":"Entity Group Id","description":"The ID of the entity group to associate with the document."},"custom_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Custom Metadata","description":"Custom metadata for the document."},"gemini_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gemini Model","description":"Override the Gemini model used for this document's extraction. Only accepted for enterprise_byok users. Must be one of the allowed models."}},"type":"object","required":["file_name","entity_group_id"],"title":"SignedUrlRequest"},"SignedUrlResponse":{"properties":{"signed_url":{"type":"string","title":"Signed Url","description":"Short-lived worker-signed upload URL (PUT /uploads/{token})."},"document_id":{"type":"string","format":"uuid","title":"Document Id","description":"The ID of the created document record."},"extracted_document_id":{"type":"string","format":"uuid","title":"Extracted Document Id","description":"The ID of the created extracted_document record."},"gcs_path":{"type":"string","title":"Gcs Path","description":"Storage URI where the file will be stored (r2://... — field name kept for backward compatibility)."}},"type":"object","required":["signed_url","document_id","extracted_document_id","gcs_path"],"title":"SignedUrlResponse"},"SignupRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email"},"password":{"type":"string","title":"Password"},"cf-turnstile-response":{"type":"string","title":"Cf-Turnstile-Response"}},"type":"object","required":["email","password","cf-turnstile-response"],"title":"SignupRequest"},"TemplateCreationSignedUrlRequest":{"properties":{"file_name":{"type":"string","title":"File Name","description":"The name of the file to be uploaded."}},"type":"object","required":["file_name"],"title":"TemplateCreationSignedUrlRequest","description":"Request model for generating a signed URL for template creation upload."},"TemplateCreationSignedUrlResponse":{"properties":{"signed_url":{"type":"string","title":"Signed Url","description":"Short-lived worker-signed upload URL (PUT /uploads/{token})."},"document_id":{"type":"string","format":"uuid","title":"Document Id","description":"The ID of the created document record."},"gcs_path":{"type":"string","title":"Gcs Path","description":"Storage URI where the file will be stored (r2://... — field name kept for backward compatibility)."}},"type":"object","required":["signed_url","document_id","gcs_path"],"title":"TemplateCreationSignedUrlResponse","description":"Response model for template creation signed URL endpoint."},"UploadLimitResponse":{"properties":{"subscription_plan":{"type":"string","title":"Subscription Plan"},"uploads_today":{"type":"integer","title":"Uploads Today"},"daily_limit":{"anyOf":[{"type":"string"},{"type":"integer"}],"title":"Daily Limit"},"remaining_uploads":{"anyOf":[{"type":"string"},{"type":"integer"}],"title":"Remaining Uploads"},"has_limit":{"type":"boolean","title":"Has Limit"},"monthly_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Monthly Limit","description":"Documents the plan processes per monthly window; null = no limit."},"monthly_used":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Monthly Used","description":"Documents counted in the current window; null when the plan has no monthly document limit."},"monthly_remaining":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Monthly Remaining","description":"Documents left in the current window; null when the plan has no monthly document limit."}},"type":"object","required":["subscription_plan","uploads_today","daily_limit","remaining_uploads","has_limit","monthly_limit","monthly_used","monthly_remaining"],"title":"UploadLimitResponse","description":"Response model for the upload limit endpoint"},"UserResponse":{"properties":{"id":{"type":"string","title":"Id"},"email":{"type":"string","format":"email","title":"Email"},"role":{"type":"string","title":"Role"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"user_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"User Metadata"}},"type":"object","required":["id","email","role","created_at"],"title":"UserResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WebhookCreate":{"properties":{"name":{"type":"string","maxLength":255,"minLength":1,"title":"Name","description":"Name of the webhook"},"url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Url","description":"URL of the webhook endpoint"},"events":{"items":{"type":"string"},"type":"array","title":"Events","description":"List of event types this webhook subscribes to"},"is_active":{"type":"boolean","title":"Is Active","description":"Whether the webhook is currently active","default":true},"headers":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Headers","description":"Custom HTTP headers to send with the webhook"}},"type":"object","required":["name","url"],"title":"WebhookCreate"},"WebhookInDB":{"properties":{"name":{"type":"string","maxLength":255,"minLength":1,"title":"Name","description":"Name of the webhook"},"url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Url","description":"URL of the webhook endpoint"},"events":{"items":{"type":"string"},"type":"array","title":"Events","description":"List of event types this webhook subscribes to"},"is_active":{"type":"boolean","title":"Is Active","description":"Whether the webhook is currently active","default":true},"headers":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Headers","description":"Custom HTTP headers to send with the webhook"},"id":{"type":"string","format":"uuid","title":"Id","description":"Unique ID of the webhook"},"user_id":{"type":"string","format":"uuid","title":"User Id","description":"ID of the user who owns this webhook"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp of when the webhook was created"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"Timestamp of when the webhook was last updated"}},"type":"object","required":["name","url","id","user_id","created_at","updated_at"],"title":"WebhookInDB"},"WebhookLogInDB":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique ID of the log entry"},"webhook_id":{"type":"string","format":"uuid","title":"Webhook Id","description":"ID of the webhook that was called"},"user_id":{"type":"string","format":"uuid","title":"User Id","description":"ID of the webhook owner"},"document_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Document Id","description":"Related document ID"},"extracted_document_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Extracted Document Id","description":"Related extracted document ID"},"request_payload":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Request Payload","description":"JSON payload sent to the webhook URL"},"response_status_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Response Status Code","description":"HTTP response status code"},"response_body":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Body","description":"Response body (truncated to 5000 chars)"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message","description":"Network or application error message, if any"},"success":{"type":"boolean","title":"Success","description":"Whether the webhook call succeeded (2xx response)"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp of the webhook call"}},"type":"object","required":["id","webhook_id","user_id","success","created_at"],"title":"WebhookLogInDB"},"WebhookUpdate":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":255,"minLength":1},{"type":"null"}],"title":"Name","description":"Name of the webhook"},"url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Url","description":"URL of the webhook endpoint"},"events":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Events","description":"List of event types this webhook subscribes to"},"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Active","description":"Whether the webhook is currently active"},"headers":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Headers","description":"Custom HTTP headers to send with the webhook"}},"type":"object","title":"WebhookUpdate"},"ChangePasswordRequest":{"properties":{"current_password":{"type":"string","title":"Current Password"},"new_password":{"type":"string","title":"New Password","minLength":6}},"type":"object","required":["current_password","new_password"],"title":"ChangePasswordRequest"},"ProfileUpdate":{"properties":{"full_name":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"title":"Full Name"}},"type":"object","title":"ProfileUpdate","description":"PATCH semantics: omitted = keep, null/empty = clear."},"AccountDeletionRequest":{"properties":{"reason":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Reason"}},"type":"object","title":"AccountDeletionRequest"},"PlanSummary":{"type":"object","title":"PlanSummary","required":["subscription_plan","entitlement","credits"],"properties":{"subscription_plan":{"type":"string","title":"Subscription Plan"},"entitlement":{"$ref":"#/components/schemas/PlanEntitlement"},"credits":{"anyOf":[{"$ref":"#/components/schemas/CreditsInfo"},{"type":"null"}],"description":"The credit balance; null for accounts on the enterprise contract (their own API key: no credits)."}}},"PlanUsage":{"properties":{"subscription_plan":{"type":"string","title":"Subscription Plan"},"generated_at":{"type":"string","format":"date-time","title":"Generated At"},"period":{"type":"object","title":"Period","properties":{"month":{"type":"string","title":"Month","description":"YYYY-MM (UTC) — the month being reported, not necessarily the current one."},"days_elapsed":{"type":"integer","title":"Days Elapsed","description":"Days of the month elapsed; a closed month is fully elapsed."},"days_in_month":{"type":"integer","title":"Days In Month"},"is_current":{"type":"boolean","title":"Is Current","description":"False when a closed month is reported instead of the one in progress."},"closed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Closed At","description":"First instant after the reported month (its exclusive end); null while it is still running."}}},"documents":{"type":"object","title":"Documents","properties":{"current_month":{"type":"integer","title":"Current Month","description":"Documents created in `period.month`."},"pages_current_month":{"type":"integer","title":"Pages Current Month","description":"Pages of those documents."},"previous_month":{"type":"integer","title":"Previous Month","description":"Documents in the month before `period.month`."},"projected_month_end":{"type":"integer","title":"Projected Month End","description":"Straight-line pace: count / days elapsed * days in month. Equals the actual count for a closed month, which has fully elapsed."},"history":{"type":"array","title":"History","description":"Last 12 calendar months relative to now, oldest first, empty months included — the same window whichever month is reported.","items":{"type":"object","properties":{"month":{"type":"string"},"documents":{"type":"integer"},"pages":{"type":"integer"},"bytes":{"type":"integer","description":"Bytes uploaded that month."}}}}}},"storage":{"type":"object","title":"Storage","properties":{"bytes":{"type":"integer","title":"Bytes","description":"Files stored as of `storage.as_of` (purged documents no longer count). For a closed month this is the end-of-month snapshot, reconstructed from the documents that still exist: created before the month ended, with the purge stamp absent or later. A document deleted outright since is unrecoverable, so a snapshot can under-report a month but never over-report it."},"files":{"type":"integer","title":"Files"},"oldest_file_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Oldest File At"},"cleanup_windows":{"type":"array","title":"Cleanup Windows","description":"What POST /plan/storage/purge would release per window. Empty for a closed month — a purge acts on now, never on the past.","items":{"type":"object","properties":{"older_than_days":{"type":"integer"},"files":{"type":"integer"},"bytes":{"type":"integer"}}}},"as_of":{"type":"string","format":"date-time","title":"As Of","description":"Instant the storage numbers reflect: the month's close, or now."}}},"plan":{"anyOf":[{"type":"object","properties":{"storage_included_gb":{"type":"number"},"tiers":{"type":"array","items":{"$ref":"#/components/schemas/PlanTier"}}}},{"type":"null"}],"title":"Plan","description":"Contracted service levels; null unless the account is on the enterprise contract. Carries no prices."},"plan_status":{"anyOf":[{"type":"object","properties":{"tier":{"anyOf":[{"$ref":"#/components/schemas/PlanTier"},{"type":"null"}]},"next_tier":{"anyOf":[{"$ref":"#/components/schemas/PlanTier"},{"type":"null"}]},"over_top_tier":{"type":"boolean"},"documents_used":{"type":"integer"},"documents_limit":{"anyOf":[{"type":"integer"},{"type":"null"}]},"documents_remaining":{"anyOf":[{"type":"integer"},{"type":"null"}]},"storage_gb":{"type":"number"},"storage_above_allowance_gb":{"type":"number"}}},{"type":"null"}],"title":"Plan Status","description":"Where the current month sits against those levels; null off-contract."},"entitlement":{"$ref":"#/components/schemas/PlanEntitlement"},"credits":{"anyOf":[{"$ref":"#/components/schemas/CreditsInfo"},{"type":"null"}],"description":"The credit balance; null for accounts on the enterprise contract (their own API key: no credits)."}},"type":"object","title":"PlanUsage"},"StoragePurgeRequest":{"properties":{"older_than_days":{"type":"integer","minimum":0,"maximum":3650,"title":"Older Than Days","description":"Delete stored files of documents created before now - N days. 0 = every stored file."},"max_documents":{"anyOf":[{"type":"integer","minimum":1,"maximum":1000},{"type":"null"}],"title":"Max Documents","description":"Batch size (default and maximum 1000)."}},"type":"object","required":["older_than_days"],"title":"StoragePurgeRequest"},"StoragePurgeResponse":{"properties":{"purged":{"type":"integer","title":"Purged"},"freed_bytes":{"type":"integer","title":"Freed Bytes"},"failed":{"type":"integer","title":"Failed","description":"Files storage refused to delete; still stored and still billed."},"remaining":{"type":"integer","title":"Remaining","description":"Documents still matching the window — call again while above 0."},"cutoff":{"type":"string","format":"date-time","title":"Cutoff"}},"type":"object","required":["purged","freed_bytes","failed","remaining","cutoff"],"title":"StoragePurgeResponse"},"PlanTier":{"properties":{"level":{"type":"integer","title":"Level"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"max_documents":{"type":"integer","title":"Max Documents"}},"type":"object","required":["level","name","max_documents"],"title":"PlanTier","description":"One contracted service level: up to `max_documents` a month. No price — enterprise fees are negotiated per contract and are never returned by the API."},"PlanLimits":{"type":"object","title":"PlanLimits","description":"A plan's allowances. null = unlimited.","properties":{"documents_per_month":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Documents processed per monthly window. null for every plan today: a month's volume is measured in credits (see `credits` of `GET /plan/usage`), the visible limits are pages per document, parallel documents and templates."},"max_pages_per_document":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"A document with more pages is rejected whole (status `too large`)."},"pages_per_month":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Pages processed per monthly window. null for every plan today: credits and pages per document are the limits."},"parallel_documents":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Documents extracting at the same time; the rest wait their turn."},"templates":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Templates (entity groups) the account may keep."}},"required":["documents_per_month","max_pages_per_document","pages_per_month","parallel_documents","templates"]},"PlanCatalogEntry":{"type":"object","title":"PlanCatalogEntry","properties":{"key":{"type":"string","enum":["free","starter","pro"]},"name":{"type":"string"},"price_monthly_usd":{"type":"number","description":"USD per month, billed monthly."},"price_annual_usd":{"type":"number","description":"USD per year, billed annually (monthly x 12, -20%)."},"limits":{"$ref":"#/components/schemas/PlanLimits"},"credits_per_month":{"type":"integer","description":"Plan credits granted every monthly window. They reset with the window and never roll over."},"topup_bonus_percent":{"type":"integer","description":"Extra credits a top-up pack earns on this plan, in percent (0 on Free)."},"price_per_credit_usd":{"type":"number","description":"What one credit costs on this plan when bought as a top-up pack, in USD."}},"required":["key","name","price_monthly_usd","price_annual_usd","limits","credits_per_month","topup_bonus_percent","price_per_credit_usd"]},"PlanCatalog":{"type":"object","title":"PlanCatalog","properties":{"plans":{"type":"array","items":{"$ref":"#/components/schemas/PlanCatalogEntry"}},"credit_packs_usd":{"type":"array","items":{"type":"integer"},"description":"The top-up pack sizes, in whole USD."}},"required":["plans","credit_packs_usd"]},"PlanEntitlement":{"type":"object","title":"PlanEntitlement","description":"The plan that applies to the account right now and what its current monthly window has used.","properties":{"plan":{"type":"string","enum":["free","starter","pro","enterprise_byok"],"description":"The plan in force. A comp grant that ended, or a subscription Stripe cancelled or stopped collecting, reads as `free`."},"assigned_plan":{"type":"string","description":"`subscription_plan` as stored: what was granted or bought, even when it no longer applies."},"source":{"type":"string","enum":["free","stripe","comp","contract"],"description":"`stripe` = a paid subscription; `comp` = granted by an admin; `contract` = enterprise_byok."},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Stripe subscription status (`active`, `trialing`, `past_due`, ...), `comp`, or null."},"interval":{"anyOf":[{"type":"string","enum":["month","year"]},{"type":"null"}],"description":"Billing interval of a paid subscription."},"cancel_at_period_end":{"type":"boolean","description":"The subscription ends when the paid period does."},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"End of the paid period or comp grant; null = none."},"limits":{"$ref":"#/components/schemas/PlanLimits"},"window":{"type":"object","description":"The monthly quota window now in force: the monthly anniversary of the subscription / grant start for paid and comp accounts (annual subscriptions get monthly windows too), the UTC calendar month otherwise.","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time","description":"Exclusive; the allowance resets here."}},"required":["start","end"]},"usage":{"type":"object","description":"Consumption against `limits`.","properties":{"documents":{"type":"integer","description":"Successful extractions in the window."},"pages":{"type":"integer","description":"Pages of those extractions."},"parallel_in_flight":{"type":"integer","description":"Documents extracting right now."},"templates":{"type":"integer","description":"Templates (entity groups) the account has."}},"required":["documents","pages","parallel_in_flight","templates"]}},"required":["plan","assigned_plan","source","status","interval","cancel_at_period_end","expires_at","limits","window","usage"]},"SubscriptionCheckoutRequest":{"type":"object","title":"SubscriptionCheckoutRequest","properties":{"plan":{"type":"string","enum":["starter","pro"]},"interval":{"type":"string","enum":["month","year"],"description":"`year` bills annually at 20% off the monthly price."}},"required":["plan","interval"]},"SubscriptionCheckoutResponse":{"type":"object","title":"SubscriptionCheckoutResponse","properties":{"checkout_url":{"type":"string","description":"Stripe Checkout page to redirect the user to."},"session_id":{"type":"string","description":"Stripe checkout session id."}},"required":["checkout_url","session_id"]},"BillingPortalResponse":{"type":"object","title":"BillingPortalResponse","properties":{"portal_url":{"type":"string","description":"Stripe Billing Portal page to redirect the user to."}},"required":["portal_url"]},"ErrorResponse":{"type":"object","title":"ErrorResponse","properties":{"detail":{"type":"string"}},"required":["detail"]},"CreditsInfo":{"type":"object","title":"CreditsInfo","description":"The credit balance and what tops it up. Credits are numbers with up to 2 decimals. Never a dollar cost.","properties":{"balance":{"type":"object","properties":{"plan":{"type":"number","description":"Plan credits left in the current window: spent first, reset with the window, never roll over."},"purchased":{"type":"number","description":"Bought (and gifted) credits left: spent after the plan credits, never expire. Can be negative after a run that cost more than was reserved."},"held":{"type":"number","description":"Reserved by the documents processing right now."},"available":{"type":"number","description":"plan + purchased - held: what a new document can draw on. A document starts only when this covers its estimate (otherwise `insufficient credits`)."}},"required":["plan","purchased","held","available"]},"plan":{"type":"object","properties":{"credits_per_month":{"type":"integer","description":"Plan credits granted every window."},"resets_at":{"type":"string","format":"date-time","description":"When the next window starts and its plan credits are granted (the unspent ones expire)."}},"required":["credits_per_month","resets_at"]},"topup":{"type":"object","properties":{"credits_per_usd":{"type":"number","description":"Credits one USD of top-up buys on this plan."},"bonus_percent":{"type":"integer","description":"Extra credits a top-up earns on this plan against Free, in percent."},"packs":{"type":"array","items":{"type":"object","properties":{"usd":{"type":"integer"},"credits":{"type":"integer","description":"Whole credits the pack buys on this plan."}},"required":["usd","credits"]}}},"required":["credits_per_usd","bonus_percent","packs"]},"breaker":{"anyOf":[{"type":"object","properties":{"reached":{"type":"boolean","description":"The monthly fair-use limit is reached: new documents wait, as `limit reached`, until `plan.resets_at`. A flag only, never a figure."}},"required":["reached"]},{"type":"null"}],"description":"The fair-use limit of the window (what failed and abandoned runs may cost in one window). null when it does not apply."}},"required":["balance","plan","topup","breaker"]},"CreditsEstimateRequest":{"type":"object","title":"CreditsEstimateRequest","properties":{"pages":{"type":"integer","minimum":1,"description":"Pages of the document (a PDF's page count, 1 for an image)."},"template_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The extraction template (entity group) of the document. Omit for AI template creation: the estimate is then the template-writing call alone (the extraction that follows is estimated, held and charged when it starts)."}},"required":["pages"]},"CreditsEstimate":{"type":"object","title":"CreditsEstimate","properties":{"low":{"type":"number","description":"The cheap end of the expected cost, in credits."},"high":{"type":"number","description":"The expensive end of the expected cost, in credits."},"hold":{"type":"number","description":"What a run reserves while it processes: the high end, capped by the most one model call can cost. A document starts only when `available` covers it."},"available":{"type":"number","description":"The balance a new document can draw on right now (plan + purchased - held)."},"enough":{"type":"boolean","description":"`available` covers `hold`."}},"required":["low","high","hold","available","enough"]},"CreditPackCheckoutRequest":{"type":"object","title":"CreditPackCheckoutRequest","properties":{"pack_usd":{"type":"integer","description":"The pack size in USD, one of the offered packs (10, 25, 50 or 100 today). The credits it buys are not sent by the client."}},"required":["pack_usd"]},"CreditPackCheckoutResponse":{"type":"object","title":"CreditPackCheckoutResponse","properties":{"url":{"type":"string","description":"Stripe Checkout page to redirect the user to."}},"required":["url"]},"AdminUserCredits":{"type":"object","title":"AdminUserCredits","description":"An account's credit balance right now, in credits (up to 2 decimals).","properties":{"plan":{"type":"number","description":"Plan credits left in the account's current window."},"purchased":{"type":"number","description":"Bought and gifted credits left (can be negative after an overrun or a refund of spent credits)."},"held":{"type":"number","description":"Reserved by the documents processing right now."},"available":{"type":"number","description":"plan + purchased - held."}},"required":["plan","purchased","held","available"]},"AdminCreditsGrantRequest":{"type":"object","title":"AdminCreditsGrantRequest","properties":{"credits":{"type":"number","exclusiveMinimum":0,"maximum":1000000,"description":"Credits to add (up to 6 decimals)."},"note":{"type":["string","null"],"maxLength":500,"description":"Optional reason, kept in the ledger."}},"required":["credits"]},"AdminCreditsGrantResponse":{"type":"object","title":"AdminCreditsGrantResponse","properties":{"user_id":{"type":"string","format":"uuid"},"granted":{"type":"number","description":"The credits added."},"balance":{"anyOf":[{"$ref":"#/components/schemas/AdminUserCredits"},{"type":"null"}],"description":"The account's balance after the grant."}},"required":["user_id","granted","balance"]},"ApiKey":{"type":"object","title":"ApiKey","required":["id","name","prefix","created_at","last_used_at"],"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"prefix":{"type":"string","title":"Prefix","description":"The key's first 12 characters, to tell keys apart"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"last_used_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Used At","description":"Last authenticated request, to the minute; null if never used"},"source":{"type":"string","enum":["manual","oauth"],"description":"oauth: issued to a connected app (Claude, Cursor…) when it signed in; manual: made on the API keys page.","title":"Source"}}},"ApiKeyCreate":{"type":"object","title":"ApiKeyCreate","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":60,"title":"Name","description":"What the key is for (trimmed)"}}},"ApiKeyCreated":{"type":"object","title":"ApiKeyCreated","required":["id","name","prefix","created_at","last_used_at","key"],"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"prefix":{"type":"string","title":"Prefix","description":"The key's first 12 characters, to tell keys apart"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"last_used_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Used At","description":"Last authenticated request, to the minute; null if never used"},"key":{"type":"string","title":"Key","description":"The secret, `prs_` + 43 characters. Shown once."}}},"FieldNode":{"type":"object","title":"FieldNode","required":["name","type"],"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Omit for a new field; keep it to update a field in place."},"name":{"type":"string","maxLength":50,"title":"Name","description":"The JSON key of the extracted value; unique among siblings."},"type":{"type":"string","enum":["text","number","boolean","date","object","list"],"title":"Type"},"prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prompt","description":"Where to find the value / what it looks like."},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"children":{"type":"array","items":{"$ref":"#/components/schemas/FieldNode"},"title":"Children","description":"Nested fields (object: its fields; list: each item's fields; a list without children is a list of text). At most 4 levels, 200 fields per template."}}},"TemplateSchema":{"type":"object","title":"TemplateSchema","properties":{"entity_group_id":{"type":"string","format":"uuid"},"version":{"type":"integer"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/FieldNode"}},"record_mode":{"type":"string","enum":["auto","single","list"],"title":"Record Mode","description":"What one document yields: single = exactly one record (the template is one object); list = a list of records shaped like the template; auto = the model decides. The extracted data is always an array of records."}}},"TemplateSchemaUpdate":{"type":"object","title":"TemplateSchemaUpdate","required":["base_version","fields"],"properties":{"base_version":{"type":"integer","description":"The version you loaded. A different current version → 409 (someone saved in between)."},"fields":{"type":"array","items":{"$ref":"#/components/schemas/FieldNode"}},"record_mode":{"type":"string","enum":["auto","single","list"],"title":"Record Mode","description":"What one document yields: single = exactly one record (the template is one object); list = a list of records shaped like the template; auto = the model decides. The extracted data is always an array of records."}}},"TemplateVersionSummary":{"type":"object","title":"TemplateVersionSummary","properties":{"version":{"type":"integer"},"source":{"type":"string","enum":["create","edit","restore","ai"]},"ai_run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"field_count":{"type":"integer"},"record_mode":{"type":"string","enum":["auto","single","list"],"title":"Record Mode","description":"What one document yields: single = exactly one record (the template is one object); list = a list of records shaped like the template; auto = the model decides. The extracted data is always an array of records."}}},"TemplateVersionList":{"type":"object","title":"TemplateVersionList","properties":{"entity_group_id":{"type":"string","format":"uuid"},"current_version":{"type":"integer"},"versions":{"type":"array","items":{"$ref":"#/components/schemas/TemplateVersionSummary"}}}},"TemplateVersion":{"type":"object","title":"TemplateVersion","properties":{"entity_group_id":{"type":"string","format":"uuid"},"version":{"type":"integer"},"source":{"type":"string"},"ai_run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/FieldNode"}},"record_mode":{"type":"string","enum":["auto","single","list"],"title":"Record Mode","description":"What one document yields: single = exactly one record (the template is one object); list = a list of records shaped like the template; auto = the model decides. The extracted data is always an array of records."}}},"TemplateAiProposalItem":{"type":"object","title":"TemplateAiProposalItem","properties":{"id":{"type":"string"},"op":{"type":"string","enum":["add","update","remove"]},"target_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"field":{"$ref":"#/components/schemas/FieldNode"},"before":{"anyOf":[{"$ref":"#/components/schemas/FieldNode"},{"type":"null"}]},"reason":{"type":"string"},"evidence":{"type":"array","items":{"type":"object","properties":{"source":{"type":"integer"},"file_name":{"type":"string"},"quote":{"type":"string"}}}},"found_in":{"type":"integer"},"decision":{"type":"string","enum":["accept","reject"]}}},"TemplateAiProposal":{"type":"object","title":"TemplateAiProposal","properties":{"template_name":{"type":"string"},"description":{"type":"string"},"summary":{"type":"string"},"source_count":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/TemplateAiProposalItem"}},"record_mode":{"type":"string","enum":["single","list"]},"record_mode_reason":{"type":"string"},"base_record_mode":{"anyOf":[{"type":"string","enum":["auto","single","list"]},{"type":"null"}]},"record_mode_decision":{"type":"string","enum":["accept","reject"]}}},"TemplateAiRun":{"type":"object","title":"TemplateAiRun","properties":{"id":{"type":"string","format":"uuid"},"mode":{"type":"string","enum":["generate","improve"]},"status":{"type":"string","enum":["uploading","running","ready","failed","applied","dismissed"]},"base_template_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"base_version":{"anyOf":[{"type":"integer"},{"type":"null"}]},"result_template_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"result_version":{"anyOf":[{"type":"integer"},{"type":"null"}]},"model":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"item_count":{"anyOf":[{"type":"integer"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"sources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"position":{"type":"integer"},"document_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"file_name":{"type":"string"},"content_type":{"type":"string"},"size_bytes":{"type":"integer"},"uploaded":{"type":"boolean"}}}},"proposal":{"anyOf":[{"$ref":"#/components/schemas/TemplateAiProposal"},{"type":"null"}]}}},"TemplateAiRunCreate":{"type":"object","title":"TemplateAiRunCreate","properties":{"base_template_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Template to improve; omit to generate a new one."},"document_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Documents already uploaded (their stored file is read)."},"files":{"type":"array","items":{"type":"object","required":["name","size"],"properties":{"name":{"type":"string"},"size":{"type":"integer"}}},"description":"New files: each gets an upload_url to PUT the bytes to, then call /start."}},"description":"1 to 5 sources in total."},"TemplateAiRunCreated":{"type":"object","title":"TemplateAiRunCreated","properties":{"run":{"$ref":"#/components/schemas/TemplateAiRun"},"uploads":{"type":"array","items":{"type":"object","properties":{"source_id":{"type":"string","format":"uuid"},"file_name":{"type":"string"},"content_type":{"type":"string"},"upload_url":{"type":"string"}}}}}},"TemplateAiApply":{"type":"object","title":"TemplateAiApply","required":["decisions"],"properties":{"decisions":{"type":"object","additionalProperties":{"type":"string","enum":["accept","reject"]},"description":"item id → accept | reject, plus \"record_mode\" for the proposed record mode; missing = reject."},"name":{"type":"string","description":"generate only: the new template's name (default: the proposed one)."},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"TemplateAiApplied":{"type":"object","title":"TemplateAiApplied","properties":{"run":{"$ref":"#/components/schemas/TemplateAiRun"},"template_id":{"type":"string","format":"uuid"},"version":{"type":"integer"}}}},"securitySchemes":{"OAuth2PasswordBearer":{"type":"oauth2","flows":{"password":{"scopes":{},"tokenUrl":"auth/login"}}}}}}