> ## Documentation Index
> Fetch the complete documentation index at: https://docs.holydocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Projects API

REST API endpoints for creating, reading, updating, and deleting HolyDocs documentation projects.

## Overview

The Projects API lets you manage documentation projects programmatically. All endpoints require authentication and are scoped to your organization.

**Base path:** `https://api.holydocs.com/api/v1/projects`

## List Projects

Retrieve all projects in your organization.

```bash
GET /api/v1/projects
```

Copy as context

**cURL**

```bash
    curl https://api.holydocs.com/api/v1/projects \
      -H "Authorization: Bearer $HOLYDOCS_API_KEY"
    ```
  **CLI**

```bash
    holydocs status
    # or list projects via the API helper:
    holydocs api get /projects
    ```
  **SDK**

```ts
    // Project-management helpers are not part of the current JS SDK.
    // Use the CLI API helper or call the REST endpoint directly.
    // Example:
    // holydocs api get /projects
    ```

### Query Parameters

| Parameter | Type | Description |
|---|---|---|
| `page` | number | Page number (default: 1) |
| `perPage` | number | Results per page (default: 20, max: 100) |

### Response

```json
{
  "data": [
    {
      "id": "proj_abc123",
      "orgId": "org_xyz",
      "name": "My API Docs",
      "slug": "my-api-docs",
      "subdomain": "my-api-docs",
      "customDomain": "docs.mycompany.com",
      "repoProvider": "github",
      "repoOwner": "myorg",
      "repoName": "api-docs",
      "repoBranch": "main",
      "repoPath": "/",
      "createdAt": 1708200000000,
      "updatedAt": 1708200000000
    }
  ],
  "meta": {
    "total": 5,
    "page": 1,
    "perPage": 20,
    "totalPages": 1
  }
}
```

## Get Project

Retrieve a single project by ID.

```bash
GET /api/v1/projects/:projectId
```

### Response

```json
{
  "data": {
    "id": "proj_abc123",
    "orgId": "org_xyz",
    "name": "My API Docs",
    "slug": "my-api-docs",
    "subdomain": "my-api-docs",
    "customDomain": "docs.mycompany.com",
    "repoProvider": "github",
    "repoOwner": "myorg",
    "repoName": "api-docs",
    "repoBranch": "main",
    "repoPath": "/",
    "configJson": "{...}",
    "createdAt": 1708200000000,
    "updatedAt": 1708200000000
  }
}
```

## Create Project

Create a new documentation project.

```bash
POST /api/v1/projects
```

### Request Body

```json
{
  "name": "My API Docs",
  "slug": "my-api-docs",
  "subdomain": "my-api-docs",
  "customDomain": "docs.mycompany.com",
  "repoProvider": "github",
  "repoOwner": "myorg",
  "repoName": "api-docs",
  "repoBranch": "main",
  "repoPath": "/"
}
```

### Fields

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | Yes | Project display name (1-100 chars) |
| `slug` | string | Yes | URL-safe identifier (`[a-z0-9-]+`, 1-100 chars) |
| `subdomain` | string | No | Custom subdomain (defaults to slug) |
| `customDomain` | string | No | Stored project metadata only. Use the [Domains API](/api/domains) to provision and verify the hostname. |
| `repoProvider` | `github` \| `gitlab` | No | Git provider |
| `repoOwner` | string | No | Repository owner/organization |
| `repoName` | string | No | Repository name |
| `repoBranch` | string | No | Branch to deploy from (default: `main`) |
| `repoPath` | string | No | Path to docs directory (default: `/`) |

### Response

```json
{
  "data": {
    "id": "proj_abc123",
    "name": "My API Docs",
    "slug": "my-api-docs",
    "createdAt": 1708200000000
  }
}
```

The `slug` must be unique within your organization. Creating a project with a duplicate slug returns a `409 ALREADY_EXISTS` error.

## Update Project

Update an existing project's settings.

```bash
PATCH /api/v1/projects/:projectId
```

### Request Body

All fields are optional. Only include the fields you want to update:

```json
{
  "name": "Updated Docs Name",
  "repoBranch": "release/v2",
  "configJson": "{\"name\":\"Updated\",\"colors\":{\"primary\":\"#FBBF24\"}}"
}
```

### Response

```json
{
  "data": {
    "id": "proj_abc123",
    "name": "Updated Docs Name",
    "updatedAt": 1708200500000
  }
}
```

## Delete Project

Permanently delete a project and all associated data.

```bash
DELETE /api/v1/projects/:projectId
```

This action is irreversible. All deployments, assets, AI indices, analytics data, and custom domain configuration will be permanently deleted. The Git repository is not affected.

### Response

```json
{
  "data": {
    "deleted": true,
    "id": "proj_abc123"
  }
}
```

## Error Codes

| Code | Status | Description |
|---|---|---|
| `NOT_FOUND` | 404 | Project not found |
| `ALREADY_EXISTS` | 409 | Slug already taken in this organization |
| `VALIDATION_ERROR` | 400 | Invalid field values |
| `LIMIT_EXCEEDED` | 403 | Project limit reached for your plan |