# Endpoints

Every HTTP endpoint a program can call, with auth, purpose and a link to the page that explains it. The machine-readable form is /openapi.json.

Base URL `https://tapmy.link`. JSON bodies, JSON responses. Auth is `Authorization: Bearer <key>` unless marked *none*. The OpenAPI 3.0 document at [https://tapmy.link/openapi.json](https://tapmy.link/openapi.json) is generated from the same validation schemas the server runs.

## Create and discover

| Method and path | Auth | Does |
| --- | --- | --- |
| `GET /api/username/check?u=<name>` | none | `free` / `taken` (+ suggestions) / `invalid` (+ reason). |
| `POST /api/agent/pages` | none or key | Account (if needed) + page + key + claim link. [Quickstart](https://tapmy.link/documentation/agents/quickstart.md). |
| `POST /api/agent/pages/validate` | none | Same body, nothing written; every problem at once. |
| `GET /api/agent/me` | key | The account, its pages, remaining page slots. |
| `POST /api/agent/claim-link` | key | A fresh claim link for a provisional account. |
| `GET /api/claim/<token>` | none | Claim status: `pending`, `claimed`, `expired`, `invalid`. |

## Pages

| Method and path | Auth | Does |
| --- | --- | --- |
| `GET /api/profiles` | key | All pages of the account. |
| `POST /api/profiles` | key | Claim another subdomain on the account: `{ username, templateId? }`. |
| `GET /api/profiles/{id}` | key | One page, every editable field. |
| `PATCH /api/profiles/{id}` | key | Change any subset of fields. `blocks` replaces the list. |
| `PUT /api/profiles/{id}` | key | Replace every editable field (what the editor does on autosave). |
| `DELETE /api/profiles/{id}` | key | Delete the page and its files; the name is parked. |
| `GET /api/profiles/{id}/stats` | key | Views, uniques, taps; daily series. [Statistics](https://tapmy.link/documentation/agents/statistics.md). |

## Images and imports

| Method and path | Auth | Does |
| --- | --- | --- |
| `POST /api/upload` | key | JSON `{ url, kind }` or multipart `file` + `kind` → a storage key. [Images](https://tapmy.link/documentation/agents/images.md). |
| `POST /api/import/page` | key | Links found on a public link page. [Import](https://tapmy.link/documentation/agents/import.md). |
| `POST /api/import/instagram` | key | Photo, name and bio from an Instagram handle. |

## Account

| Method and path | Auth | Does |
| --- | --- | --- |
| `GET /api/account` | key | E-mail, language, creation date. |
| `PATCH /api/account` | key | `{ locale }`; password change needs the current password. |
| `GET /api/account/export` | key | Everything stored about the account, as JSON. |
| `GET /api/keys` · `POST /api/keys` · `DELETE /api/keys/{id}` | browser session only | Keys are managed by a person, never by a key. |

## Public, per page

| Path | Does |
| --- | --- |
| `https://<name>.tapmy.link/page.md` | The page as Markdown. Also `/?format=md` or `Accept: text/markdown`. |
| `https://<name>.tapmy.link/<path>` | A short link, counted and redirected. |

## Headers worth sending

| Header | Why |
| --- | --- |
| `Idempotency-Key` | On `POST /api/agent/pages`: a retry with the same key replays the first answer instead of making a second page. |
| `User-Agent` | Stored on accounts and pages you create; shown to the owner as "created by …". |

---
Part of the [Tapmy.link agent documentation](https://tapmy.link/documentation/agents.md). Canonical: https://tapmy.link/documentation/agents/endpoints.md