{ "openapi": "3.1.0", "info": { "title": "MapIron API", "version": "1.0.0", "description": "Map API built on OpenStreetMap data: static map images (including a privacy area mode), geocoding and reverse geocoding, and raster and vector tiles.\n\nEvery request takes an API key as `?key=ps_\u2026` or `Authorization: Bearer ps_\u2026`. Plans have hard monthly caps per product; when a cap is reached the product returns 429 until the first of the next month or until you upgrade. Show \"\u00a9 OpenStreetMap contributors\" wherever maps or results appear.", "termsOfService": "https://mapiron.com/terms", "contact": { "name": "MapIron support", "email": "support@mapiron.com", "url": "https://mapiron.com" } }, "externalDocs": { "url": "https://mapiron.com/docs" }, "servers": [ { "url": "https://api.mapiron.com" } ], "security": [ { "apiKeyQuery": [] }, { "bearerAuth": [] } ], "tags": [ { "name": "Static maps" }, { "name": "Geocoding" }, { "name": "Tiles" }, { "name": "MCP" }, { "name": "Service" }, { "name": "Keys API", "description": "For platforms: manage map keys with an API token (psm_\u2026). See /docs/keys-api." } ], "x-attribution": "\u00a9 OpenStreetMap contributors", "components": { "securitySchemes": { "apiKeyQuery": { "type": "apiKey", "in": "query", "name": "key" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "ps_\u2026" }, "mgmtToken": { "type": "http", "scheme": "bearer", "bearerFormat": "psm_\u2026", "description": "API token for the keys API, made in the dashboard. Never accepted on map endpoints." } }, "schemas": { "Caps": { "type": [ "object", "null" ], "description": "Monthly caps for one key; null or a missing product shares the account's cap.", "properties": { "static": { "type": [ "integer", "null" ], "minimum": 0 }, "geocode": { "type": [ "integer", "null" ], "minimum": 0 }, "tiles": { "type": [ "integer", "null" ], "minimum": 0 } } }, "Key": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque key id (key_\u2026)." }, "key": { "type": "string", "description": "The secret; only when created or rotated." }, "prefix": { "type": "string" }, "name": { "type": "string" }, "referers": { "type": "array", "items": { "type": "string" } }, "external_id": { "type": [ "string", "null" ] }, "caps": { "$ref": "#/components/schemas/Caps" }, "metadata": { "type": "object" }, "created_via": { "type": "string", "enum": [ "dashboard", "api", "cli" ] }, "created_at": { "type": "string", "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "usage_this_month": { "type": "object", "properties": { "static": { "type": "integer" }, "geocode": { "type": "integer" }, "tiles": { "type": "integer" } } } } }, "Error": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "bad_request", "invalid_body", "unsupported_media_type", "payload_too_large", "method_not_allowed", "missing_key", "invalid_key", "referer_denied", "monthly_cap_reached", "slow_down", "daily_limit_reached", "demo_limit_reached", "too_many_attempts", "engine_error", "unavailable", "internal", "not_found", "forbidden", "not_signed_in", "passkey_failed", "reauth_required", "step_up_required", "missing_token", "invalid_token", "insufficient_scope", "plan_feature_unavailable", "plan_upgrade_required", "privacy_mode_active", "district_retired", "key_limit_reached", "external_id_taken", "webhook_limit_reached", "token_limit_reached", "idempotency_in_progress", "idempotency_key_reused" ], "description": "Machine-readable code; see https://mapiron.com/docs#limits and docs/errors.md. New codes may be added: treat unknown codes by HTTP status." }, "scope": { "type": "string", "enum": [ "key", "account" ], "description": "With monthly_cap_reached: whose cap was reached." }, "message": { "type": "string", "description": "A sentence you can show to a person." }, "detail": { "type": "string", "description": "When the request couldn't be parsed: the parser's own explanation, for developers." }, "methods": { "type": "array", "items": { "type": "string" }, "description": "With reauth_required: the ways the account can confirm it's you." }, "product": { "type": "string" }, "cap": { "type": "integer" }, "resets": { "type": "string", "format": "date" }, "upgrade_url": { "type": "string", "format": "uri" } } }, "GeocodeResponse": { "type": "object", "required": [ "type", "features", "attribution", "license" ], "properties": { "type": { "type": "string", "enum": [ "FeatureCollection" ] }, "features": { "type": "array", "items": { "$ref": "#/components/schemas/GeocodeFeature" } }, "attribution": { "type": "string" }, "license": { "type": "string" } } }, "GeocodeFeature": { "type": "object", "required": [ "type", "geometry", "properties" ], "properties": { "type": { "type": "string", "enum": [ "Feature" ] }, "geometry": { "type": "object", "required": [ "type", "coordinates" ], "properties": { "type": { "type": "string", "enum": [ "Point" ] }, "coordinates": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "number" }, "description": "[longitude, latitude]" } } }, "properties": { "type": "object", "properties": { "name": { "type": "string" }, "housenumber": { "type": "string" }, "street": { "type": "string" }, "postcode": { "type": "string" }, "city": { "type": "string" }, "district": { "type": "string" }, "county": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "countrycode": { "type": "string" }, "osm_type": { "type": "string" }, "osm_id": { "type": "string" }, "osm_key": { "type": "string" }, "osm_value": { "type": "string" }, "type": { "type": "string" }, "extent": { "type": "array", "items": { "type": "number" } } }, "additionalProperties": true } } } }, "responses": { "BadRequest": { "description": "Bad request: missing or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Key is not allowed from this website.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "No such tile, style or path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TooMany": { "description": "monthly_cap_reached or slow_down; see Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "EngineError": { "description": "Temporary engine error; retry shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "paths": { "/v1/static": { "get": { "operationId": "staticMap", "summary": "Render a static map image", "description": "Give center+zoom, or any of area/markers/path to fit automatically. Privacy area mode snaps the point to a grid, always keeps the real point inside the circle, draws no pin, and returns the identical image for every address in the same grid cell. Counts as 1 static image. Free plan adds a small mark.", "tags": [ "Static maps" ], "parameters": [ { "name": "center", "in": "query", "schema": { "type": "string" }, "description": "lat,lng" }, { "name": "zoom", "in": "query", "schema": { "type": "number", "minimum": 0, "maximum": 20 }, "description": "0 to 20." }, { "name": "size", "in": "query", "schema": { "type": "string", "default": "600x400" }, "description": "WIDTHxHEIGHT; each side 16 to 1280." }, { "name": "scale", "in": "query", "schema": { "type": "integer", "default": 1, "enum": [ 1, 2 ] } }, { "name": "style", "in": "query", "schema": { "type": "string", "default": "light", "enum": [ "light", "dark", "white", "grayscale" ] } }, { "name": "format", "in": "query", "schema": { "type": "string", "default": "png", "enum": [ "png", "jpg", "webp" ] } }, { "name": "padding", "in": "query", "schema": { "type": "integer", "default": 40 }, "description": "Pixels kept clear around fitted content." }, { "name": "markers", "in": "query", "schema": { "type": "string" }, "description": "lat,lng|lat,lng; up to 25 points." }, { "name": "marker_color", "in": "query", "schema": { "type": "string" }, "description": "Hex colour." }, { "name": "path", "in": "query", "schema": { "type": "string" }, "description": "lat,lng|\u2026; 2 to 200 points." }, { "name": "path_color", "in": "query", "schema": { "type": "string" }, "description": "Hex colour." }, { "name": "path_width", "in": "query", "schema": { "type": "integer", "default": 4, "minimum": 1, "maximum": 12 } }, { "name": "area", "in": "query", "schema": { "type": "string" }, "description": "Privacy area point as lat,lng. Round it to the snap grid before putting the URL in a web page; the image is the same." }, { "name": "radius", "in": "query", "schema": { "type": "number", "default": 1000, "minimum": 100, "maximum": 25000 }, "description": "Circle radius in metres." }, { "name": "snap", "in": "query", "schema": { "type": "number", "default": 0.01, "minimum": 0, "maximum": 0.1 }, "description": "Grid size in degrees; 0.01 is about 1 km. Values below 0.005 (including 0) use 0.005." }, { "name": "color", "in": "query", "schema": { "type": "string" }, "description": "Hex colour for the area circle." } ], "responses": { "200": { "description": "OK", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Bad request: missing or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key is not allowed from this website.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "monthly_cap_reached or slow_down; see Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Temporary engine error; retry shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/geocode": { "get": { "operationId": "geocode", "summary": "Forward geocoding", "description": "Turns an address or place name into GeoJSON features. Counts as 1 geocode.", "tags": [ "Geocoding" ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 300 }, "required": true, "description": "Text to search for." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 5, "minimum": 1, "maximum": 20 } }, { "name": "lang", "in": "query", "schema": { "type": "string" }, "description": "Language code, or default for local names." }, { "name": "lat", "in": "query", "schema": { "type": "number" }, "description": "Prefer results near this latitude." }, { "name": "lon", "in": "query", "schema": { "type": "number" }, "description": "Prefer results near this longitude." }, { "name": "bbox", "in": "query", "schema": { "type": "string" }, "description": "minLon,minLat,maxLon,maxLat to restrict results." }, { "name": "layer", "in": "query", "schema": { "type": "string" }, "description": "Feature layer filter, e.g. house, street, city." }, { "name": "osm_tag", "in": "query", "schema": { "type": "string" }, "description": "OpenStreetMap tag filter." }, { "name": "zoom", "in": "query", "schema": { "type": "number" }, "description": "Location bias zoom." }, { "name": "location_bias_scale", "in": "query", "schema": { "type": "number" }, "description": "Location bias scale." } ], "responses": { "200": { "description": "GeoJSON results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeocodeResponse" } } } }, "400": { "description": "Bad request: missing or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key is not allowed from this website.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "monthly_cap_reached or slow_down; see Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Temporary engine error; retry shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/autocomplete": { "get": { "operationId": "autocomplete", "summary": "Address autocomplete", "description": "Same parameters as geocode; suited to type-ahead boxes. Counts as 1 geocode.", "tags": [ "Geocoding" ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 300 }, "required": true, "description": "Text to search for." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 5, "minimum": 1, "maximum": 20 } }, { "name": "lang", "in": "query", "schema": { "type": "string" }, "description": "Language code, or default for local names." }, { "name": "lat", "in": "query", "schema": { "type": "number" }, "description": "Prefer results near this latitude." }, { "name": "lon", "in": "query", "schema": { "type": "number" }, "description": "Prefer results near this longitude." }, { "name": "bbox", "in": "query", "schema": { "type": "string" }, "description": "minLon,minLat,maxLon,maxLat to restrict results." }, { "name": "layer", "in": "query", "schema": { "type": "string" }, "description": "Feature layer filter, e.g. house, street, city." }, { "name": "osm_tag", "in": "query", "schema": { "type": "string" }, "description": "OpenStreetMap tag filter." }, { "name": "zoom", "in": "query", "schema": { "type": "number" }, "description": "Location bias zoom." }, { "name": "location_bias_scale", "in": "query", "schema": { "type": "number" }, "description": "Location bias scale." } ], "responses": { "200": { "description": "GeoJSON results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeocodeResponse" } } } }, "400": { "description": "Bad request: missing or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key is not allowed from this website.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "monthly_cap_reached or slow_down; see Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Temporary engine error; retry shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reverse": { "get": { "operationId": "reverseGeocode", "summary": "Reverse geocoding", "description": "Coordinates to the nearest address or place. Counts as 1 geocode.", "tags": [ "Geocoding" ], "parameters": [ { "name": "lat", "in": "query", "schema": { "type": "number" }, "required": true }, { "name": "lon", "in": "query", "schema": { "type": "number" }, "required": true }, { "name": "radius", "in": "query", "schema": { "type": "number" }, "description": "Radius in km." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 5, "minimum": 1, "maximum": 20 } }, { "name": "lang", "in": "query", "schema": { "type": "string" } }, { "name": "layer", "in": "query", "schema": { "type": "string" } }, { "name": "osm_tag", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "GeoJSON results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeocodeResponse" } } } }, "400": { "description": "Bad request: missing or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key is not allowed from this website.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "monthly_cap_reached or slow_down; see Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Temporary engine error; retry shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/schools": { "get": { "operationId": "schoolsAtPoint", "summary": "School districts and attendance zones at a point", "description": "US public school districts at a point and, grade by grade, the assigned public school with its attendance zone (method, confidence, school year, source). Grades without a mapped zone list the district's nearest regular schools instead. Boundaries only: no ratings or demographics. Results may be stored. Counts as 1 geocode.", "tags": [ "Schools" ], "parameters": [ { "name": "lat", "in": "query", "schema": { "type": "number" }, "required": true, "description": "Latitude (WGS84)." }, { "name": "lon", "in": "query", "schema": { "type": "number" }, "required": true, "description": "Longitude (WGS84)." }, { "name": "grade", "in": "query", "schema": { "type": "string" }, "description": "Only this grade: PK, K or 1 to 12." } ], "responses": { "200": { "description": "Districts, assigned schools and zones.", "content": { "application/json": { "schema": { "type": "object", "properties": { "coverage": { "type": "string", "enum": [ "zone", "partial", "district_only", "none" ] }, "districts": { "type": "array", "items": { "type": "object" } }, "assigned": { "type": "array", "items": { "type": "object" } }, "unassigned": { "type": "array", "items": { "type": "object" } }, "notice": { "type": "string" }, "sources": { "type": "string" }, "license": { "type": "string" } } } } } }, "400": { "description": "Bad request: missing or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key is not allowed from this website.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "monthly_cap_reached or slow_down; see Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Temporary engine error; retry shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/parcels": { "get": { "operationId": "parcels", "summary": "Property parcel at a point, or parcels in a box", "description": "US property parcel boundaries from open public records: the parcel containing lat/lon (1 geocode), or up to 200 parcels in a bbox of at most 1 km\u00b2 (1 geocode per 10 returned). Geometry, county parcel number (APN), area and source; never owner names or values. Growth plans and up (403 plan_upgrade_required otherwise). Results from sources marked keep_forever may be stored indefinitely on paid plans.", "tags": [ "Parcels" ], "parameters": [ { "name": "lat", "in": "query", "schema": { "type": "number" }, "description": "Latitude of a point inside the parcel (with lon)." }, { "name": "lon", "in": "query", "schema": { "type": "number" }, "description": "Longitude (with lat)." }, { "name": "bbox", "in": "query", "schema": { "type": "string" }, "description": "min_lon,min_lat,max_lon,max_lat, at most 1 km\u00b2 (instead of lat/lon)." }, { "name": "geometry", "in": "query", "schema": { "type": "string", "enum": [ "full", "simplified", "none" ] }, "description": "Boundary detail (default full)." }, { "name": "limit", "in": "query", "schema": { "type": "integer" }, "description": "bbox only: 1 to 200." } ], "responses": { "200": { "description": "The parcel (or null), or a FeatureCollection for bbox, with attribution, license and notice.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: missing or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key is not allowed from this website.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "monthly_cap_reached or slow_down; see Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Temporary engine error; retry shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/parcels/{parcel_id}": { "get": { "operationId": "parcelById", "summary": "Property parcel by id", "description": "A parcel by its parcel_id (us--). 1 geocode. Growth plans and up.", "tags": [ "Parcels" ], "parameters": [ { "name": "parcel_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "geometry", "in": "query", "schema": { "type": "string", "enum": [ "full", "simplified", "none" ] }, "description": "Boundary detail (default full)." } ], "responses": { "200": { "description": "The parcel.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: missing or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key is not allowed from this website.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "monthly_cap_reached or slow_down; see Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Temporary engine error; retry shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/parcels/coverage": { "get": { "operationId": "parcelCoverage", "summary": "Parcel sources that are live", "description": "Sources, parcel counts, dates, licences and attribution. No key, no quota.", "tags": [ "Parcels" ], "security": [], "responses": { "200": { "description": "Coverage.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/districts": { "get": { "operationId": "getSpecialDistricts", "summary": "Texas special districts (MUD, WCID, PID) at a point", "description": "Every Texas special taxing district that contains lat/lon: MUDs, WCIDs, FWSDs, LIDs, management and other water districts statewide (TCEQ) and PIDs where cities publish them, with each district's self-reported tax rate per $100 (and its year), outstanding debt, website and the statute for the purchaser's notice (Water Code \u00a749.452 or Property Code \u00a75.014). result is districts_found, none_found or outside_coverage; none_found is not proof that no district applies. near_boundary, distance_to_boundary_m and nearby (within 150 m) flag lots that may straddle a boundary. tax and debt are null when no confident Comptroller match exists, never 0. 1 geocode. Growth plans and up (403 plan_upgrade_required otherwise).", "tags": [ "Districts" ], "parameters": [ { "name": "lat", "in": "query", "schema": { "type": "number" }, "description": "Latitude of the property (a point inside the parcel is best)." }, { "name": "lon", "in": "query", "schema": { "type": "number" }, "description": "Longitude." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "all" ] }, "description": "active (default: active and unknown status) or all (adds inactive and dissolved districts)." }, { "name": "geometry", "in": "query", "schema": { "type": "string", "enum": [ "none", "simplified", "full" ] }, "description": "District boundaries (default none)." } ], "responses": { "200": { "description": "result, coverage, districts, nearby, warnings, attribution, license, notice, data_version.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: missing or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key is not allowed from this website.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "monthly_cap_reached or slow_down; see Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Temporary engine error; retry shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/districts/{district_id}": { "get": { "operationId": "getSpecialDistrict", "summary": "A Texas special district by id", "description": "One district by id (tx-wd- or tx-pid-fortworth-), with simplified boundary by default. 410 district_retired for a district that left the data. 1 geocode. Growth plans and up.", "tags": [ "Districts" ], "parameters": [ { "name": "district_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "geometry", "in": "query", "schema": { "type": "string", "enum": [ "none", "simplified", "full" ] }, "description": "Boundary detail (default simplified)." } ], "responses": { "200": { "description": "The district.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request: missing or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key is not allowed from this website.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "monthly_cap_reached or slow_down; see Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Temporary engine error; retry shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/districts/coverage": { "get": { "operationId": "districtCoverage", "summary": "Texas special district coverage", "description": "Counts by type and status, Comptroller match rate, PID areas, sources, licences and attribution. No key, no quota.", "tags": [ "Districts" ], "security": [], "responses": { "200": { "description": "Coverage.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/tiles/{style}/{z}/{x}/{file}": { "get": { "operationId": "rasterTile", "summary": "Raster map tile", "description": "256-pixel raster tile. Counts as 1 tile.", "tags": [ "Tiles" ], "parameters": [ { "name": "style", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "light", "dark", "white", "grayscale" ] } }, { "name": "z", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0, "maximum": 20 } }, { "name": "x", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "file", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Bad request or unknown style.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key is not allowed from this website.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "monthly_cap_reached or slow_down; see Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tiles/vector/{z}/{x}/{file}": { "get": { "operationId": "vectorTile", "summary": "Vector map tile", "description": "Protomaps basemap schema vector tile. Counts as 1 tile.", "tags": [ "Tiles" ], "parameters": [ { "name": "z", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0, "maximum": 15 } }, { "name": "x", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "file", "in": "path", "required": true, "schema": { "type": "string" }, "description": "{y}.pbf" } ], "responses": { "200": { "description": "Vector tile.", "content": { "application/x-protobuf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key is not allowed from this website.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "monthly_cap_reached or slow_down; see Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tiles/vector.json": { "get": { "operationId": "tileJSON", "summary": "Vector TileJSON", "description": "TileJSON for the Protomaps vector basemap. Free of charge.", "tags": [ "Tiles" ], "responses": { "200": { "description": "TileJSON.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "monthly_cap_reached or slow_down; see Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/styles/{file}": { "get": { "operationId": "style", "summary": "MapLibre style JSON", "description": "MapLibre style whose tile, glyph and sprite URLs already carry the caller's key. Free of charge.", "tags": [ "Tiles" ], "parameters": [ { "name": "file", "in": "path", "required": true, "schema": { "type": "string" }, "description": "{style}.json" } ], "responses": { "200": { "description": "MapLibre style JSON.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such style.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "monthly_cap_reached or slow_down; see Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/mcp": { "post": { "operationId": "mcp", "summary": "MapIron MCP server", "description": "Streamable HTTP JSON-RPC 2.0 endpoint. Stateless; no SSE. initialize and tools/list need no key. tools/call uses the API key and counts like REST.", "tags": [ "MCP" ], "externalDocs": { "url": "https://mapiron.com/docs/mcp" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "type": [ "string", "integer" ] }, "method": { "type": "string" }, "params": { "type": "object" } } } } } }, "responses": { "200": { "description": "JSON-RPC response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "monthly_cap_reached or slow_down; see Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Temporary engine error; retry shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/health": { "get": { "operationId": "health", "summary": "Service health", "description": "Reports whether the service and database are OK. No API key required.", "tags": [ "Service" ], "security": [], "responses": { "200": { "description": "Health JSON.", "content": { "application/json": { "schema": { "type": "object" } } } }, "502": { "description": "Service unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/whoami": { "get": { "operationId": "whoami", "summary": "Check a key (free)", "description": "Checks a map key and returns its plan, this month's usage, caps and what's left, without counting anything. No-code tools (Zapier, Make, n8n, Google Sheets) use it to test a connection. Website limits apply as on the map endpoints. Optional header X-PS-Client: tool/version.", "tags": [ "Service" ], "parameters": [ { "name": "client", "in": "query", "schema": { "type": "string" }, "description": "Name of the calling tool, e.g. batch/1 (browsers that can't set X-PS-Client)." } ], "responses": { "200": { "description": "The key works.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "plan", "key", "usage", "resets", "upgrade_url", "attribution" ], "properties": { "ok": { "type": "boolean" }, "plan": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "price_usd": { "type": "integer" }, "storage_days": { "type": [ "integer", "null" ], "description": "Days results may be stored; null = indefinitely." }, "watermark": { "type": "boolean" }, "rate_per_sec": { "type": [ "number", "null" ] } } }, "key": { "type": "object", "properties": { "prefix": { "type": "string" }, "name": { "type": "string" }, "website_limited": { "type": "boolean" } } }, "usage": { "type": "object", "description": "static, geocode and tiles: used, cap, remaining (and key_cap when the key has its own cap).", "additionalProperties": { "type": "object", "properties": { "used": { "type": "integer" }, "cap": { "type": "integer" }, "remaining": { "type": "integer" }, "key_cap": { "type": "integer" } } } }, "resets": { "type": "string", "format": "date" }, "upgrade_url": { "type": "string", "format": "uri" }, "attribution": { "type": "string" } } } } } }, "401": { "description": "missing_key or invalid_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "referer_denied: the key is limited to other websites.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/meta": { "get": { "operationId": "meta", "summary": "Public metadata", "description": "Plans, styles and attribution. No API key required.", "tags": [ "Service" ], "security": [], "responses": { "200": { "description": "Metadata JSON.", "content": { "application/json": { "schema": { "type": "object" } } } }, "502": { "description": "Service unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/demo": { "get": { "operationId": "demoLookup", "summary": "Keyless demo lookup", "description": "IP-limited keyless demo for the public website.", "tags": [ "Service" ], "security": [], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Demo result.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "slow_down; see Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/demo/autocomplete": { "get": { "operationId": "demoAutocomplete", "summary": "Keyless demo address suggestions", "description": "Type-ahead for the website demo: up to 5 suggestions in the same shape as /v1/autocomplete. Under 3 characters returns an empty collection. IP-limited; not for production use (use /v1/autocomplete with a key).", "tags": [ "Service" ], "security": [], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" }, "required": true, "description": "Text typed so far, up to 120 characters." } ], "responses": { "200": { "description": "Up to 5 suggestions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeocodeResponse" } } } }, "400": { "description": "bad_request: q is longer than 120 characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "slow_down; see Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "engine_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/demo/image": { "get": { "operationId": "demoImage", "summary": "Keyless demo image", "description": "Keyless privacy-area demo image.", "tags": [ "Service" ], "security": [], "parameters": [ { "name": "area", "in": "query", "schema": { "type": "string" }, "required": true, "description": "lat,lng" } ], "responses": { "200": { "description": "OK", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "slow_down; see Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/keys": { "post": { "operationId": "createKey", "summary": "Create a key", "description": "Creates a map key; `key` (the secret) is in this response only. Honours `Idempotency-Key` for 24 hours. Scope keys:write.", "tags": [ "Keys API" ], "security": [ { "mgmtToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Key" } } } }, "401": { "description": "missing_token or invalid_token (a map key is not a management token).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, or plan_feature_unavailable (the keys API, per-key caps and webhooks are on the platform plan).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "bad_request (including unknown fields in the body).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "key_limit_reached, external_id_taken or idempotency_in_progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "idempotency_key_reused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "slow_down: over 10 a second or 300 a minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 60 }, "referers": { "type": "array", "items": { "type": "string" }, "maxItems": 20, "description": "Host names; *.example.com covers subdomains." }, "external_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "Your own id for the site; unique among live keys." }, "caps": { "$ref": "#/components/schemas/Caps" }, "metadata": { "type": "object", "description": "Any JSON object up to 4 KB." } } } } } } }, "get": { "operationId": "listKeys", "summary": "List keys", "description": "Live keys, oldest first. Scope keys:read.", "tags": [ "Keys API" ], "security": [ { "mgmtToken": [] } ], "parameters": [ { "name": "external_id", "in": "query", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "next_cursor from the previous page." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 200 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "all" ] } } ], "responses": { "200": { "description": "A page of keys.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Key" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "401": { "description": "missing_token or invalid_token (a map key is not a management token).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, or plan_feature_unavailable (the keys API, per-key caps and webhooks are on the platform plan).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "bad_request (including unknown fields in the body).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/keys/{id}": { "get": { "operationId": "getKey", "summary": "Get a key", "description": "Scope keys:read.", "tags": [ "Keys API" ], "security": [ { "mgmtToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Key id (key_\u2026)." } ], "responses": { "200": { "description": "The key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Key" } } } }, "401": { "description": "missing_token or invalid_token (a map key is not a management token).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, or plan_feature_unavailable (the keys API, per-key caps and webhooks are on the platform plan).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "bad_request (including unknown fields in the body).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updateKey", "summary": "Change a key", "description": "Only the fields sent change; `caps` replaces all three caps. Scope keys:write.", "tags": [ "Keys API" ], "security": [ { "mgmtToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Key id (key_\u2026)." } ], "responses": { "200": { "description": "The key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Key" } } } }, "401": { "description": "missing_token or invalid_token (a map key is not a management token).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, or plan_feature_unavailable (the keys API, per-key caps and webhooks are on the platform plan).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "bad_request (including unknown fields in the body).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "external_id_taken.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 60 }, "referers": { "type": "array", "items": { "type": "string" }, "maxItems": 20, "description": "Host names; *.example.com covers subdomains." }, "external_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "Your own id for the site; unique among live keys." }, "caps": { "$ref": "#/components/schemas/Caps" }, "metadata": { "type": "object", "description": "Any JSON object up to 4 KB." } } } } } } }, "delete": { "operationId": "revokeKey", "summary": "Revoke a key", "description": "Takes effect within about a minute everywhere. Scope keys:write.", "tags": [ "Keys API" ], "security": [ { "mgmtToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Key id (key_\u2026)." } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "missing_token or invalid_token (a map key is not a management token).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, or plan_feature_unavailable (the keys API, per-key caps and webhooks are on the platform plan).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "bad_request (including unknown fields in the body).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/keys/{id}/rotate": { "post": { "operationId": "rotateKey", "summary": "Rotate a key's secret", "description": "New secret, same id; the old secret works for `grace_seconds`. Scope keys:write.", "tags": [ "Keys API" ], "security": [ { "mgmtToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Key id (key_\u2026)." } ], "responses": { "200": { "description": "The key with its new `key` and `previous_key_valid_until`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Key" } } } }, "401": { "description": "missing_token or invalid_token (a map key is not a management token).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, or plan_feature_unavailable (the keys API, per-key caps and webhooks are on the platform plan).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "bad_request (including unknown fields in the body).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "grace_seconds": { "type": "integer", "minimum": 0, "maximum": 86400, "default": 3600 } } } } } } } }, "/v1/keys/{id}/usage": { "get": { "operationId": "keyUsage", "summary": "Usage of one key", "description": "Requests per day (up to 400 days) or per month. Scope usage:read.", "tags": [ "Keys API" ], "security": [ { "mgmtToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Key id (key_\u2026)." }, { "name": "granularity", "in": "query", "schema": { "type": "string", "default": "day", "enum": [ "day", "month" ] } }, { "name": "from", "in": "query", "schema": { "type": "string" } }, { "name": "to", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "missing_token or invalid_token (a map key is not a management token).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, or plan_feature_unavailable (the keys API, per-key caps and webhooks are on the platform plan).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "bad_request (including unknown fields in the body).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/usage": { "get": { "operationId": "accountUsage", "summary": "Usage by key", "description": "The account's usage for a month, with `group_by=key` per key; `format=csv` for a CSV. Scope usage:read.", "tags": [ "Keys API" ], "security": [ { "mgmtToken": [] } ], "parameters": [ { "name": "month", "in": "query", "schema": { "type": "string" }, "description": "YYYY-MM; default this month." }, { "name": "group_by", "in": "query", "schema": { "type": "string", "enum": [ "key" ] } }, { "name": "format", "in": "query", "schema": { "type": "string", "default": "json", "enum": [ "json", "csv" ] } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "next_cursor from the previous page." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 1000 } } ], "responses": { "200": { "description": "Usage.", "content": { "application/json": { "schema": { "type": "object" } }, "text/csv": { "schema": { "type": "string" } } } }, "401": { "description": "missing_token or invalid_token (a map key is not a management token).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, or plan_feature_unavailable (the keys API, per-key caps and webhooks are on the platform plan).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "bad_request (including unknown fields in the body).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks": { "post": { "operationId": "createWebhook", "summary": "Add a webhook", "description": "https URLs with a public host name on port 443; up to 5. The signing `secret` is in this response only. Signed with PS-Signature (t=\u2026,v1=HMAC-SHA256 of `t.body`). Retried for 24 hours; turned off after a 410 or 3 days of failures. Scope keys:write.", "tags": [ "Keys API" ], "security": [ { "mgmtToken": [] } ], "parameters": [], "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "missing_token or invalid_token (a map key is not a management token).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, or plan_feature_unavailable (the keys API, per-key caps and webhooks are on the platform plan).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "bad_request (including unknown fields in the body).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "webhook_limit_reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "key.usage.80", "key.usage.100", "account.usage.80", "account.usage.100", "key.created", "key.rotated", "key.revoked" ] } } } } } } } }, "get": { "operationId": "listWebhooks", "summary": "List webhooks", "description": "With each webhook's status (active or disabled, and why) and latest delivery. Scope keys:read.", "tags": [ "Keys API" ], "security": [ { "mgmtToken": [] } ], "parameters": [], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "missing_token or invalid_token (a map key is not a management token).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, or plan_feature_unavailable (the keys API, per-key caps and webhooks are on the platform plan).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "bad_request (including unknown fields in the body).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}": { "patch": { "operationId": "updateWebhook", "summary": "Change a webhook", "description": "Change `url` or `events`, or turn it off and on with `enabled`. Scope keys:write.", "tags": [ "Keys API" ], "security": [ { "mgmtToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Webhook id (whk_\u2026)." } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "missing_token or invalid_token (a map key is not a management token).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, or plan_feature_unavailable (the keys API, per-key caps and webhooks are on the platform plan).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "bad_request (including unknown fields in the body).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" } } } } } } }, "delete": { "operationId": "deleteWebhook", "summary": "Delete a webhook", "description": "Scope keys:write.", "tags": [ "Keys API" ], "security": [ { "mgmtToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Webhook id (whk_\u2026)." } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "missing_token or invalid_token (a map key is not a management token).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, or plan_feature_unavailable (the keys API, per-key caps and webhooks are on the platform plan).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "bad_request (including unknown fields in the body).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}/test": { "post": { "operationId": "testWebhook", "summary": "Send a test event", "description": "Queues a `webhook.test` event to this webhook only. Scope keys:write.", "tags": [ "Keys API" ], "security": [ { "mgmtToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Webhook id (whk_\u2026)." } ], "responses": { "202": { "description": "Queued.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "missing_token or invalid_token (a map key is not a management token).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, or plan_feature_unavailable (the keys API, per-key caps and webhooks are on the platform plan).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "bad_request (including unknown fields in the body).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}/deliveries": { "get": { "operationId": "listDeliveries", "summary": "List deliveries", "description": "The last 30 days, newest first. Scope keys:read.", "tags": [ "Keys API" ], "security": [ { "mgmtToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Webhook id (whk_\u2026)." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "delivered", "failed", "cancelled" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "missing_token or invalid_token (a map key is not a management token).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, or plan_feature_unavailable (the keys API, per-key caps and webhooks are on the platform plan).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "bad_request (including unknown fields in the body).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}/deliveries/{event_id}/redeliver": { "post": { "operationId": "redeliver", "summary": "Send an event again", "description": "Same event id and payload, fresh signature. Scope keys:write.", "tags": [ "Keys API" ], "security": [ { "mgmtToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Webhook id (whk_\u2026)." }, { "name": "event_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Event id (evt_\u2026)." } ], "responses": { "202": { "description": "Queued.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "missing_token or invalid_token (a map key is not a management token).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, or plan_feature_unavailable (the keys API, per-key caps and webhooks are on the platform plan).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "bad_request (including unknown fields in the body).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }