# Docs API

This group covers Docs spaces and their pages: space and page members, the page tree, page content and revisions, Trash, stars and search. 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).

## Docs spaces

| Method | Path | Operation | Summary |
| --- | --- | --- | --- |
| GET | `/api/v1/docs` | `docs.getList` | Lists the Docs spaces the caller can open. |
| POST | `/api/v1/docs` | `docs.create` | Creates a Docs space with the caller as its admin. |
| GET | `/api/v1/docs/{id}` | `docs.get` | Gets a Docs space the caller can open. |
| PUT | `/api/v1/docs/{id}` | `docs.update` | Updates a Docs space the caller administers. |
| DELETE | `/api/v1/docs/{id}` | `docs.delete` | Moves an archived Docs space to Trash. |
| POST | `/api/v1/docs/{id}/archive` | `docs.archive` | Archives a Docs space, hiding it and its pages everywhere until it is restored. |
| DELETE | `/api/v1/docs/{id}/permanent` | `docs.deletePermanently` | Permanently deletes a Docs space in Trash with all its pages. |
| POST | `/api/v1/docs/{id}/restore` | `docs.restore` | Restores an archived Docs space. |
| POST | `/api/v1/docs/{id}/restore-from-trash` | `docs.restoreFromTrash` | Restores a Docs space from Trash to the archive. |
| PUT | `/api/v1/docs/{id}/star` | `docs.starSpace` | Stars or unstars a Docs space for the caller. |
| GET | `/api/v1/docs/{spaceId}/members` | `docs.getMembers` | Lists the members of a Docs space. |
| POST | `/api/v1/docs/{spaceId}/members` | `docs.addMember` | Adds a person, group or agent to a Docs space with a role. |
| PUT | `/api/v1/docs/{spaceId}/members/{memberId}` | `docs.updateMember` | Changes the role of a member of a Docs space. |
| DELETE | `/api/v1/docs/{spaceId}/members/{memberId}` | `docs.removeMember` | Removes a member from a Docs space. |
| GET | `/api/v1/docs/{spaceId}/people` | `docs.getPeople` | Gets a short preview of who can open a Docs space, with the total count. |
| GET | `/api/v1/docs/for-user/{userId}` | `docs.getSpacesForUser` | Lists the Docs spaces a workspace member belongs to that the caller can also open. |
| GET | `/api/v1/docs/spaces/archived` | `docs.getArchivedList` | Lists the archived Docs spaces the caller administers. |
| GET | `/api/v1/docs/spaces/recent` | `docs.getRecentSpaces` | Lists the Docs spaces the caller opened most recently. |
| GET | `/api/v1/docs/spaces/trash` | `docs.getTrashList` | Lists the Docs spaces in Trash that the caller administers. |

Request bodies:

- `CreateSpaceDto` (`create`): requires `title` (string).
- `UpdateSpaceDto` (`update`): requires `title` (string).
- `UpdateSpaceMemberDto` (`updateMember`): no field is required.

## Docs pages

| Method | Path | Operation | Summary |
| --- | --- | --- | --- |
| POST | `/api/v1/docs/{spaceId}/pages` | `docs.createPage` | Creates a page in a Docs space, at the top level or under a parent page. |
| POST | `/api/v1/docs/{spaceId}/pages/reorder` | `docs.reorderPages` | Sets the order of the pages under one parent in a Docs space. |
| GET | `/api/v1/docs/{spaceId}/pages/tree` | `docs.getTree` | Gets the page tree of a Docs space, with the pages the caller can open. |
| GET | `/api/v1/docs/pages/{id}` | `docs.getPage` | Gets a Docs page with its content. |
| PUT | `/api/v1/docs/pages/{id}` | `docs.updatePage` | Replaces the content of a Docs page. |
| DELETE | `/api/v1/docs/pages/{id}` | `docs.deletePage` | Moves a Docs page and every page under it to Trash. |
| POST | `/api/v1/docs/pages/{id}/convert-to-rich` | `docs.convertPageToRich` | Converts a Markdown Docs page to a rich page. |
| POST | `/api/v1/docs/pages/{id}/copy` | `docs.copyPage` | Copies a Docs page, with the pages under it, to another place or space. |
| POST | `/api/v1/docs/pages/{id}/duplicate` | `docs.duplicatePage` | Makes a copy of a Docs page beside it. |
| POST | `/api/v1/docs/pages/{id}/move` | `docs.movePage` | Moves a Docs page, with the pages under it, to another place or space. |
| DELETE | `/api/v1/docs/pages/{id}/permanent` | `docs.deletePagePermanently` | Permanently deletes a Docs page in Trash. |
| POST | `/api/v1/docs/pages/{id}/restore` | `docs.restorePage` | Restores a Docs page from Trash. |
| PUT | `/api/v1/docs/pages/{id}/star` | `docs.starPage` | Stars or unstars a Docs page for the caller. |
| PUT | `/api/v1/docs/pages/{id}/title` | `docs.renamePage` | Renames a Docs page. |
| GET | `/api/v1/docs/pages/{pageId}/backlinks` | `docs.getBacklinks` | Lists the Docs pages that link to a page. |
| GET | `/api/v1/docs/pages/{pageId}/members` | `docs.getPageMembers` | Lists the people who can open a Docs page with restricted access. |
| POST | `/api/v1/docs/pages/{pageId}/members` | `docs.addPageMember` | Gives a person, group or agent a role on a Docs page with restricted access. |
| DELETE | `/api/v1/docs/pages/{pageId}/members/{memberId}` | `docs.removePageMember` | Removes a member from a Docs page with restricted access. |
| GET | `/api/v1/docs/pages/{pageId}/revisions` | `docs.getRevisions` | Lists the saved revisions of a Docs page, newest first. |
| GET | `/api/v1/docs/pages/{pageId}/revisions/{revisionId}` | `docs.getRevision` | Gets one saved revision of a Docs page with its content. |
| POST | `/api/v1/docs/pages/{pageId}/revisions/{revisionId}/restore` | `docs.restoreRevision` | Restores a Docs page to one of its saved revisions. |
| POST | `/api/v1/docs/pages/{pageId}/visibility/reset` | `docs.resetPageVisibility` | Removes a Docs page's own access list so it follows its space again. |
| GET | `/api/v1/docs/pages/recent` | `docs.getRecentPages` | Lists the Docs pages the caller most recently viewed, edited or created. |
| GET | `/api/v1/docs/pages/search` | `docs.searchPages` | Searches the Docs pages the caller can open, in every space or in one. |
| GET | `/api/v1/docs/pages/starred` | `docs.getStarredPages` | Lists the Docs pages the caller has starred, paged. |
| GET | `/api/v1/docs/pages/trash` | `docs.getTrashedPages` | Lists the Docs pages in Trash that the caller can restore, paged. |

Request bodies:

- `CreatePageDto` (`createPage`): requires `title` (string).
- `UpdatePageDto` (`updatePage`): requires `title` (string).

## Example

`docs.getList`: lists the Docs spaces the caller can open.

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