<!-- DRAFT. Not published. Addrexy is not live. The pages and files below will be served from https://addrexy.com if the platform allows (TBD). In version 1 the portal and human documentation are those of https://intodq2.devapicloud.com.
     Format follows llmstxt.org: one H1, a blockquote summary, then H2 sections of "- [name](url): note" lines. -->
# Addrexy

> Address APIs for software: autocomplete (suggest addresses as someone types), verify (check one address against postal reference data and standardise it), forward geocode (address to latitude and longitude) and reverse geocode (latitude and longitude to address). Runs on a white-label developer portal. A person creates the API key and secret; an agent cannot create an account.

Notes for agents:
- The pages written for you start at /agent. They are plain text and need no JavaScript.
- Credentials come from a person, through the portal. There is no agent sign-up and no anonymous access.
- Verify and geocode return matchScore 0 to 5. There is no confidence percentage. Branch on matchScore, and act on the rules in /agent/build.
- Autocomplete does not verify. Verify what the user chose. A geocode point at postcode or town level is a centroid, not an address.
- Every call needs Basic authentication and an X-Session-Token (a UUID v4).

## Start here
- [Agent home](https://addrexy.com/agent): what Addrexy is, which API you need, three rules, a glossary
- [Get access](https://addrexy.com/agent/start): how a person gets you a key and secret, how to authenticate, a first call
- [Build against it](https://addrexy.com/agent/build): all four APIs, requests and responses, what to do for each matchScore, where the documentation contradicts itself
- [Operate it](https://addrexy.com/agent/operate): errors, retries, rate limits, audit log, when to hand back to a human
- [Country coverage](https://addrexy.com/agent/coverage): which countries each service covers, one row per country; also as [JSON](https://addrexy.com/coverage.json)

## API
- [OpenAPI spec](https://addrexy.com/openapi.json): the machine-readable contract (base URL https://api.devapicloud.com/v1)
- [MCP server card](https://mcp.addrexy.example/mcp/server-card): connection details for the planned pass-through MCP server (host TBD)
- [AI catalog](https://addrexy.com/.well-known/ai-catalog.json): domain-level discovery; points to the server card

## Docs
- [Portal documentation](https://intodq2.devapicloud.com/assets/developer-portal.html): the human documentation for all four APIs (version 1 location; the same documentation will serve Addrexy)

## Optional
- [About](https://addrexy.com/about.md): what the name means