Projects
Projects
Create, read, and delete projects and manage their repository and preview settings
Overview
The Projects group of the Doxa REST API manages the projects that belong to the signed-in user. A project connects one GitHub repository to one docs site, and the endpoints in this group create it, read it, change its repository and preview visibility, and delete it.
The list endpoint returns the projects you can access. That includes your personal projects and projects that belong to your teams. Team projects appear only for the roles your team membership allows. Starting a generation, managing branches, and publishing are covered in the other REST API groups and in the Generations group.
Use the shell endpoint to load what the dashboard needs for one project in a single request. Use the preview visibility endpoints to read or change whether the project's docs preview is visible.
Note:
Only the project owner can connect or change the GitHub repository for a project. The repository comes from the owner's GitHub installation, so a team member who is not the owner receives a 403 response with the message "Only the project owner can connect a repository."
Schema
The fields below come from the request and response shapes used by these endpoints.
| Field | Type | Required | Description |
|---|---|---|---|
project | object | Yes (responses) | The project returned by create, read, repository, and preview endpoints. Includes the project's docs URL. |
projects | array of objects | Yes (list response) | The projects the signed-in user can access, each with the same fields as project. Docs URLs are included. |
githubRepositoryId | number | Yes (repository request) | The ID of a repository from your GitHub installation to connect to the project. |
error.message | string | Yes (error responses) | A readable description of the failure. |
error.details | any | No (error responses) | Extra information about the failure, when the server provides it. |
Error responses use one shape:
{
"error": {
"message": "Only the project owner can connect a repository.",
"details": null
}
}Endpoints
| Method | Path | Description | Reference |
|---|---|---|---|
| GET | /projects | List the signed-in user's projects. | List projects |
| POST | /projects | Create a new project. Returns 201 on success. | Create a project |
| POST | /projects/example | Create a project from the starter example docs. Returns 201 on success. | Create example project |
| PUT | /projects/{projectId}/repository | Connect or change the GitHub repository for a project. Owner only. | Set project repository |
| GET | /projects/{projectId} | Fetch a project by ID. | Get a project |
| DELETE | /projects/{projectId} | Delete a project. | Delete a project |
| GET | /projects/{projectId}/shell | Fetch the data the dashboard shell needs for a project. | Get project shell |
| GET | /projects/{projectId}/preview-visibility | Read the preview visibility setting for a project. | Get preview visibility |
| PUT | /projects/{projectId}/preview-visibility | Change the preview visibility setting for a project. | Set preview visibility |