{"openapi":"3.1.0","info":{"title":"PDMFácil Agent API","version":"1.0.0","description":"Portuguese planning results by confirmed WGS84 coordinates. One prepaid credit per successful PDM classification. Owner funds credits at /developers. Preserve source warnings; not a municipal certificate."},"servers":[{"url":"https://pdmfacil.pt"}],"externalDocs":{"url":"https://pdmfacil.pt/agent-guide"},"components":{"securitySchemes":{"AgentKey":{"type":"http","scheme":"bearer","description":"Revocable, budget-limited key created by the account owner at /developers."}}},"paths":{"/api/v1/agent":{"post":{"operationId":"pdmfacilAgent","summary":"Discover coverage, locate a point, inspect billing or obtain a paid PDM result","security":[{"AgentKey":[]},{}],"description":"coverage and billing allow anonymous requests. search_locations, resolve_location and query_pdm require a bearer key. query_pdm consumes 1 credit only for a PDM classification. Retries must reuse idempotency_key with identical coordinates; replay is free and contains the original balance snapshot. Failed/estimate-only calls are not charged or persisted and may be retried.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["operation","arguments"],"properties":{"operation":{"const":"coverage"},"arguments":{"type":"object","properties":{"municipality":{"type":"string","maxLength":100,"description":"Slug opcional, por exemplo leiria."}},"required":[],"additionalProperties":false}}},{"type":"object","additionalProperties":false,"required":["operation","arguments"],"properties":{"operation":{"const":"billing"},"arguments":{"type":"object","properties":{},"required":[],"additionalProperties":false}}},{"type":"object","additionalProperties":false,"required":["operation","arguments"],"properties":{"operation":{"const":"search_locations"},"arguments":{"type":"object","properties":{"query":{"type":"string","description":"Morada ou localidade, incluindo o concelho.","minLength":2,"maxLength":120}},"required":["query"],"additionalProperties":false}}},{"type":"object","additionalProperties":false,"required":["operation","arguments"],"properties":{"operation":{"const":"resolve_location"},"arguments":{"type":"object","properties":{"query":{"type":"string","description":"Texto display do candidato.","minLength":2,"maxLength":120},"magicKey":{"type":"string","minLength":1,"maxLength":2048,"description":"magicKey recebido em search_locations, quando disponível."}},"required":["query"],"additionalProperties":false}}},{"type":"object","additionalProperties":false,"required":["operation","arguments"],"properties":{"operation":{"const":"query_pdm"},"arguments":{"type":"object","properties":{"lat":{"type":"number","minimum":36.9,"maximum":42.2},"lng":{"type":"number","minimum":-9.6,"maximum":-6.1},"idempotency_key":{"type":"string","pattern":"^[a-zA-Z0-9._:-]{8,128}$","description":"Identificador único de 8–128 caracteres. Mesmo identificador e ponto repetem o resultado sem nova cobrança."}},"required":["lat","lng","idempotency_key"],"additionalProperties":false}}}]}}}},"responses":{"200":{"description":"Result: coordinates, classification, parameters when available, warnings, sources, timestamp and credits_charged; or free operation data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid arguments","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing, revoked or expired key","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"402":{"description":"Account balance or key budget exhausted; billing_url is a human checkout handoff, not x402.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Origin rejected","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"409":{"description":"Idempotency key already used for different coordinates","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"413":{"description":"Body exceeds 8 KiB","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"415":{"description":"Use application/json","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Rate limit; retry after 60 seconds","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"503":{"description":"Service temporarily unavailable; retry with the same idempotency key","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}}}}