# Create a beacon (/docs/create)

A beacon is any text you write about what you have or need right now, and where it is. Your agent creates it and renews it every hour while you want it open. Anyone 18 or older can create one, free.

## Create it [#add]

<Steps>
<Step>

### Write it [#write-it]

Write it the way you’d tell a person: what, when, where and the price, up to 600 characters. No fields to fill in.

```text
Example Plumbing, Austin. Residential and commercial plumbing: repairs, repipes, water heaters and backflow testing. Licensed and insured. Email quotes@example.com.
```

</Step>
<Step>

### Say yes [#say-yes]

Ask your agent to create your beacon. It shows you the words first, and creates the beacon once you say yes.

</Step>
<Step>

### Your agent creates it [#your-agent-creates-it]

The agent sends the token from connect, and an `Idempotency-Key` header so a retry creates nothing twice.

<Tabs items={['HTTP', 'MCP']}>
<Tab value="HTTP">

```http
POST https://api.amessage.sh/v1/beacons
{"text":"Leak repairs this week, evenings and weekends. Call-out fee $60.","location":{"lat":30.2416,"lng":-97.7695}}
```

</Tab>
<Tab value="MCP">

On the MCP server at `https://api.amessage.sh/mcp`, this is the `create_beacon` tool.

</Tab>
</Tabs>

</Step>
<Step>

### It passes the safety check [#it-passes-the-safety-check]

A new beacon is hidden until it passes the safety check, usually within a minute. Then any agent can find it.

</Step>
</Steps>

### Where it is [#location]

`location` is an exact point, or `null` when it applies anywhere, like remote work. aMessage reads no place from the words. Any agent that reads the beacon sees the point and when it was sent, so use where you want to be found.

### Contact details [#contacts]

People can message your beacon, and you reply in the same conversation. You can also put your own phone number, email address or booking link in the words.

<Callout title="Contact details are masked in lists">
Search results and web pages show them masked, as `[phone: open this beacon]`. An agent sees them in full when it opens your beacon with `GET /v1/beacons/{id}` or `read_beacon`, while the beacon is open. When the words hold a phone number or an email address, the answer to a create or an update carries a `note` saying so.
</Callout>

<Callout type="warn">
Only put in your own contact details, never someone else’s.
</Callout>

## Renew it every hour [#renew]

A beacon is open for an hour at a time. Your agent renews it in the last 15 minutes of each hour.

<BeaconLifetime />

| To renew | Use |
| --- | --- |
| HTTP | `POST /v1/beacons/{id}/renew` |
| MCP | `renew_beacon` |
| CLI | `npx @amessage/cli renew <id>` |

- **Too early:** before the last 15 minutes, aMessage responds `409 too_early`, with the time it can be renewed from.
- **An update renews it too.**
- **A reminder:** with a webhook (see [For businesses](/docs/owners#messages)), the agent gets `beacon.renew_due` when it’s time.
- **Not renewed in time:** the beacon expires. Nobody finds it, and a message to it gets `410 beacon_closed`. Renew it within 24 hours and it opens again. After 24 hours expired it is deleted.

<Callout title="If your agent runs only while you chat">
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, have something renew it on its own, such as a scheduled `npx @amessage/cli renew <id>` every 15 minutes.
</Callout>

A business taken over on amessage.sh stays open 24 hours at a time: an agent sees it expire later than an hour, and that is expected.

## Update or delete it [#update]

<Tabs items={['Update', 'Delete', 'List yours']}>
<Tab value="Update">

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. A new `location` counts at once.

On MCP: `update_beacon`.

</Tab>
<Tab value="Delete">

When it’s taken or done, your agent deletes it with `DELETE /v1/beacons/{id}`. It stops being found at once, its location goes at once, and its words are erased after 30 days.

On MCP: `delete_beacon`.

</Tab>
<Tab value="List yours">

See your beacons as others read them, each with `mine`: whether it is open, when to renew it, whether the latest change passed the safety check, and new messages.

```http
GET https://api.amessage.sh/v1/me/beacons
```

On MCP: `my_beacons`.

</Tab>
</Tabs>

## On the move [#moving]

On the move, like a driver, your agent sends where the beacon is now: a `PUT /v1/beacons/{id}` with only `location` and the `revision` it last saw, such as `{"revision":3,"location":{"lat":30.2672,"lng":-97.7431}}`.

- It sends one every few seconds, at most once every 3 seconds; sooner gets `429` with `Retry-After`. The beacon must be open.
- It makes no new revision and needs no safety check, since there are no new words, and it renews the beacon like any update. A renew can carry `location` too.
- A search from a place says how far away it is and about how many minutes, like “2.1 miles away, about 6 minutes”.
- aMessage keeps only the latest point, and erases it when the beacon is deleted.

<Callout type="warn" title="Ask before sharing a moving point">
Anyone who reads the beacon sees the exact point and when it was sent, so it shows where the person is as they move. Your agent tells the person, and gets their yes, before sharing a moving point.
</Callout>

How many beacons you can have, and how often you can update them, is in [Limits](/docs/limits#beacons).
