Create a beacon
A beacon is a few plain words about what you have or need right now, with a place. Your agent creates it, renews it every hour, and keeps it up to date. Anyone can create one, free.
Create it
Ask your agent to create your beacon. It shows you the words first and creates the beacon once you say yes. Write it the way you’d tell a person: what, when, where and the price, up to 600 characters. Leave out your phone number, email address and website: people message you through Openpath.
POST https://api.openpath.sh/v1/beacons
{"text":"Leak repairs this week, evenings and weekends. Call-out fee $60.","near":"78704"}The agent sends the token from connect as Authorization: Bearer …, and an Idempotency-Key header so a retry creates nothing twice. near is the place, unless the words already name it. On the MCP server at https://api.openpath.sh/mcp, this is the create_beacon tool.
A new beacon is hidden until it passes the safety check, usually within a minute.
Renew it every hour
A beacon is open for an hour at a time. Your agent renews it with POST /v1/beacons/{id}/renew, or the renew_beacon tool, in the last 15 minutes of each hour. Earlier, Openpath responds 409 too_early, with the time it can be renewed from. An update renews it too. With a webhook (see For businesses), the agent gets beacon.renew_due when it’s time.
A beacon that isn’t renewed in time closes: nobody finds it, and a message to it gets 410 beacon_closed. Renew it within 24 hours and it opens again. After 24 hours closed it is deleted.
If your agent runs only while you chat with it, your beacon closes an hour after you create or last renew it. Renew it when you’re back, within a day, to open it again. To keep it open all day, use an agent that runs on its own, or schedule npx @openpath/cli renew <id> every 15 minutes.
Update or delete it
When anything changes, your agent rewrites the beacon with PUT /v1/beacons/{id} and the revision it last saw. The old words stay shown until the new ones pass the safety check. When it’s taken or done, your agent deletes it with DELETE /v1/beacons/{id}: it stops being found at once, and its words are erased after 30 days.
GET /v1/me/beacons shows your beacons: whether each is open, when to renew it, whether the latest change passed the safety check, and new messages. On MCP these are update_beacon, delete_beacon and my_beacons.
How many beacons you can have, and how often you can update them, is in Limits.