# Agenda API

This group covers the caller's agenda: agenda items and the tasks, requests and other items they link to, recurring agenda items, and the agenda requests people send each other. Every call acts as a person: send a personal access token, or an OAuth access token from a person's sign-in (scope `Volobox`). An integration app's own client secret is refused with `403` (`Volobox:Integrations:MemberConnectionRequired`). Paths, tokens and conventions are in [API overview](/docs/api-overview).

## Agenda items

| Method | Path | Operation | Summary |
| --- | --- | --- | --- |
| GET | `/api/v1/agenda-item` | `agenda.agendaItem.getList` | Lists the caller's agenda items for a date range. |
| POST | `/api/v1/agenda-item` | `agenda.agendaItem.create` | Creates an agenda item for the caller. |
| GET | `/api/v1/agenda-item/{id}` | `agenda.agendaItem.get` | Gets one of the caller's agenda items. |
| PUT | `/api/v1/agenda-item/{id}` | `agenda.agendaItem.update` | Changes an agenda item's title, date, time or other fields. |
| DELETE | `/api/v1/agenda-item/{id}` | `agenda.agendaItem.delete` | Deletes an agenda item. |
| POST | `/api/v1/agenda-item/{id}/convert-to-recurring` | `agenda.agendaItem.convertToRecurring` | Turns an agenda item into a recurring one. |
| POST | `/api/v1/agenda-item/{id}/create-task` | `agenda.agendaItem.createTaskFromAgendaItem` | Creates a task in a project from an agenda item and links the two. |
| POST | `/api/v1/agenda-item/{id}/links` | `agenda.agendaItem.addLink` | Links an agenda item to a task, request or other item. |
| DELETE | `/api/v1/agenda-item/{id}/links/{linkId}` | `agenda.agendaItem.unlink` | Removes a link from an agenda item. |
| POST | `/api/v1/agenda-item/{id}/move-scheduled` | `agenda.agendaItem.moveScheduledItem` | Moves a scheduled agenda item to another day at the same time of day. |
| POST | `/api/v1/agenda-item/{id}/set-status` | `agenda.agendaItem.setStatus` | Sets the status of an agenda item. |
| POST | `/api/v1/agenda-item/for-link-targets` | `agenda.agendaItem.getForLinkTargets` | Lists the caller's agenda items linked to the given tasks, requests or other items. |
| POST | `/api/v1/agenda-item/from-link` | `agenda.agendaItem.createFromLink` | Creates an agenda item linked to a task, request or other item. |
| POST | `/api/v1/agenda-item/reorder-day` | `agenda.agendaItem.reorderDay` | Puts the unscheduled agenda items of a day in the given order, moving any from other days. |
| GET | `/api/v1/agenda-item/team-member/{userId}` | `agenda.agendaItem.getListForTeamMember` | Lists a teammate's agenda for a date range, as far as the caller may see it. |
| GET | `/api/v1/agenda-item/vacations` | `agenda.agendaItem.getVacationDays` | Lists the caller's vacation days in a date range, as the agenda shows them. |

Request bodies:

- `CreateAgendaItemDto` (`create`): requires `date` (date (yyyy-MM-dd)), `text` (string).
- `UpdateAgendaItemDto` (`update`): requires `date` (date (yyyy-MM-dd)), `text` (string).
- `CreateTaskFromAgendaItemDto` (`createTaskFromAgendaItem`): requires `title` (string).
- `CreateAgendaItemFromLinkDto` (`createFromLink`): requires `date` (date (yyyy-MM-dd)), `kind` (AgendaItemLinkKind: ProjectTask, Meeting, PullRequest, ProjectRequest, AgendaItemRequest, AppRecord, AppPublishRequest), `targetId` (uuid).

## Agenda requests

| Method | Path | Operation | Summary |
| --- | --- | --- | --- |
| POST | `/api/v1/agenda-item-request` | `agenda.agendaItemRequest.create` | Asks a teammate to put something on their agenda. |
| GET | `/api/v1/agenda-item-request/{id}` | `agenda.agendaItemRequest.get` | Gets an agenda request the caller sent or received. |
| POST | `/api/v1/agenda-item-request/{id}/accept` | `agenda.agendaItemRequest.accept` | Accepts an agenda request, adding it to the caller's agenda. |
| POST | `/api/v1/agenda-item-request/{id}/accept-as-task` | `agenda.agendaItemRequest.acceptAsTask` | Accepts an agenda request as a task in a project. |
| POST | `/api/v1/agenda-item-request/{id}/forward` | `agenda.agendaItemRequest.forward` | Forwards an agenda request sent to the caller to another teammate. |
| POST | `/api/v1/agenda-item-request/{id}/ignore` | `agenda.agendaItemRequest.ignore` | Ignores an agenda request sent to the caller. |
| GET | `/api/v1/agenda-item-request/pending` | `agenda.agendaItemRequest.getPendingList` | Lists the agenda requests waiting for the caller's answer. |
| GET | `/api/v1/agenda-item-request/pending-count` | `agenda.agendaItemRequest.getPendingCount` | Counts the agenda requests waiting for the caller's answer. |
| GET | `/api/v1/agenda-item-request/sent` | `agenda.agendaItemRequest.getSent` | Lists the agenda requests the caller sent, one page at a time. |

Request bodies:

- `CreateAgendaItemRequestDto` (`create`): requires `recipientUserId` (uuid), `text` (string).

## Recurring agenda items

| Method | Path | Operation | Summary |
| --- | --- | --- | --- |
| GET | `/api/v1/recurring-agenda-item/{id}` | `agenda.recurringAgendaItem.get` | Gets one of the caller's recurring agenda items. |
| PUT | `/api/v1/recurring-agenda-item/{id}` | `agenda.recurringAgendaItem.update` | Changes a recurring agenda item and its schedule. |
| DELETE | `/api/v1/recurring-agenda-item/{id}` | `agenda.recurringAgendaItem.delete` | Deletes a recurring agenda item with all its occurrences. |
| PUT | `/api/v1/recurring-agenda-item/{id}/occurrence` | `agenda.recurringAgendaItem.updateOccurrence` | Changes one occurrence of a recurring agenda item without changing the others. |
| POST | `/api/v1/recurring-agenda-item/{id}/occurrence/cancel` | `agenda.recurringAgendaItem.cancelOccurrence` | Cancels one occurrence of a recurring agenda item. |
| POST | `/api/v1/recurring-agenda-item/{id}/occurrence/restore` | `agenda.recurringAgendaItem.restoreOccurrence` | Restores a cancelled occurrence of a recurring agenda item. |

Request bodies:

- `UpdateRecurringAgendaItemDto` (`update`): requires `recurrence` (AgendaRecurrenceInputDto), `text` (string).
- `UpdateAgendaOccurrenceDto` (`updateOccurrence`): requires `occurrenceStartUtc` (date-time), `text` (string).

## Example

`agenda.agendaItem.getList`: lists the caller's agenda items for a date range.

```bash title="curl"
curl -s "https://volobox.example.com/api/v1/agenda-item" \
  -H "Authorization: Bearer $VOLOBOX_TOKEN"
```
