# Quickstart

> From a new API key to your first undone change in five calls.

You need a key with **Trips: read and write** (Integrations → API & MCP). Put it in your shell:

```bash
export BYMUNDI_KEY=bym_live_...
```

Each block below starts with the status it should answer. Replace nothing else: the variables are set as you go.

## 1. Check the key

```bash
# expect 200
curl https://api.bymundi.com/v1/me \
  -H "Authorization: Bearer $BYMUNDI_KEY"
```

The answer names you, your agency and the key's permissions.

## 2. Create a trip

```bash
# expect 201, save TRIP_ID from .id
curl -X POST https://api.bymundi.com/v1/trips \
  -H "Authorization: Bearer $BYMUNDI_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"title":"My first API trip","startDate":"2027-05-01","endDate":"2027-05-04"}'
```

Copy the `id` from the answer: `export TRIP_ID=<id>`. The `Idempotency-Key` makes the call [safe to retry](https://api.bymundi.com/docs/guides/idempotency-and-retries.md).

## 3. Add a note to its itinerary

```bash
# expect 200, save CHANGE_ID from header Bymundi-Change-Id
curl -i -X POST https://api.bymundi.com/v1/trips/$TRIP_ID/itinerary/ops \
  -H "Authorization: Bearer $BYMUNDI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ops":[{"op":"add","type":"texto","parentId":null,"position":"end","clientId":"hello"}]}'
```

`-i` prints the headers: copy `Bymundi-Change-Id` into `export CHANGE_ID=<id>`. Open the trip in bymundi: the note is there. How the itinerary tree works: [Itineraries](https://api.bymundi.com/docs/guides/itineraries.md).

## 4. Undo it

```bash
# expect 200
curl -X POST https://api.bymundi.com/v1/changes/$CHANGE_ID/revert \
  -H "Authorization: Bearer $BYMUNDI_KEY"
```

The note is gone. The same change also appears in the app under Integrations → API & MCP → Activity, with its own Undo.

## 5. Archive the trip

```bash
# expect 200
curl -X DELETE https://api.bymundi.com/v1/trips/$TRIP_ID \
  -H "Authorization: Bearer $BYMUNDI_KEY"
```

Archiving is undoable too (`POST /v1/trips/{tripId}/restore`).

## Next

- [Authentication](https://api.bymundi.com/docs/guides/authentication.md) and [permissions](https://api.bymundi.com/docs/guides/permissions.md)
- [Errors](https://api.bymundi.com/docs/guides/errors.md) — what a refusal looks like
- [Connect an AI assistant](https://api.bymundi.com/docs/mcp/clients.md)
- [Get notified with webhooks](https://api.bymundi.com/docs/guides/webhooks.md)