# SnapHop Maps

> SnapHop Maps makes interactive web maps -- an OpenFreeMap basemap with up to 500 plain-text markers -- and publishes each one at a stable link and as HTML to embed in any web page. This guide is for AI agents: how to open an account, create a map and publish it over HTTP and JSON, with no browser, email address or password.

Published maps are served from https://maps-cdn.snaphop.ai, not from this host, and keep working whatever happens here.

## Open an account

Any agent may open an account here; no person has to approve it.

```http
POST https://maps.snaphop.ai/api/agents
Content-Type: application/json

{"name": "Your agent's name"}
```

The answer, `201`, carries `apiKey`: the account's only credential, shown this once. Send it on every other request as `Authorization: Bearer <apiKey>`. It works until `expiresAt`, about 30 days; before then, `POST https://maps.snaphop.ai/api/admin/v1/agent/key` with it answers with a new `apiKey` and stops the old one. There is no password and no recovery: an agent whose key is lost or expired registers again, as a new account.

The account has a workspace of its own. Its key reads, creates, publishes and withdraws maps there, and does nothing else.

## Create and publish a map in one request

```http
POST https://maps.snaphop.ai/api/admin/v1/maps?publish=true
Authorization: Bearer <apiKey>
Content-Type: application/json

{
  "name": "Coffee in Lisbon",
  "style": "positron",
  "markers": [
    {"position": [-9.1427, 38.7107], "title": "A Brasileira", "description": "Open since 1905"},
    {"position": [-9.1365, 38.7139], "title": "Fabrica Coffee Roasters", "color": "#b5452b"}
  ]
}
```

- `position` is `[longitude, latitude]`: longitude first.
- `name` and each `title` are 1 to 120 characters; a `description` is at most 1000 and may have line breaks; a `color` is `#rrggbb`. All of it is plain text and is never read as HTML or Markdown.
- `style` is one of `liberty`, `bright`, `positron`, `dark`, `fiord`. Leave it out for `liberty`.
- Leave `view` out and the map opens on all of its markers.
- A map holds at most 500 markers, and an agent's workspace at most 25 maps.

The answer, `201`, has the map's `id` and, under `published`, `page` -- the link to give a person -- and `embedScript` and `embedFrame`, HTML to paste into a web page. If publication was refused, `published` is `null` and `publicationError` says why; the map is kept as a draft, and `POST https://maps.snaphop.ai/api/admin/v1/maps/<id>/publications` publishes it.

A definition that cannot be saved answers `422` `MAP_INVALID`, with every refused field under `error.fields` by its path, such as `markers[3].position`.

## Change a map

1. `GET https://maps.snaphop.ai/api/admin/v1/maps/<id>` answers with its `draft` and `draftVersion`.
2. `PUT https://maps.snaphop.ai/api/admin/v1/maps/<id>` with `{"draftVersion": <draftVersion>, "definition": <the whole changed draft>}` saves it. A `draftVersion` that is no longer current answers `409` `DRAFT_CHANGED`: read the map again and redo the change.
3. `POST https://maps.snaphop.ai/api/admin/v1/maps/<id>/publications` publishes it. The link and every embed show the new release within about a minute.

`GET https://maps.snaphop.ai/api/admin/v1/maps` lists the workspace's maps. `DELETE https://maps.snaphop.ai/api/admin/v1/maps/<id>` withdraws one: its link and every embed stop showing it, and it cannot be undone.

## MCP

`https://maps.snaphop.ai/mcp` is an MCP server -- Streamable HTTP, stateless, JSON responses -- whose tools are `register_agent`, `create_map`, `list_maps`, `get_map`, `update_map`, `publish_map`, `withdraw_map` and `replace_key`. Send the key as `Authorization: Bearer <apiKey>`, or, where the client cannot set a header, as each tool's `apiKey` argument.

## Errors and limits

Every refusal answers `{"error": {"code": "...", "message": "..."}, "requestId": "..."}`. `429` means wait and try again later: registration is counted per client address and per day, and an agent's publications, rollbacks and withdrawals per workspace. A request to `/api/admin/v1/` without a key is redirected to the sign-in page.

## Reference

- [OpenAPI description](https://maps.snaphop.ai/openapi.yaml): every route, its body and its answers
- [Sign in](https://maps.snaphop.ai/): for people with a workspace