# Workspace API

This group covers announcements, resolving and searching references to the workspace's items, and searching the knowledge the caller can read. 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).

## Announcements

| Method | Path | Operation | Summary |
| --- | --- | --- | --- |
| GET | `/api/v1/announcement` | `workspace.announcement.getList` | Lists the announcements the caller can see, filtered and paged. |
| POST | `/api/v1/announcement` | `workspace.announcement.create` | Creates an announcement for the whole workspace or a chosen audience. |
| GET | `/api/v1/announcement/{id}` | `workspace.announcement.get` | Gets an announcement the caller can see. |
| PUT | `/api/v1/announcement/{id}` | `workspace.announcement.update` | Updates an announcement the caller may manage. |
| DELETE | `/api/v1/announcement/{id}` | `workspace.announcement.delete` | Deletes an announcement the caller may manage. |
| POST | `/api/v1/announcement/{id}/confirm-read` | `workspace.announcement.confirmRead` | Confirms that the caller read an announcement that asks for a read confirmation. |
| POST | `/api/v1/announcement/{id}/mark-page-read` | `workspace.announcement.markPageRead` | Records that the caller read an announcement that asks for no reaction. |
| GET | `/api/v1/announcement/{id}/reaction-stats` | `workspace.announcement.getReactionStats` | Gets how the audience of an announcement has responded to it: reads, read confirmations or poll answers. |
| POST | `/api/v1/announcement/poll-vote/{id}` | `workspace.announcement.submitPollVote` | Records the caller's answer to an announcement's poll. |

Request bodies:

- `CreateAnnouncementDto` (`create`): requires `title` (string).
- `UpdateAnnouncementDto` (`update`): requires `title` (string).

## Item references

| Method | Path | Operation | Summary |
| --- | --- | --- | --- |
| POST | `/api/v1/entity-reference/resolve-batch` | `workspace.entityReference.resolveBatch` | Resolves reference tokens to the items they name (title, kind and link), marking the ones the caller cannot open as restricted. |
| GET | `/api/v1/entity-reference/search` | `workspace.entityReference.search` | Searches the items the caller can reference (tasks, pages, files, people and more) by name. |

## Knowledge search

| Method | Path | Operation | Summary |
| --- | --- | --- | --- |
| GET | `/api/v1/knowledge/search` | `workspace.knowledge.search` | Searches the workspace's indexed knowledge the caller can read and returns the best-matching passages. |

## Example

`workspace.announcement.getList`: lists the announcements the caller can see, filtered and paged.

```bash title="curl"
curl -s "https://volobox.example.com/api/v1/announcement?SkipCount=0&MaxResultCount=20" \
  -H "Authorization: Bearer $VOLOBOX_TOKEN"
```

`SkipCount` is how many items to skip and `MaxResultCount` how many to return. The answer carries `totalCount` and the page of `items`.
