map.name
Throw things into a library, search it, and read what a key is allowed to see, over plain HTTPS or MCP. Everything is private by default, and every call is made with a key you can end at any time.
The map.name API is plain HTTPS. Requests and answers are JSON, addresses are ordinary URLs, and success and failure are told by ordinary HTTP status codes.
A library is private by default. A key reads what its owner has made public, and nothing more unless the owner grants it. A key can add to a library and read from it. It can never publish, delete, or change what is public or private.
The same key works over MCP, so an assistant and a script can share one library. Everything on this page is live.
Run any request from here with your own key and see the real answer, before you write a line of code. Choose a request, fill in what it needs, and press the button.
Reading only ever reads your own library. The one request that writes throws a private note into it, which only you can open.
Each answer shows the status code and the JSON exactly as a program would receive it, and the same request as a command to paste into a terminal.
Send your key on every request, in the Authorization header after the word Bearer. A key starts with mn_ and belongs to one address.
The quickest check that a key works is a call to /v1/me, which answers with the address the key belongs to and what it may do.
All requests go over HTTPS. A request with no key is answered 401 with the error key_missing; one whose key is mistyped, ended or past its date is answered 401 with token_expired.
A key does only what its owner chose for it. Reading what the owner has made public is always allowed.
A key lasts as long as its owner chose, from one day to 365. It can be ended at any moment from Agents (MCP) in the account menu, and it stops working at once.
Choose the least a tool needs. A script that only adds things needs throw:own and nothing else.
A request that fails answers with a 4xx or 5xx status and a JSON body holding an error code and a short detail. The code is for your program; the detail names what to change, such as the field that is missing or the permission the key needs. A refused throw also says state refused.
A request the key may not make is refused, never answered with an empty list: you can always tell nothing was found from nothing was allowed.
A throw that is sent twice should be kept once. Pass an idempotency_key with a throw and a repeat of the same request inside 24 hours answers with the same catch and makes nothing new.
Use any string that is unique to the thing being thrown. If the same key arrives with different content, the answer is 409 idempotency_conflict, so a mistake is never kept silently.
A key may throw 10 times a minute and 500 times a day, counting throws to its own library and to other people together. On top of that, it may send any one person 5 throws a minute and 50 a day. One throw may be up to 25 MB and carry up to 10 tags; one sent to another person may hold up to 16,000 characters.
Reading is generous: a key may read, search and list up to 300 times a minute and 20,000 times a day. Over MCP, an assistant may edit what it put in a library up to 10 times a minute and 200 times a day.
Going over a limit answers 429 rate_limited. Nothing is dropped silently.
Every call a key makes is written to an access log its owner can read. Nothing a key reads from a private library ever reaches a public page.
Put a piece of text into a library. Thrown to the key's own address with throw:own, it is kept at once and answers with its name, as in Kept private at map.name/ada.0k7xq, and is read the way anything else in the library is. Thrown to someone else's address, it arrives in their Messages for them to keep or forget, the way a letter would. That needs throw:other, unless it is someone the owner already writes with.
The fields that say where a throw came from are optional and worth sending: the library shows what an assistant threw by tool and session, so a named session reads as one piece of work.
Ask for something in plain words and get the closest catches the key may read. With read:private the search covers everything the owner has kept; without it, only what is public.
The answer always says how many catches came back, what the limit was, and in one sentence why the list is as long as it is, so a short list can be told from a cut one. It also says how the words were read: a place, a time, a kind or a source in the query becomes a filter. Sent with no words, it answers with nothing and says why.
Read one catch in full, by its short address or its id. The address is the one a throw or a search gave you, with or without the handle in front.
If the address names a page, the page comes back: its title, whether it is Public, Link only or Private, and its blocks in order. A Private or Link only page needs read:private.
Something the key may not read is refused with scope_missing, and nothing about it is revealed.
List what the key can read, newest first, a page at a time. Use it to see what is in a library when you have no words to search for. Search finds one thing; this shows what is there.
The reach is the same as search: a key that reads one collection is shown that collection and what is public, and nothing on the Secret shelf is ever listed.
List the collections the key can see. A key that reads one collection is told about that one and the public ones, and never the name of another private collection.
Returns the address a key belongs to, the name its owner gave it, what it may do and when it stops working. It is the call to make first.
map.name speaks MCP at one address, so an assistant that supports it can use a library with the same key. Give the assistant the address and the key. The For Agents page has the steps for each tool.
Every connection sees the same list of tools. With no key, only the public ones answer: public_library, public_pages, search_public_library, browse_public_collection, read_public_catch and read_public_page. They read what people have made public and nothing else.
With a key, throw, my_key, search_my_library, read_my_catch, my_library, my_collections and update_my_catch answer too, each held to what the key may do exactly as the requests above are. Without one they refuse and say a key is needed. update_my_catch changes an agent-created catch at the same address and keeps its history. Read it first and send its revision as expected_revision; this is required after you edit it yourself. Your private comments appear as owner_comments on read_my_catch, and in my_replies with the session name used for the throw. The assistant needs read:private to see them. Comments wait until it checks; they do not wake a closed session.