{"service":"ailang-parse","version":"0.9.0","base_url":"https://docparse.ailang.sunholo.com","protocol":"a2a/0.3","auth":{"schemes":[{"id":"api_key","type":"apiKey","in":"body","name":"apiKey","prefix":"dp_","description":"API key for data endpoints (parse, formats, unstructured)"},{"id":"firebase_bearer","type":"http","scheme":"bearer","issuer":"ailang-multivac-dev.firebaseapp.com","description":"Firebase ID token for device auth approval"}],"device_flow":{"request_url":"/api/v1/auth/device","poll_url":"/api/v1/auth/device/poll","approve_url":"https://www.sunholo.com/docparse/approve.html"}},"endpoints":[{"id":"parse","path":"/api/v1/parse","method":"POST","description":"Parse any document into structured content blocks. Accepts file upload (multipart/form-data), sample IDs, or GCS refs.","auth":{"required":true,"scheme":"api_key"},"quick_start":{"step_1":"Get an API key: POST /api/v1/auth/device","step_2_sample":"Parse a sample: curl -X POST $BASE/api/v1/parse -H 'Content-Type: application/json' -d '{\"sample_id\":\"sample_docx_basic\",\"outputFormat\":\"markdown\",\"apiKey\":\"dp_...\"}","step_3_upload":"Upload your own file: curl -X POST $BASE/api/v1/parse -F 'filepath=@your-file.docx' -F 'outputFormat=markdown' -F 'apiKey=dp_...'"},"file_upload":{"method":"multipart/form-data","field_name":"filepath","description":"Upload files directly using curl -F 'filepath=@file.docx'. The field name MUST be 'filepath'. All tiers can upload files within their size limits (Free: 10MB, Pro: 25MB, Business: 50MB).","example":"curl -X POST $BASE/api/v1/parse -F 'filepath=@report.docx' -F 'outputFormat=markdown' -F 'apiKey=dp_...'"},"input_schema":{"type":"object","content_types":["application/json","multipart/form-data"],"properties":{"filepath":{"type":"string","description":"File upload (multipart: -F 'filepath=@file.docx') or sample_id string (JSON). All tiers supported."},"sample_id":{"type":"string","description":"Built-in sample ID from GET /api/v1/samples (e.g. 'sample_docx_basic'). Works on all tiers."},"gcsRef":{"type":"string","description":"gs:// URI for pre-uploaded large files (Business tier only). Get upload URL via POST /api/v1/upload/url"},"outputFormat":{"type":"string","enum":["blocks","markdown","html","a2ui"],"default":"blocks"}},"oneOf":[{"required":["filepath"]},{"required":["sample_id"]}]},"output_schema":{"type":"object","properties":{"result":{"type":"string","description":"JSON-encoded parse output"},"meta":{"$ref":"#/definitions/response_meta"}}},"error_codes":["INVALID_API_KEY","QUOTA_EXCEEDED","INPUT_NOT_FOUND","UNSUPPORTED_FORMAT","FORMAT_NOT_AVAILABLE","PARSE_FAILED","INVALID_ARGUMENT","TIER_UPGRADE_REQUIRED","INVALID_GCS_REF","FORBIDDEN","GCS_DOWNLOAD_FAILED"],"cost":{"unit":"request","estimated_class":"small","quota_scope":"daily","ai_required_for":["pdf","png","jpg","gif","tiff","webp"]},"determinism":{"replayable":true,"sources_of_variance":["ai_model_version (PDF/image only)"]},"examples":[{"id":"parse_docx_blocks_basic","request":{"sample_id":"sample_docx_formatting","outputFormat":"blocks"},"expected":{"status":200,"response_shape":{"blocks":"array","metadata":"object"},"deterministic":true,"notes":"Office formats always return identical output for same input"}}]},{"id":"formats","path":"/api/v1/formats","method":"GET","description":"List all supported input, output, and generation formats","auth":{"required":false},"cost":{"unit":"none","quota_scope":"none"},"determinism":{"replayable":true,"sources_of_variance":[]}},{"id":"health","path":"/api/v1/health","method":"GET","description":"Service health, version, uptime","auth":{"required":false},"cost":{"unit":"none","quota_scope":"none"},"determinism":{"replayable":true,"sources_of_variance":["uptime_ms"]}},{"id":"unstructured","path":"/general/v0/general","method":"POST","description":"Drop-in Unstructured.io API replacement","auth":{"required":true,"scheme":"api_key"},"input_schema":{"type":"object","properties":{"path":{"type":"string"},"strategy":{"type":"string","enum":["auto","hi_res","fast"],"default":"auto"}},"required":["path"]},"cost":{"unit":"request","quota_scope":"daily"},"determinism":{"replayable":true,"sources_of_variance":[]}},{"id":"samples","path":"/api/v1/samples","method":"GET","description":"List available sample documents for testing","auth":{"required":false},"cost":{"unit":"none","quota_scope":"none"},"determinism":{"replayable":true,"sources_of_variance":[]}},{"id":"estimate","path":"/api/v1/estimate","method":"POST","description":"Estimate cost and latency before parsing — no auth required","auth":{"required":false},"input_schema":{"type":"object","properties":{"filepath":{"type":"string"},"outputFormat":{"type":"string","enum":["blocks","markdown","html","a2ui"]}},"required":["filepath"]},"cost":{"unit":"none","quota_scope":"none"},"determinism":{"replayable":true,"sources_of_variance":[]}},{"id":"pricing","path":"/api/v1/pricing","method":"GET","description":"Machine-readable pricing tiers and credit costs","auth":{"required":false},"cost":{"unit":"none","quota_scope":"none"}},{"id":"keys_usage","path":"/api/v1/keys/usage","method":"POST","description":"Usage counters and quota limits for a key","auth":{"required":true,"scheme":"api_key"},"cost":{"unit":"none","quota_scope":"none"}},{"id":"device_auth","path":"/api/v1/auth/device","method":"POST","description":"Request device authorization code (RFC 8628)","auth":{"required":false},"input_schema":{"type":"object","properties":{"label":{"type":"string","description":"Agent label for identification"},"scope":{"type":"string","default":"parse"}}},"cost":{"unit":"none","quota_scope":"none"}},{"id":"device_poll","path":"/api/v1/auth/device/poll","method":"POST","description":"Poll for device authorization approval","auth":{"required":false},"input_schema":{"type":"object","properties":{"device_code":{"type":"string"}},"required":["device_code"]},"error_codes":["AUTHORIZATION_PENDING","DEVICE_CODE_EXPIRED"],"cost":{"unit":"none","quota_scope":"none"}},{"id":"upload_url","path":"/api/v1/upload/url","method":"POST","description":"Get a pre-authenticated GCS upload URL for large files exceeding the 32MB request limit (Business tier only). For files under 32MB, use direct multipart upload: curl -F 'filepath=@file.docx' to POST /api/v1/parse instead.","auth":{"required":true,"scheme":"api_key"},"input_schema":{"type":"object","properties":{"filename":{"type":"string","description":"Original filename"},"mimeType":{"type":"string","description":"MIME type (e.g. application/pdf, image/png)"}},"required":["filename","mimeType"]},"output_schema":{"type":"object","properties":{"upload_url":{"type":"string","description":"PUT file content to this URL"},"gcs_ref":{"type":"string","description":"Pass this to POST /api/v1/parse as gcsRef"},"method":{"type":"string","enum":["PUT"]},"content_type":{"type":"string"}}},"error_codes":["INVALID_API_KEY","TIER_UPGRADE_REQUIRED","SERVICE_UNAVAILABLE","GCS_UPLOAD_INIT_FAILED"],"cost":{"unit":"none","quota_scope":"none"},"tier_required":"business"},{"id":"requests_replay","path":"/api/v1/requests/replay","method":"POST","description":"Replay a previous parse request by request_id. Requires authentication — the authenticated user must own the original request.","auth":{"required":true,"note":"API key or Firebase JWT required; ownership verified"},"input_schema":{"type":"object","properties":{"request_id":{"type":"string","description":"The request_id from a previous parse response meta"}},"required":["request_id"]},"cost":{"unit":"none","quota_scope":"none"},"determinism":{"replayable":true,"sources_of_variance":[]}},{"id":"requests_history","path":"/api/v1/requests/history","method":"POST","description":"List parse history for a user. Returns recent parse requests with metadata.","auth":{"required":true,"scheme":"api_key"},"cost":{"unit":"none","quota_scope":"none"},"determinism":{"replayable":false,"sources_of_variance":["new_requests_since_last_call"]}}],"definitions":{"response_meta":{"type":"object","properties":{"request_id":{"type":"string","description":"Unique request identifier for replay/audit"},"quota_used":{"type":"integer"},"quota_remaining":{"type":"integer"},"replayable":{"type":"boolean"},"sample_id":{"type":"string","description":"If request used a sample, its ID"}}},"error_response":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["INVALID_API_KEY","QUOTA_EXCEEDED","INPUT_NOT_FOUND","UNSUPPORTED_FORMAT","PARSE_FAILED","INVALID_ARGUMENT","INTERNAL_ERROR","AI_UNAVAILABLE","AUTHORIZATION_PENDING","DEVICE_CODE_EXPIRED"]},"message":{"type":"string"},"retryable":{"type":"boolean"},"suggested_fix":{"type":"string"}},"required":["code","message","retryable"]}}}},"tool_definitions":{"mcp":"/mcp/","a2a":"/.well-known/agent.json","openapi":"/api/_meta/openapi.json"}}