{ "openapi": "3.1.0", "info": { "title": "agentops.tools API", "version": "1.0.0", "summary": "Free tools for AI agents, over REST and MCP.", "description": "Every tool is available at POST /v1/{name} with a JSON body, or GET /v1/{name} with query parameters. Responses use one envelope shape. Check `ok` first. Anonymous limit: 30 units per minute and 1,000 per day per client." }, "servers": [ { "url": "https://agentops.tools" } ], "paths": { "/v1/time.now": { "get": { "operationId": "time_now_get", "summary": "Current date and time in any IANA timezone, with UTC offset and daylight-saving flag.", "description": "Use whenever you need today's date or the current time, because models do not know it. Pass an IANA timezone such as Europe/Berlin. Defaults to UTC.", "tags": [ "data" ], "parameters": [ { "name": "timezone", "in": "query", "required": false, "description": "IANA timezone, e.g. America/New_York.", "schema": { "default": "UTC", "type": "string", "minLength": 1, "maxLength": 64 } } ], "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 }, "post": { "operationId": "time_now_post", "summary": "Current date and time in any IANA timezone, with UTC offset and daylight-saving flag.", "description": "Use whenever you need today's date or the current time, because models do not know it. Pass an IANA timezone such as Europe/Berlin. Defaults to UTC.", "tags": [ "data" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "timezone": { "default": "UTC", "description": "IANA timezone, e.g. America/New_York.", "type": "string", "minLength": 1, "maxLength": 64 } } } } } }, "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 } }, "/v1/geo.resolve": { "get": { "operationId": "geo_resolve_get", "summary": "Turns a place name into coordinates, country and timezone.", "description": "Use when the user names a place and you need its coordinates or to pick between candidates. Weather, air quality, routing and nearby search accept a place name directly, so you rarely need this on its own.", "tags": [ "geo" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Place name, e.g. 'Kyoto' or 'Paris, France'.", "schema": { "type": "string", "minLength": 2, "maxLength": 200 } }, { "name": "count", "in": "query", "required": false, "description": "How many candidates to return.", "schema": { "default": 5, "type": "integer", "minimum": 1, "maximum": 10 } } ], "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 }, "post": { "operationId": "geo_resolve_post", "summary": "Turns a place name into coordinates, country and timezone.", "description": "Use when the user names a place and you need its coordinates or to pick between candidates. Weather, air quality, routing and nearby search accept a place name directly, so you rarely need this on its own.", "tags": [ "geo" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "query": { "type": "string", "minLength": 2, "maxLength": 200, "description": "Place name, e.g. 'Kyoto' or 'Paris, France'." }, "count": { "default": 5, "description": "How many candidates to return.", "type": "integer", "minimum": 1, "maximum": 10 } }, "required": [ "query" ] } } } }, "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 } }, "/v1/weather.current": { "get": { "operationId": "weather_current_get", "summary": "Current temperature, feels-like, humidity, wind and conditions for a place.", "description": "Use for questions about the weather right now at a place. Use weather.forecast for future days and weather.alerts for warnings.", "tags": [ "geo" ], "parameters": [ { "name": "location", "in": "query", "required": false, "description": "Place name such as 'Tokyo' or 'Austin, TX'. Use instead of latitude and longitude.", "schema": { "type": "string", "minLength": 2, "maxLength": 200 } }, { "name": "latitude", "in": "query", "required": false, "description": "Decimal latitude, -90 to 90.", "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, { "name": "longitude", "in": "query", "required": false, "description": "Decimal longitude, -180 to 180.", "schema": { "type": "number", "minimum": -180, "maximum": 180 } }, { "name": "units", "in": "query", "required": false, "description": "metric (°C, km/h, mm) or imperial (°F, mph, in).", "schema": { "default": "metric", "type": "string", "enum": [ "metric", "imperial" ] } } ], "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 }, "post": { "operationId": "weather_current_post", "summary": "Current temperature, feels-like, humidity, wind and conditions for a place.", "description": "Use for questions about the weather right now at a place. Use weather.forecast for future days and weather.alerts for warnings.", "tags": [ "geo" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "location": { "description": "Place name such as 'Tokyo' or 'Austin, TX'. Use instead of latitude and longitude.", "type": "string", "minLength": 2, "maxLength": 200 }, "latitude": { "description": "Decimal latitude, -90 to 90.", "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "description": "Decimal longitude, -180 to 180.", "type": "number", "minimum": -180, "maximum": 180 }, "units": { "default": "metric", "description": "metric (°C, km/h, mm) or imperial (°F, mph, in).", "type": "string", "enum": [ "metric", "imperial" ] } } } } } }, "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 } }, "/v1/weather.forecast": { "get": { "operationId": "weather_forecast_get", "summary": "Daily forecast up to 16 days: highs, lows, rain chance, wind, sunrise and sunset.", "description": "Use for questions about future weather at a place, such as 'will it rain on Friday' or 'what should I pack for next week'. Use weather.current for right now.", "tags": [ "geo" ], "parameters": [ { "name": "location", "in": "query", "required": false, "description": "Place name such as 'Tokyo' or 'Austin, TX'. Use instead of latitude and longitude.", "schema": { "type": "string", "minLength": 2, "maxLength": 200 } }, { "name": "latitude", "in": "query", "required": false, "description": "Decimal latitude, -90 to 90.", "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, { "name": "longitude", "in": "query", "required": false, "description": "Decimal longitude, -180 to 180.", "schema": { "type": "number", "minimum": -180, "maximum": 180 } }, { "name": "days", "in": "query", "required": false, "description": "Number of days, 1 to 16.", "schema": { "default": 7, "type": "integer", "minimum": 1, "maximum": 16 } }, { "name": "units", "in": "query", "required": false, "description": "metric (°C, km/h, mm) or imperial (°F, mph, in).", "schema": { "default": "metric", "type": "string", "enum": [ "metric", "imperial" ] } } ], "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 }, "post": { "operationId": "weather_forecast_post", "summary": "Daily forecast up to 16 days: highs, lows, rain chance, wind, sunrise and sunset.", "description": "Use for questions about future weather at a place, such as 'will it rain on Friday' or 'what should I pack for next week'. Use weather.current for right now.", "tags": [ "geo" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "location": { "description": "Place name such as 'Tokyo' or 'Austin, TX'. Use instead of latitude and longitude.", "type": "string", "minLength": 2, "maxLength": 200 }, "latitude": { "description": "Decimal latitude, -90 to 90.", "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "description": "Decimal longitude, -180 to 180.", "type": "number", "minimum": -180, "maximum": 180 }, "days": { "default": 7, "description": "Number of days, 1 to 16.", "type": "integer", "minimum": 1, "maximum": 16 }, "units": { "default": "metric", "description": "metric (°C, km/h, mm) or imperial (°F, mph, in).", "type": "string", "enum": [ "metric", "imperial" ] } } } } } }, "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 } }, "/v1/air.quality": { "get": { "operationId": "air_quality_get", "summary": "Current US and European AQI with PM2.5, PM10, ozone and NO2 readings for a place.", "description": "Use for questions about air pollution, or whether it is safe to exercise outdoors at a place. Returns US AQI (0-500) and European AQI.", "tags": [ "geo" ], "parameters": [ { "name": "location", "in": "query", "required": false, "description": "Place name such as 'Tokyo' or 'Austin, TX'. Use instead of latitude and longitude.", "schema": { "type": "string", "minLength": 2, "maxLength": 200 } }, { "name": "latitude", "in": "query", "required": false, "description": "Decimal latitude, -90 to 90.", "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, { "name": "longitude", "in": "query", "required": false, "description": "Decimal longitude, -180 to 180.", "schema": { "type": "number", "minimum": -180, "maximum": 180 } } ], "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 }, "post": { "operationId": "air_quality_post", "summary": "Current US and European AQI with PM2.5, PM10, ozone and NO2 readings for a place.", "description": "Use for questions about air pollution, or whether it is safe to exercise outdoors at a place. Returns US AQI (0-500) and European AQI.", "tags": [ "geo" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "location": { "description": "Place name such as 'Tokyo' or 'Austin, TX'. Use instead of latitude and longitude.", "type": "string", "minLength": 2, "maxLength": 200 }, "latitude": { "description": "Decimal latitude, -90 to 90.", "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "description": "Decimal longitude, -180 to 180.", "type": "number", "minimum": -180, "maximum": 180 } } } } } }, "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 } }, "/v1/weather.alerts": { "get": { "operationId": "weather_alerts_get", "summary": "Active National Weather Service warnings, watches and advisories for a US point.", "description": "Use when the user asks about active warnings, storms or hazards at a location. Coverage is the United States and territories only. Other locations return an empty list with a coverage note.", "tags": [ "geo" ], "parameters": [ { "name": "location", "in": "query", "required": false, "description": "Place name such as 'Tokyo' or 'Austin, TX'. Use instead of latitude and longitude.", "schema": { "type": "string", "minLength": 2, "maxLength": 200 } }, { "name": "latitude", "in": "query", "required": false, "description": "Decimal latitude, -90 to 90.", "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, { "name": "longitude", "in": "query", "required": false, "description": "Decimal longitude, -180 to 180.", "schema": { "type": "number", "minimum": -180, "maximum": 180 } } ], "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 }, "post": { "operationId": "weather_alerts_post", "summary": "Active National Weather Service warnings, watches and advisories for a US point.", "description": "Use when the user asks about active warnings, storms or hazards at a location. Coverage is the United States and territories only. Other locations return an empty list with a coverage note.", "tags": [ "geo" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "location": { "description": "Place name such as 'Tokyo' or 'Austin, TX'. Use instead of latitude and longitude.", "type": "string", "minLength": 2, "maxLength": 200 }, "latitude": { "description": "Decimal latitude, -90 to 90.", "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "description": "Decimal longitude, -180 to 180.", "type": "number", "minimum": -180, "maximum": 180 } } } } } }, "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 } }, "/v1/fx.convert": { "get": { "operationId": "fx_convert_get", "summary": "Converts an amount between two currencies at the ECB reference rate, latest or historical.", "description": "Use for currency conversion. ECB reference rates are published on business days, so weekend and holiday requests use the last published rate. Not a trading or exact bank quote.", "tags": [ "data" ], "parameters": [ { "name": "amount", "in": "query", "required": true, "description": "Amount in the source currency.", "schema": { "type": "number", "minimum": 0, "maximum": 1000000000000 } }, { "name": "from", "in": "query", "required": true, "description": "ISO 4217 code, e.g. USD.", "schema": { "type": "string", "pattern": "^[A-Za-z]{3}$" } }, { "name": "to", "in": "query", "required": true, "description": "ISO 4217 code, e.g. EUR.", "schema": { "type": "string", "pattern": "^[A-Za-z]{3}$" } }, { "name": "date", "in": "query", "required": false, "description": "Historical date YYYY-MM-DD, from 1999-01-04. Omit for the latest rate.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } ], "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 }, "post": { "operationId": "fx_convert_post", "summary": "Converts an amount between two currencies at the ECB reference rate, latest or historical.", "description": "Use for currency conversion. ECB reference rates are published on business days, so weekend and holiday requests use the last published rate. Not a trading or exact bank quote.", "tags": [ "data" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "amount": { "type": "number", "minimum": 0, "maximum": 1000000000000, "description": "Amount in the source currency." }, "from": { "type": "string", "pattern": "^[A-Za-z]{3}$", "description": "ISO 4217 code, e.g. USD." }, "to": { "type": "string", "pattern": "^[A-Za-z]{3}$", "description": "ISO 4217 code, e.g. EUR." }, "date": { "description": "Historical date YYYY-MM-DD, from 1999-01-04. Omit for the latest rate.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "amount", "from", "to" ] } } } }, "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 } }, "/v1/crypto.price": { "get": { "operationId": "crypto_price_get", "summary": "Price, 24-hour change and market cap for up to 10 coins by CoinGecko id.", "description": "Use for current cryptocurrency prices. Pass CoinGecko ids such as bitcoin or ethereum, not ticker symbols, which are ambiguous. Prices are indicative, not trading quotes.", "tags": [ "data" ], "parameters": [ { "name": "ids", "in": "query", "required": true, "description": "CoinGecko ids, lowercase, e.g. ['bitcoin', 'ethereum'].", "schema": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9-]{2,64}$" } }, "style": "form", "explode": false }, { "name": "vs", "in": "query", "required": false, "description": "Quote currency, lowercase ISO code such as usd or eur.", "schema": { "default": "usd", "type": "string", "pattern": "^[a-z]{3}$" } } ], "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 }, "post": { "operationId": "crypto_price_post", "summary": "Price, 24-hour change and market cap for up to 10 coins by CoinGecko id.", "description": "Use for current cryptocurrency prices. Pass CoinGecko ids such as bitcoin or ethereum, not ticker symbols, which are ambiguous. Prices are indicative, not trading quotes.", "tags": [ "data" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9-]{2,64}$" }, "description": "CoinGecko ids, lowercase, e.g. ['bitcoin', 'ethereum']." }, "vs": { "default": "usd", "description": "Quote currency, lowercase ISO code such as usd or eur.", "type": "string", "pattern": "^[a-z]{3}$" } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 } }, "/v1/holidays.list": { "get": { "operationId": "holidays_list_get", "summary": "Public and bank holidays for a country or state in a year, plus a business-day check.", "description": "Use for holiday calendars, or to check whether a date is a business day, for example when counting working days toward a deadline. Computed offline, so it is fast and always available.", "tags": [ "data" ], "parameters": [ { "name": "country", "in": "query", "required": true, "description": "ISO 3166-1 alpha-2 code, e.g. US, DE, JP.", "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" } }, { "name": "subdivision", "in": "query", "required": false, "description": "State or region code, e.g. CA for California in the US.", "schema": { "type": "string", "minLength": 1, "maxLength": 10 } }, { "name": "year", "in": "query", "required": false, "description": "Year. Defaults to the current UTC year.", "schema": { "type": "integer", "minimum": 1900, "maximum": 2100 } }, { "name": "include_observances", "in": "query", "required": false, "description": "Also include observances and optional days, not only public and bank holidays.", "schema": { "default": false, "type": "boolean" } }, { "name": "on", "in": "query", "required": false, "description": "Date YYYY-MM-DD to check for business-day status.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } ], "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 }, "post": { "operationId": "holidays_list_post", "summary": "Public and bank holidays for a country or state in a year, plus a business-day check.", "description": "Use for holiday calendars, or to check whether a date is a business day, for example when counting working days toward a deadline. Computed offline, so it is fast and always available.", "tags": [ "data" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "country": { "type": "string", "pattern": "^[A-Za-z]{2}$", "description": "ISO 3166-1 alpha-2 code, e.g. US, DE, JP." }, "subdivision": { "description": "State or region code, e.g. CA for California in the US.", "type": "string", "minLength": 1, "maxLength": 10 }, "year": { "description": "Year. Defaults to the current UTC year.", "type": "integer", "minimum": 1900, "maximum": 2100 }, "include_observances": { "default": false, "description": "Also include observances and optional days, not only public and bank holidays.", "type": "boolean" }, "on": { "description": "Date YYYY-MM-DD to check for business-day status.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "country" ] } } } }, "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 } }, "/v1/tokens.count": { "get": { "operationId": "tokens_count_get", "summary": "Exact token count for the OpenAI o200k_base and cl100k_base encodings, computed offline.", "description": "Use to estimate prompt size or cost for OpenAI models. Counts are exact for the named encoding. Anthropic and Google tokenizers differ and are not supported yet.", "tags": [ "data" ], "parameters": [ { "name": "text", "in": "query", "required": true, "description": "Text to tokenize, up to 200,000 characters.", "schema": { "type": "string", "minLength": 1, "maxLength": 200000 } }, { "name": "encoding", "in": "query", "required": false, "description": "o200k_base for GPT-4o and later. cl100k_base for GPT-4 and GPT-3.5.", "schema": { "default": "o200k_base", "type": "string", "enum": [ "o200k_base", "cl100k_base" ] } } ], "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 }, "post": { "operationId": "tokens_count_post", "summary": "Exact token count for the OpenAI o200k_base and cl100k_base encodings, computed offline.", "description": "Use to estimate prompt size or cost for OpenAI models. Counts are exact for the named encoding. Anthropic and Google tokenizers differ and are not supported yet.", "tags": [ "data" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 200000, "description": "Text to tokenize, up to 200,000 characters." }, "encoding": { "default": "o200k_base", "description": "o200k_base for GPT-4o and later. cl100k_base for GPT-4 and GPT-3.5.", "type": "string", "enum": [ "o200k_base", "cl100k_base" ] } }, "required": [ "text" ] } } } }, "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 } }, "/v1/web.extract": { "get": { "operationId": "web_extract_get", "summary": "Main text, title, author and publish date from a public web page, as clean plain text.", "description": "Use to read the content of an article, blog post or documentation page. Returns plain text, not HTML. Pages that need JavaScript to render may return EMPTY_CONTENT; web.screenshot can show those.", "tags": [ "web" ], "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Absolute http or https URL of the page.", "schema": { "type": "string", "maxLength": 2048, "format": "uri" } }, { "name": "max_chars", "in": "query", "required": false, "description": "Maximum characters of text to return.", "schema": { "default": 20000, "type": "integer", "minimum": 500, "maximum": 100000 } } ], "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 }, "post": { "operationId": "web_extract_post", "summary": "Main text, title, author and publish date from a public web page, as clean plain text.", "description": "Use to read the content of an article, blog post or documentation page. Returns plain text, not HTML. Pages that need JavaScript to render may return EMPTY_CONTENT; web.screenshot can show those.", "tags": [ "web" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute http or https URL of the page." }, "max_chars": { "default": 20000, "description": "Maximum characters of text to return.", "type": "integer", "minimum": 500, "maximum": 100000 } }, "required": [ "url" ] } } } }, "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 } }, "/v1/web.archive": { "get": { "operationId": "web_archive_get", "summary": "Closest Internet Archive snapshot of a URL, latest or near a given date.", "description": "Use when a link is dead or the user wants a page as it was on a date. Returns the snapshot closest to the timestamp, not every capture.", "tags": [ "web" ], "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 2048, "format": "uri" } }, { "name": "timestamp", "in": "query", "required": false, "description": "Target date, YYYY, YYYY-MM or YYYY-MM-DD. Omit for the latest snapshot.", "schema": { "type": "string", "pattern": "^\\d{4}(-?\\d{2}(-?\\d{2})?)?$" } } ], "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 }, "post": { "operationId": "web_archive_post", "summary": "Closest Internet Archive snapshot of a URL, latest or near a given date.", "description": "Use when a link is dead or the user wants a page as it was on a date. Returns the snapshot closest to the timestamp, not every capture.", "tags": [ "web" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "timestamp": { "description": "Target date, YYYY, YYYY-MM or YYYY-MM-DD. Omit for the latest snapshot.", "type": "string", "pattern": "^\\d{4}(-?\\d{2}(-?\\d{2})?)?$" } }, "required": [ "url" ] } } } }, "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 } }, "/v1/feed.read": { "get": { "operationId": "feed_read_get", "summary": "Latest items from any RSS or Atom feed: title, link, published time and summary.", "description": "Use to see recent posts from a blog, news site or release channel. Stateless: each call returns the newest items; it does not notify on new ones.", "tags": [ "web" ], "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Feed URL (RSS 2.0 or Atom).", "schema": { "type": "string", "maxLength": 2048, "format": "uri" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum items to return.", "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 }, "post": { "operationId": "feed_read_post", "summary": "Latest items from any RSS or Atom feed: title, link, published time and summary.", "description": "Use to see recent posts from a blog, news site or release channel. Stateless: each call returns the newest items; it does not notify on new ones.", "tags": [ "web" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Feed URL (RSS 2.0 or Atom)." }, "limit": { "default": 10, "description": "Maximum items to return.", "type": "integer", "minimum": 1, "maximum": 50 } }, "required": [ "url" ] } } } }, "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 } }, "/v1/site.status": { "get": { "operationId": "site_status_get", "summary": "Is a URL up? HTTP status, redirect target, response time and a failure class, for up to 20 URLs.", "description": "Use to check whether a site is reachable from the public internet, or to diagnose why a link fails. Reports the first response without following redirects. Results are not cached.", "tags": [ "net" ], "parameters": [ { "name": "urls", "in": "query", "required": true, "description": "Up to 20 absolute http or https URLs.", "schema": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 2048, "format": "uri" } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 }, "post": { "operationId": "site_status_post", "summary": "Is a URL up? HTTP status, redirect target, response time and a failure class, for up to 20 URLs.", "description": "Use to check whether a site is reachable from the public internet, or to diagnose why a link fails. Reports the first response without following redirects. Results are not cached.", "tags": [ "net" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "urls": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 2048, "format": "uri" }, "description": "Up to 20 absolute http or https URLs." } }, "required": [ "urls" ] } } } }, "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 } }, "/v1/dns.lookup": { "get": { "operationId": "dns_lookup_get", "summary": "A, AAAA, MX, TXT, NS, CNAME and CAA records for a domain, with SPF and DMARC parsed out.", "description": "Use to check where a domain points, which mail servers it uses, or whether SPF and DMARC are set. Answers come from a public recursive resolver, so changes may take time to show.", "tags": [ "net" ], "parameters": [ { "name": "name", "in": "query", "required": true, "description": "Domain name, e.g. example.com.", "schema": { "type": "string", "minLength": 3, "maxLength": 253, "pattern": "^[A-Za-z0-9._-]+$" } }, { "name": "types", "in": "query", "required": false, "description": "Record types to fetch.", "schema": { "default": [ "A", "AAAA", "MX", "TXT", "NS" ], "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "string", "enum": [ "A", "AAAA", "MX", "TXT", "NS", "CNAME", "CAA" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 }, "post": { "operationId": "dns_lookup_post", "summary": "A, AAAA, MX, TXT, NS, CNAME and CAA records for a domain, with SPF and DMARC parsed out.", "description": "Use to check where a domain points, which mail servers it uses, or whether SPF and DMARC are set. Answers come from a public recursive resolver, so changes may take time to show.", "tags": [ "net" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 3, "maxLength": 253, "pattern": "^[A-Za-z0-9._-]+$", "description": "Domain name, e.g. example.com." }, "types": { "default": [ "A", "AAAA", "MX", "TXT", "NS" ], "description": "Record types to fetch.", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "string", "enum": [ "A", "AAAA", "MX", "TXT", "NS", "CNAME", "CAA" ] } } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 } }, "/v1/domain.whois": { "get": { "operationId": "domain_whois_get", "summary": "Registrar, creation and expiry dates, status flags and nameservers from RDAP.", "description": "Use for questions about who registered a domain, when it expires, or which nameservers it uses. Uses RDAP, the modern replacement for WHOIS. Some registries redact contact details, which is expected.", "tags": [ "net" ], "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Registered domain, e.g. example.com.", "schema": { "type": "string", "pattern": "^(?=.{4,253}$)([a-z0-9-]{1,63}\\.)+[a-z]{2,63}$" } } ], "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 }, "post": { "operationId": "domain_whois_post", "summary": "Registrar, creation and expiry dates, status flags and nameservers from RDAP.", "description": "Use for questions about who registered a domain, when it expires, or which nameservers it uses. Uses RDAP, the modern replacement for WHOIS. Some registries redact contact details, which is expected.", "tags": [ "net" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "domain": { "type": "string", "pattern": "^(?=.{4,253}$)([a-z0-9-]{1,63}\\.)+[a-z]{2,63}$", "description": "Registered domain, e.g. example.com." } }, "required": [ "domain" ] } } } }, "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 } }, "/v1/email.check": { "get": { "operationId": "email_check_get", "summary": "Syntax, mail-server (MX) presence, disposable-domain and role-account checks for an address.", "description": "Use to screen addresses before sending or storing them: is the syntax valid, does the domain accept mail, is it a throwaway provider. It does not contact the mailbox, so it cannot confirm that the person exists.", "tags": [ "net" ], "parameters": [ { "name": "email", "in": "query", "required": true, "description": "Email address to check.", "schema": { "type": "string", "minLength": 3, "maxLength": 320 } } ], "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 }, "post": { "operationId": "email_check_post", "summary": "Syntax, mail-server (MX) presence, disposable-domain and role-account checks for an address.", "description": "Use to screen addresses before sending or storing them: is the syntax valid, does the domain accept mail, is it a throwaway provider. It does not contact the mailbox, so it cannot confirm that the person exists.", "tags": [ "net" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "email": { "type": "string", "minLength": 3, "maxLength": 320, "description": "Email address to check." } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 } }, "/v1/tls.inspect": { "get": { "operationId": "tls_inspect_get", "summary": "Certificate chain, expiry, cipher and TLS version for a host, seen from our network.", "description": "Use to check whether a site's certificate is valid, who issued it, when it expires, or what TLS version and cipher it negotiates. Sees what our servers see, not the agent's own network.", "tags": [ "net" ], "parameters": [ { "name": "host", "in": "query", "required": true, "description": "Hostname, e.g. example.com. IP literals are rejected.", "schema": { "type": "string", "minLength": 1, "maxLength": 253 } }, { "name": "port", "in": "query", "required": false, "schema": { "default": 443, "type": "integer", "minimum": 1, "maximum": 65535 } } ], "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 }, "post": { "operationId": "tls_inspect_post", "summary": "Certificate chain, expiry, cipher and TLS version for a host, seen from our network.", "description": "Use to check whether a site's certificate is valid, who issued it, when it expires, or what TLS version and cipher it negotiates. Sees what our servers see, not the agent's own network.", "tags": [ "net" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "host": { "type": "string", "minLength": 1, "maxLength": 253, "description": "Hostname, e.g. example.com. IP literals are rejected." }, "port": { "default": 443, "type": "integer", "minimum": 1, "maximum": 65535 } }, "required": [ "host" ] } } } }, "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 } }, "/v1/route.plan": { "get": { "operationId": "route_plan_get", "summary": "Driving distance, duration and turn-by-turn steps through two to ten stops.", "description": "Use for drive distance and time between places, or a multi-stop road trip. Gives road-network estimates without live traffic. Walking and cycling are not offered yet.", "tags": [ "geo" ], "parameters": [ { "name": "stops", "in": "query", "required": true, "description": "Ordered stops. Each is {location} or {latitude, longitude}.", "schema": { "minItems": 2, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "location": { "description": "Place name such as 'Tokyo' or 'Austin, TX'. Use instead of latitude and longitude.", "type": "string", "minLength": 2, "maxLength": 200 }, "latitude": { "description": "Decimal latitude, -90 to 90.", "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "description": "Decimal longitude, -180 to 180.", "type": "number", "minimum": -180, "maximum": 180 } } } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 2 }, "post": { "operationId": "route_plan_post", "summary": "Driving distance, duration and turn-by-turn steps through two to ten stops.", "description": "Use for drive distance and time between places, or a multi-stop road trip. Gives road-network estimates without live traffic. Walking and cycling are not offered yet.", "tags": [ "geo" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "stops": { "minItems": 2, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "location": { "description": "Place name such as 'Tokyo' or 'Austin, TX'. Use instead of latitude and longitude.", "type": "string", "minLength": 2, "maxLength": 200 }, "latitude": { "description": "Decimal latitude, -90 to 90.", "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "description": "Decimal longitude, -180 to 180.", "type": "number", "minimum": -180, "maximum": 180 } } }, "description": "Ordered stops. Each is {location} or {latitude, longitude}." } }, "required": [ "stops" ] } } } }, "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 2 } }, "/v1/places.nearby": { "get": { "operationId": "places_nearby_get", "summary": "Named restaurants, cafés, pharmacies, fuel, ATMs and more within a radius, nearest first.", "description": "Use to find named businesses or amenities near a location. Results come from OpenStreetMap, so coverage varies by area, and opening hours are as mapped by volunteers.", "tags": [ "geo" ], "parameters": [ { "name": "location", "in": "query", "required": false, "description": "Place name such as 'Tokyo' or 'Austin, TX'. Use instead of latitude and longitude.", "schema": { "type": "string", "minLength": 2, "maxLength": 200 } }, { "name": "latitude", "in": "query", "required": false, "description": "Decimal latitude, -90 to 90.", "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, { "name": "longitude", "in": "query", "required": false, "description": "Decimal longitude, -180 to 180.", "schema": { "type": "number", "minimum": -180, "maximum": 180 } }, { "name": "category", "in": "query", "required": true, "description": "Kind of place to search for.", "schema": { "type": "string", "enum": [ "restaurant", "cafe", "pharmacy", "hospital", "atm", "fuel", "library", "supermarket", "park" ] } }, { "name": "radius_m", "in": "query", "required": false, "description": "Search radius in metres.", "schema": { "default": 1000, "type": "integer", "minimum": 100, "maximum": 5000 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum places to return.", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 2 }, "post": { "operationId": "places_nearby_post", "summary": "Named restaurants, cafés, pharmacies, fuel, ATMs and more within a radius, nearest first.", "description": "Use to find named businesses or amenities near a location. Results come from OpenStreetMap, so coverage varies by area, and opening hours are as mapped by volunteers.", "tags": [ "geo" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "location": { "description": "Place name such as 'Tokyo' or 'Austin, TX'. Use instead of latitude and longitude.", "type": "string", "minLength": 2, "maxLength": 200 }, "latitude": { "description": "Decimal latitude, -90 to 90.", "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "description": "Decimal longitude, -180 to 180.", "type": "number", "minimum": -180, "maximum": 180 }, "category": { "type": "string", "enum": [ "restaurant", "cafe", "pharmacy", "hospital", "atm", "fuel", "library", "supermarket", "park" ], "description": "Kind of place to search for." }, "radius_m": { "default": 1000, "description": "Search radius in metres.", "type": "integer", "minimum": 100, "maximum": 5000 }, "limit": { "default": 20, "description": "Maximum places to return.", "type": "integer", "minimum": 1, "maximum": 50 } }, "required": [ "category" ] } } } }, "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 2 } }, "/v1/ip.geolocate": { "get": { "operationId": "ip_geolocate_get", "summary": "Country, city and coordinates for a public IP address, from an offline database.", "description": "Use to place an IP address on the map, for example to localise content or annotate logs. City precision is approximate; private addresses are rejected.", "tags": [ "geo" ], "parameters": [ { "name": "ip", "in": "query", "required": true, "description": "IPv4 or IPv6 address.", "schema": { "type": "string", "minLength": 3, "maxLength": 64 } } ], "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 }, "post": { "operationId": "ip_geolocate_post", "summary": "Country, city and coordinates for a public IP address, from an offline database.", "description": "Use to place an IP address on the map, for example to localise content or annotate logs. City precision is approximate; private addresses are rejected.", "tags": [ "geo" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ip": { "type": "string", "minLength": 3, "maxLength": 64, "description": "IPv4 or IPv6 address." } }, "required": [ "ip" ] } } } }, "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 } }, "/v1/food.barcode": { "get": { "operationId": "food_barcode_get", "summary": "Name, brand, quantity, categories, Nutri-Score and ingredients for a food barcode (EAN/UPC).", "description": "Use to identify a packaged food product from its barcode. Food only: Open Food Facts does not carry prices or non-food items.", "tags": [ "data" ], "parameters": [ { "name": "barcode", "in": "query", "required": true, "description": "EAN-8, UPC-A, EAN-13 or GTIN-14 digits, no spaces.", "schema": { "type": "string", "pattern": "^\\d{8,14}$" } } ], "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 }, "post": { "operationId": "food_barcode_post", "summary": "Name, brand, quantity, categories, Nutri-Score and ingredients for a food barcode (EAN/UPC).", "description": "Use to identify a packaged food product from its barcode. Food only: Open Food Facts does not carry prices or non-food items.", "tags": [ "data" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "barcode": { "type": "string", "pattern": "^\\d{8,14}$", "description": "EAN-8, UPC-A, EAN-13 or GTIN-14 digits, no spaces." } }, "required": [ "barcode" ] } } } }, "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 } }, "/v1/qr.generate": { "get": { "operationId": "qr_generate_get", "summary": "QR code as PNG (base64) or SVG for any text or URL up to 2,000 characters.", "description": "Use when the user needs a QR code for a link, Wi-Fi string, contact or any text. Output is an image the user can save or print.", "tags": [ "media" ], "parameters": [ { "name": "text", "in": "query", "required": true, "description": "Content to encode.", "schema": { "type": "string", "minLength": 1, "maxLength": 2000 } }, { "name": "format", "in": "query", "required": false, "schema": { "default": "png", "type": "string", "enum": [ "png", "svg" ] } }, { "name": "size_px", "in": "query", "required": false, "description": "Approximate PNG side length in pixels.", "schema": { "default": 256, "type": "integer", "minimum": 64, "maximum": 1024 } }, { "name": "error_correction", "in": "query", "required": false, "description": "L recovers ~7% damage, M ~15%, Q ~25%, H ~30%.", "schema": { "default": "M", "type": "string", "enum": [ "L", "M", "Q", "H" ] } }, { "name": "margin", "in": "query", "required": false, "description": "Quiet-zone width in modules.", "schema": { "default": 4, "type": "integer", "minimum": 0, "maximum": 10 } } ], "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 }, "post": { "operationId": "qr_generate_post", "summary": "QR code as PNG (base64) or SVG for any text or URL up to 2,000 characters.", "description": "Use when the user needs a QR code for a link, Wi-Fi string, contact or any text. Output is an image the user can save or print.", "tags": [ "media" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Content to encode." }, "format": { "default": "png", "type": "string", "enum": [ "png", "svg" ] }, "size_px": { "default": 256, "description": "Approximate PNG side length in pixels.", "type": "integer", "minimum": 64, "maximum": 1024 }, "error_correction": { "default": "M", "description": "L recovers ~7% damage, M ~15%, Q ~25%, H ~30%.", "type": "string", "enum": [ "L", "M", "Q", "H" ] }, "margin": { "default": 4, "description": "Quiet-zone width in modules.", "type": "integer", "minimum": 0, "maximum": 10 } }, "required": [ "text" ] } } } }, "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 } }, "/v1/qr.decode": { "get": { "operationId": "qr_decode_get", "summary": "Reads the QR code in a PNG or JPEG image, given as a URL or base64.", "description": "Use to read a QR code from a screenshot or photo. Only QR codes are decoded; 1D barcodes are not supported in this version. Images over 12 megapixels are rejected.", "tags": [ "media" ], "parameters": [ { "name": "url", "in": "query", "required": false, "description": "Absolute http or https URL of the file. Use instead of base64.", "schema": { "type": "string", "maxLength": 2048, "format": "uri" } }, { "name": "base64", "in": "query", "required": false, "description": "Base64-encoded file bytes, up to 10 MB once decoded. Use instead of url.", "schema": { "type": "string", "maxLength": 14000000 } } ], "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 }, "post": { "operationId": "qr_decode_post", "summary": "Reads the QR code in a PNG or JPEG image, given as a URL or base64.", "description": "Use to read a QR code from a screenshot or photo. Only QR codes are decoded; 1D barcodes are not supported in this version. Images over 12 megapixels are rejected.", "tags": [ "media" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "description": "Absolute http or https URL of the file. Use instead of base64.", "type": "string", "maxLength": 2048, "format": "uri" }, "base64": { "description": "Base64-encoded file bytes, up to 10 MB once decoded. Use instead of url.", "type": "string", "maxLength": 14000000 } } } } } }, "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 } }, "/v1/image.transform": { "get": { "operationId": "image_transform_get", "summary": "Resize an image and convert it to JPEG, PNG or WebP; metadata is stripped.", "description": "Use to make an image a particular size or format, for example a thumbnail or a WebP for the web. Output up to 1 MB is returned inline as base64.", "tags": [ "media" ], "parameters": [ { "name": "url", "in": "query", "required": false, "description": "Absolute http or https URL of the file. Use instead of base64.", "schema": { "type": "string", "maxLength": 2048, "format": "uri" } }, { "name": "base64", "in": "query", "required": false, "description": "Base64-encoded file bytes, up to 10 MB once decoded. Use instead of url.", "schema": { "type": "string", "maxLength": 14000000 } }, { "name": "width", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 4096 } }, { "name": "height", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 4096 } }, { "name": "fit", "in": "query", "required": false, "schema": { "default": "scale-down", "type": "string", "enum": [ "scale-down", "contain", "cover", "crop", "pad" ] } }, { "name": "format", "in": "query", "required": false, "schema": { "default": "webp", "type": "string", "enum": [ "jpeg", "png", "webp" ] } }, { "name": "quality", "in": "query", "required": false, "schema": { "default": 80, "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 2 }, "post": { "operationId": "image_transform_post", "summary": "Resize an image and convert it to JPEG, PNG or WebP; metadata is stripped.", "description": "Use to make an image a particular size or format, for example a thumbnail or a WebP for the web. Output up to 1 MB is returned inline as base64.", "tags": [ "media" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "description": "Absolute http or https URL of the file. Use instead of base64.", "type": "string", "maxLength": 2048, "format": "uri" }, "base64": { "description": "Base64-encoded file bytes, up to 10 MB once decoded. Use instead of url.", "type": "string", "maxLength": 14000000 }, "width": { "type": "integer", "minimum": 1, "maximum": 4096 }, "height": { "type": "integer", "minimum": 1, "maximum": 4096 }, "fit": { "default": "scale-down", "type": "string", "enum": [ "scale-down", "contain", "cover", "crop", "pad" ] }, "format": { "default": "webp", "type": "string", "enum": [ "jpeg", "png", "webp" ] }, "quality": { "default": 80, "type": "integer", "minimum": 1, "maximum": 100 } } } } } }, "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 2 } }, "/v1/image.inspect": { "get": { "operationId": "image_inspect_get", "summary": "Format, dimensions, EXIF camera and capture data, and dominant colours of an image.", "description": "Use to learn what an image is: its size, format, camera and date from EXIF, and its main colours. EXIF may contain GPS coordinates when the camera recorded them. Dominant colours are only computed for PNG and JPEG.", "tags": [ "media" ], "parameters": [ { "name": "url", "in": "query", "required": false, "description": "Absolute http or https URL of the file. Use instead of base64.", "schema": { "type": "string", "maxLength": 2048, "format": "uri" } }, { "name": "base64", "in": "query", "required": false, "description": "Base64-encoded file bytes, up to 10 MB once decoded. Use instead of url.", "schema": { "type": "string", "maxLength": 14000000 } } ], "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 }, "post": { "operationId": "image_inspect_post", "summary": "Format, dimensions, EXIF camera and capture data, and dominant colours of an image.", "description": "Use to learn what an image is: its size, format, camera and date from EXIF, and its main colours. EXIF may contain GPS coordinates when the camera recorded them. Dominant colours are only computed for PNG and JPEG.", "tags": [ "media" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "description": "Absolute http or https URL of the file. Use instead of base64.", "type": "string", "maxLength": 2048, "format": "uri" }, "base64": { "description": "Base64-encoded file bytes, up to 10 MB once decoded. Use instead of url.", "type": "string", "maxLength": 14000000 } } } } } }, "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 1 } }, "/v1/image.ocr": { "get": { "operationId": "image_ocr_get", "summary": "Printed text read from an image, with mean confidence and word count.", "description": "Use to read text in a photo, scan or screenshot, for example a receipt, sign or document page. Works on clear printed text; handwriting and heavy stylisation fail.", "tags": [ "media" ], "parameters": [ { "name": "url", "in": "query", "required": false, "description": "Absolute http or https URL of the file. Use instead of base64.", "schema": { "type": "string", "maxLength": 2048, "format": "uri" } }, { "name": "base64", "in": "query", "required": false, "description": "Base64-encoded file bytes, up to 10 MB once decoded. Use instead of url.", "schema": { "type": "string", "maxLength": 14000000 } } ], "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 2 }, "post": { "operationId": "image_ocr_post", "summary": "Printed text read from an image, with mean confidence and word count.", "description": "Use to read text in a photo, scan or screenshot, for example a receipt, sign or document page. Works on clear printed text; handwriting and heavy stylisation fail.", "tags": [ "media" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "description": "Absolute http or https URL of the file. Use instead of base64.", "type": "string", "maxLength": 2048, "format": "uri" }, "base64": { "description": "Base64-encoded file bytes, up to 10 MB once decoded. Use instead of url.", "type": "string", "maxLength": 14000000 } } } } } }, "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 2 } }, "/v1/media.probe": { "get": { "operationId": "media_probe_get", "summary": "Duration, codecs, dimensions and container for an audio or video file up to 20 MB.", "description": "Use to inspect a media file before processing it: how long it is, what codecs it uses, its resolution. Give a URL or base64 bytes.", "tags": [ "media" ], "parameters": [ { "name": "url", "in": "query", "required": false, "description": "Absolute http or https URL of the file. Use instead of base64.", "schema": { "type": "string", "maxLength": 2048, "format": "uri" } }, { "name": "base64", "in": "query", "required": false, "description": "Base64-encoded file bytes, up to 20 MB once decoded. Use instead of url.", "schema": { "type": "string", "maxLength": 28000000 } } ], "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 2 }, "post": { "operationId": "media_probe_post", "summary": "Duration, codecs, dimensions and container for an audio or video file up to 20 MB.", "description": "Use to inspect a media file before processing it: how long it is, what codecs it uses, its resolution. Give a URL or base64 bytes.", "tags": [ "media" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "description": "Absolute http or https URL of the file. Use instead of base64.", "type": "string", "maxLength": 2048, "format": "uri" }, "base64": { "description": "Base64-encoded file bytes, up to 20 MB once decoded. Use instead of url.", "type": "string", "maxLength": 28000000 } } } } } }, "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 2 } }, "/v1/chart.render": { "get": { "operationId": "chart_render_get", "summary": "Bar, line or pie chart from up to 24 labelled values, returned as a PNG.", "description": "Use to turn numbers into a shareable chart image, for example a report figure or a quick visual of a comparison. Up to 24 points; for larger data summarise first.", "tags": [ "media" ], "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "default": "bar", "type": "string", "enum": [ "bar", "line", "pie" ] } }, { "name": "labels", "in": "query", "required": true, "schema": { "minItems": 1, "maxItems": 24, "type": "array", "items": { "type": "string", "maxLength": 60 } }, "style": "form", "explode": false }, { "name": "values", "in": "query", "required": true, "schema": { "minItems": 1, "maxItems": 24, "type": "array", "items": { "type": "number" } }, "style": "form", "explode": false }, { "name": "title", "in": "query", "required": false, "schema": { "default": "", "type": "string", "maxLength": 120 } } ], "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 2 }, "post": { "operationId": "chart_render_post", "summary": "Bar, line or pie chart from up to 24 labelled values, returned as a PNG.", "description": "Use to turn numbers into a shareable chart image, for example a report figure or a quick visual of a comparison. Up to 24 points; for larger data summarise first.", "tags": [ "media" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "kind": { "default": "bar", "type": "string", "enum": [ "bar", "line", "pie" ] }, "labels": { "minItems": 1, "maxItems": 24, "type": "array", "items": { "type": "string", "maxLength": 60 } }, "values": { "minItems": 1, "maxItems": 24, "type": "array", "items": { "type": "number" } }, "title": { "default": "", "type": "string", "maxLength": 120 } }, "required": [ "labels", "values" ] } } } }, "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 2 } }, "/v1/pdf.extract": { "get": { "operationId": "pdf_extract_get", "summary": "Page-by-page text from a text-based PDF, given as a URL or base64, up to 10 MB.", "description": "Use to read the text of a PDF such as a report, contract or paper. Works on text-based PDFs; for scanned pages with no text layer, use image.ocr on a rendered page image instead.", "tags": [ "media" ], "parameters": [ { "name": "url", "in": "query", "required": false, "description": "Absolute http or https URL of the file. Use instead of base64.", "schema": { "type": "string", "maxLength": 2048, "format": "uri" } }, { "name": "base64", "in": "query", "required": false, "description": "Base64-encoded file bytes, up to 10 MB once decoded. Use instead of url.", "schema": { "type": "string", "maxLength": 14000000 } }, { "name": "max_pages", "in": "query", "required": false, "description": "Pages to read from the start of the document.", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 2 }, "post": { "operationId": "pdf_extract_post", "summary": "Page-by-page text from a text-based PDF, given as a URL or base64, up to 10 MB.", "description": "Use to read the text of a PDF such as a report, contract or paper. Works on text-based PDFs; for scanned pages with no text layer, use image.ocr on a rendered page image instead.", "tags": [ "media" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "description": "Absolute http or https URL of the file. Use instead of base64.", "type": "string", "maxLength": 2048, "format": "uri" }, "base64": { "description": "Base64-encoded file bytes, up to 10 MB once decoded. Use instead of url.", "type": "string", "maxLength": 14000000 }, "max_pages": { "default": 50, "description": "Pages to read from the start of the document.", "type": "integer", "minimum": 1, "maximum": 200 } } } } } }, "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 2 } }, "/v1/web.screenshot": { "get": { "operationId": "web_screenshot_get", "summary": "Renders a public URL in a headless Chromium and returns a JPEG or PNG screenshot.", "description": "Use to see what a page looks like, including pages that need JavaScript. Renders with a real browser, which is slower than the text tools. Output up to 1 MB is returned inline.", "tags": [ "web" ], "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 2048, "format": "uri" } }, { "name": "width", "in": "query", "required": false, "schema": { "default": 1280, "type": "integer", "minimum": 320, "maximum": 1920 } }, { "name": "height", "in": "query", "required": false, "schema": { "default": 800, "type": "integer", "minimum": 200, "maximum": 2000 } }, { "name": "full_page", "in": "query", "required": false, "description": "Capture the full scroll height instead of the viewport.", "schema": { "default": false, "type": "boolean" } }, { "name": "format", "in": "query", "required": false, "schema": { "default": "jpeg", "type": "string", "enum": [ "jpeg", "png" ] } } ], "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 5 }, "post": { "operationId": "web_screenshot_post", "summary": "Renders a public URL in a headless Chromium and returns a JPEG or PNG screenshot.", "description": "Use to see what a page looks like, including pages that need JavaScript. Renders with a real browser, which is slower than the text tools. Output up to 1 MB is returned inline.", "tags": [ "web" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "width": { "default": 1280, "type": "integer", "minimum": 320, "maximum": 1920 }, "height": { "default": 800, "type": "integer", "minimum": 200, "maximum": 2000 }, "full_page": { "default": false, "description": "Capture the full scroll height instead of the viewport.", "type": "boolean" }, "format": { "default": "jpeg", "type": "string", "enum": [ "jpeg", "png" ] } }, "required": [ "url" ] } } } }, "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 5 } }, "/v1/web.pdf": { "get": { "operationId": "web_pdf_get", "summary": "Prints a public URL, or HTML you supply, to an A4 or Letter PDF using a headless browser.", "description": "Use to produce a printable PDF of a page, or of HTML the agent has written. Renders JavaScript and CSS like a browser print. Output up to 1 MB is returned inline.", "tags": [ "web" ], "parameters": [ { "name": "url", "in": "query", "required": false, "description": "Public page to print. Use instead of html.", "schema": { "type": "string", "maxLength": 2048, "format": "uri" } }, { "name": "html", "in": "query", "required": false, "description": "Raw HTML to print. Use instead of url.", "schema": { "type": "string", "maxLength": 500000 } }, { "name": "format", "in": "query", "required": false, "schema": { "default": "A4", "type": "string", "enum": [ "A4", "Letter" ] } }, { "name": "print_background", "in": "query", "required": false, "schema": { "default": true, "type": "boolean" } } ], "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 5 }, "post": { "operationId": "web_pdf_post", "summary": "Prints a public URL, or HTML you supply, to an A4 or Letter PDF using a headless browser.", "description": "Use to produce a printable PDF of a page, or of HTML the agent has written. Renders JavaScript and CSS like a browser print. Output up to 1 MB is returned inline.", "tags": [ "web" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "description": "Public page to print. Use instead of html.", "type": "string", "maxLength": 2048, "format": "uri" }, "html": { "description": "Raw HTML to print. Use instead of url.", "type": "string", "maxLength": 500000 }, "format": { "default": "A4", "type": "string", "enum": [ "A4", "Letter" ] }, "print_background": { "default": true, "type": "boolean" } } } } } }, "responses": { "200": { "description": "Envelope with ok=true and data populated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "4XX": { "description": "Envelope with ok=false. See error.code and error.hint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } }, "5XX": { "description": "Envelope with ok=false. Retry when error.retryable is true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "meta", "error" ], "properties": { "ok": { "type": "boolean" }, "data": { "type": [ "object", "null" ] }, "meta": { "type": "object", "properties": { "tool": { "type": "string" }, "version": { "type": "string" }, "took_ms": { "type": "integer" }, "cached": { "type": "boolean" }, "stale": { "type": "boolean" }, "source": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" } } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after_s": { "type": "integer" }, "hint": { "type": "string" } } } } } } } } }, "x-cost-units": 5 } } } }