# Calendar

Source: https://wire.ia.br/documentation/en/api/agenda

> Read, create and delete events in the "Paper" Google Calendar.



The API only touches the calendar called **Paper**, which the app itself creates in the person's Google Calendar. Their other calendars stay out of reach.

Before using it:

1. The person connects Google Calendar in **Settings → Integrations**.
2. In **Settings → Developer**, they tap **Allow the "Paper" calendar for the API**.
3. The token needs the calendar permission. Secure tokens don't access the calendar.

Without the first two steps, the API answers `409`.

## List events [#list-events]

```http
GET /calendar/events?from=2026-10-01&to=2026-10-31
```

`from` and `to` accept a date or a date and time in ISO 8601. Without `from`, it starts now. Without `to`, it goes 30 days past `from`. Returns up to 250 events, in order of start.

```json
[
  {
    "id": "k9d8f7g6h5j4",
    "titulo": "Dentist",
    "descricao": null,
    "inicio": { "dateTime": "2026-10-06T14:00:00-03:00", "timeZone": "America/Sao_Paulo" },
    "fim": { "dateTime": "2026-10-06T15:00:00-03:00", "timeZone": "America/Sao_Paulo" }
  }
]
```

All-day events come with `{ "date": "2026-10-06" }` in `inicio` and `fim`.

## Create an event [#create-an-event]

```http
POST /calendar/events
Content-Type: application/json
```

```json
{
  "title": "Deliver report",
  "date": "2026-10-08",
  "time": "09:30",
  "durationMinutes": 45,
  "description": "Final version, with the charts.",
  "timeZone": "America/New_York"
}
```

| Field             | Required | Rules                                                    |
| ----------------- | -------- | -------------------------------------------------------- |
| `title`           | No       | Up to 300 characters. Empty becomes "Event".             |
| `date`            | Yes      | `YYYY-MM-DD`.                                            |
| `time`            | No       | `HH:MM`, 24 hours. Without a time, the event is all-day. |
| `durationMinutes` | No       | From 5 to 1440. Default: 60.                             |
| `description`     | No       | Up to 4000 characters.                                   |
| `timeZone`        | No       | IANA time zone. Default: `America/Sao_Paulo`.            |

Response: `{ "id": "…" }`. Needs the **Read and create events** permission.

## Delete an event [#delete-an-event]

```http
DELETE /calendar/events/{id}
```

Only deletes events in the "Paper" calendar. Needs the **Read and create events** permission.

## Common sense [#common-sense]

Create events the person asked for or that come from their notes. Don't fill the calendar with repeated reminders or use the calendar as a system's task queue.