> **Draft: Addrexy is not live yet.** It will run at https://addrexy.com as a tenant of the white-label developer portal. In version 1 the portal and its documentation are those of the existing white-label tenant at https://intodq2.devapicloud.com; the API and the documentation are the same. **TBD** marks something not yet decided. **Not documented** marks something the white-label documentation does not say.

# Addrexy for agents

You are an AI agent. These pages are written for you. They are plain text and need no JavaScript.

**What Addrexy is.** Four address APIs, and nothing else: **autocomplete** (suggest addresses as someone types), **verify** (check one address against postal reference data and standardise it; coverage varies by country), **forward geocode** (address to latitude and longitude) and **reverse geocode** (latitude and longitude to address). They are building blocks for an application to call, not a business service.

## Which API do you need?

| You have or want | Call | Endpoint |
|---|---|---|
| Someone is typing an address into a field | Autocomplete | `POST /autocomplete/suggest` |
| An address that was entered, to standardise and verify it | Verify | `POST /address/verify` |
| An address, and you need latitude and longitude | Forward geocode | `POST /address/geocode` |
| Latitude and longitude, and you need the address | Reverse geocode | `POST /address/reverse-geocode` |
| A shipping address to check and plot on a map | Verify, then forward geocode | pass the verified `address.components` into geocode |

Best results: autocomplete as the user types, verify what they chose, geocode the verified address if you need coordinates. Every endpoint is under `https://api.devapicloud.com/v1`.

## Which are you?

| You are | Your path |
|---|---|
| **Helping a developer** who is writing or reviewing code. A human is in the loop. | [Start](https://addrexy.com/agent/start): ask your human to create an API key and secret in the portal and give them to you. Then [Build](https://addrexy.com/agent/build) and [Operate](https://addrexy.com/agent/operate). |
| **An independent agent with your own budget** and no human. | **Not supported yet.** Keys and credits are issued by a person through the portal. See [Start](https://addrexy.com/agent/start) for what to do and what to report. |

## The pages

| Page | You will |
|---|---|
| [/agent/start](https://addrexy.com/agent/start) | Learn how access works, get credentials from a person, and make a first call |
| [/agent/build](https://addrexy.com/agent/build) | Call the four APIs, act on every `matchScore`, and read coordinates correctly |
| [/agent/operate](https://addrexy.com/agent/operate) | Run it: errors, retries, rate limits, audit log, when to hand back |
| [/agent/coverage](https://addrexy.com/agent/coverage) | Check which countries each service covers (also [/coverage.json](https://addrexy.com/coverage.json)) |

## Three rules

1. **Credentials come from a person.** You cannot create an account or a key yourself. Never put the key or secret in browser code, logs or source control.
2. **Branch on `matchScore`** (0 to 5) from verify and from geocode. There is no confidence percentage; do not compute one. Autocomplete does not verify: verify what the user chose. A geocode point is only as good as its `locationType`: a high score at postcode depth is not a building.
3. **Send `X-Session-Token` (a UUID v4) on every call, and log the request id.** It is the `X-Request-Id` response header. Autocomplete also returns it in `requestId`, and verify and geocode in `result.meta.requestId`.

## Where things live

| What | Address |
|---|---|
| These pages | `https://addrexy.com/agent/...` (**TBD**: whether the platform can host them) |
| The API | `https://api.devapicloud.com/v1` |
| The human documentation (version 1) | https://intodq2.devapicloud.com/assets/developer-portal.html |
| MCP server (planned; a thin pass-through) | **TBD** |

## Words used on these pages

| Word | Meaning |
|---|---|
| **API key and secret** | Two values a person creates in the portal. Together they authenticate every call. |
| **Credits** | What a call draws down. An administrator allocates them. Cost per call and what happens at zero are not documented. |
| **Customer** | A level of user in the portal (Administrator, Customer, Department). It is not the same as the customers whose addresses you check. |
| **`X-Session-Token`** | A UUID v4 header that groups related calls. Required on every call. |
| **`matchScore`** | Integer 0 to 5 from verify and geocode. 5 is the strongest match. 0 is no match. |
| **`matchDetails`** | How the score was reached: how deep the match went and what happened to each component. |
| **Geocode** | Forward: address to coordinates. Reverse: coordinates to address. |
| **Centroid** | The middle of an area such as a postcode or town. A point there is not an address. |
| **Headless** | No person is available to answer a question during your task. |
| **Request id** | The correlation id for a call. Quote it when you report a problem. |

## Not for you

The portal's demo page and "Try It Out" buttons are for people.

## Machine-readable

[/llms.txt](https://addrexy.com/llms.txt) · [/openapi.json](https://addrexy.com/openapi.json) · [/.well-known/ai-catalog.json](https://addrexy.com/.well-known/ai-catalog.json)