{"service":"agent_tools_service","version":"1.0.0","description":"Shared tools for agents and backends: a headless browser for public web pages and document conversion to PDF.","authentication":{"headers":{"X-Client-Id":"<client id>","X-Client-Secret":"<client secret>"},"alternatives":["Authorization: Basic base64(client_id:client_secret)","Authorization: Bearer client_id:client_secret"]},"tools":[{"name":"browser","description":"Headless Chromium for public web pages: rendered HTML, readable content, screenshots.","endpoints":[{"method":"POST","path":"/v1/browser/render","scope":"browser.render","content_type":"application/json","description":"Open a web page in a real browser (JavaScript runs) and return its full rendered HTML, final URL, HTTP status, title and og:image. Use it to scrape or parse a page yourself. Only public pages can be opened: private, loopback and internal addresses are refused (code blocked_address). Pages that do not finish loading in timeout_ms return what loaded, with partial: true.","returns":"JSON: url, final_url, status_code, title, og_image, html, html_bytes, truncated, partial, timing"},{"method":"POST","path":"/v1/browser/content","scope":"browser.content","content_type":"application/json","description":"Read a web page: open it in a real browser and return its main content (the article, without menus and ads) as Markdown by default. Long pages come in parts: call again with start_char = next_start_char. Only public pages can be opened: private, loopback and internal addresses are refused (code blocked_address). Pages that do not finish loading in timeout_ms return what loaded, with partial: true.","returns":"JSON: url, final_url, status_code, title, og_image, format, content, total_chars, start_char, truncated, next_start_char, partial, timing"},{"method":"POST","path":"/v1/browser/screenshot","scope":"browser.screenshot","content_type":"application/json","description":"Take a screenshot of a web page, as a phone (width <= 600) or desktop. Returns the image (X-Page-Status header has the page's HTTP status), or JSON with base64 when encoding is \"base64\". Only public pages can be opened: private, loopback and internal addresses are refused (code blocked_address). Pages that do not finish loading in timeout_ms return what loaded, with partial: true.","returns":"image/png or image/jpeg; or JSON: image_base64, mime_type, status_code, final_url, title, timing"}]},{"name":"documents","description":"Document conversion with Gotenberg: Office, HTML and Markdown to PDF, PDF merge. Requests are multipart/form-data, responses are the files.","endpoints":[{"method":"POST","path":"/v1/documents/convert/office","scope":"documents.convert_office","content_type":"multipart/form-data","description":"Convert Office and OpenDocument files (docx, xlsx, pptx, odt, rtf, txt, ...) to PDF with LibreOffice. Several files give a zip of PDFs unless merge=true.","returns":"application/pdf, or application/zip for several outputs"},{"method":"POST","path":"/v1/documents/convert/html","scope":"documents.convert_html","content_type":"multipart/form-data","description":"Render an HTML page to PDF with Chromium (no JavaScript, no network). The page must be a file named index.html; images and CSS it uses go along as more files; header.html / footer.html set page headers and footers.","returns":"application/pdf, or application/zip for several outputs"},{"method":"POST","path":"/v1/documents/convert/markdown","scope":"documents.convert_markdown","content_type":"multipart/form-data","description":"Render Markdown files to PDF through an index.html wrapper that includes them with {{ toHTML \"file.md\" }}.","returns":"application/pdf, or application/zip for several outputs"},{"method":"POST","path":"/v1/documents/merge","scope":"documents.merge","content_type":"multipart/form-data","description":"Merge PDF files into one, in the alphabetical order of their file names.","returns":"application/pdf, or application/zip for several outputs"}]}],"limits":{"max_upload_mb":500},"errors":{"format":{"error":"message","code":"stable code","retryable":"bool","retry_after_s":"seconds, when given","hint":"what to change, when given"},"codes":{"invalid_request":{"status":400,"retryable":false,"meaning":"The body or a parameter is wrong: read \"error\" and \"details\", fix the call"},"unauthorized":{"status":401,"retryable":false,"meaning":"Missing or wrong client credentials"},"forbidden_ip":{"status":403,"retryable":false,"meaning":"The calling IP address is not in this client's allowlist"},"forbidden_operation":{"status":403,"retryable":false,"meaning":"This client may not use this operation"},"blocked_address":{"status":403,"retryable":false,"meaning":"The URL points to a private, loopback or internal address: only public pages can be opened"},"not_found":{"status":404,"retryable":false,"meaning":"No such endpoint: GET /v1 lists them"},"method_not_allowed":{"status":405,"retryable":false,"meaning":"Wrong HTTP method for this endpoint"},"length_required":{"status":411,"retryable":false,"meaning":"Uploads need a Content-Length header"},"too_large":{"status":413,"retryable":false,"meaning":"The upload is over the size limit"},"unsupported_media_type":{"status":415,"retryable":false,"meaning":"Wrong Content-Type: documents take multipart/form-data, browser tools take JSON"},"page_load_failed":{"status":422,"retryable":false,"meaning":"The page did not load (DNS, TLS, connection or timeout): check the URL or try a longer timeout_ms"},"selector_not_found":{"status":422,"retryable":false,"meaning":"wait_for_selector or selector matched nothing on the page"},"content_not_found":{"status":422,"retryable":false,"meaning":"No readable main content was found: try format \"html\", a selector, or browser_render"},"conversion_failed":{"status":422,"retryable":false,"meaning":"The converter could not convert the files: check the file type and form fields"},"rate_limited":{"status":429,"retryable":true,"meaning":"Too many requests this minute for this client"},"too_many_concurrent":{"status":429,"retryable":true,"meaning":"This client already has its maximum number of requests running"},"quota_exceeded":{"status":429,"retryable":true,"meaning":"The daily quota of this client is used up"},"internal_error":{"status":500,"retryable":true,"meaning":"Unexpected error in the service"},"browser_error":{"status":502,"retryable":true,"meaning":"The browser crashed or failed while working on the page"},"converter_error":{"status":502,"retryable":true,"meaning":"The document converter failed"},"busy":{"status":503,"retryable":true,"meaning":"Every browser page or converter slot is busy and the queue is full"},"unavailable":{"status":503,"retryable":true,"meaning":"A part of the service is down (queue, database or converter)"},"timeout":{"status":504,"retryable":true,"meaning":"The job did not finish in time"}}},"discovery":{"tools":"/v1/tools","me":"/v1/me","health":"/healthz","metrics":"/metrics"}}