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

# Projects API

> Create, read, update, and delete projects via the Nextoria Hub REST API.

## Endpoints

| Method   | Path                          | Description             |
| -------- | ----------------------------- | ----------------------- |
| `GET`    | `/v1/projects`                | List all projects       |
| `POST`   | `/v1/projects`                | Create a project        |
| `GET`    | `/v1/projects/:id`            | Get a project           |
| `PATCH`  | `/v1/projects/:id`            | Update a project        |
| `DELETE` | `/v1/projects/:id`            | Archive a project       |
| `GET`    | `/v1/projects/:id/tasks`      | List tasks in a project |
| `GET`    | `/v1/projects/:id/milestones` | List milestones         |

***

## List Projects

```bash theme={null}
GET /v1/projects
```

**Query Parameters:**

| Parameter      | Type    | Description                                                        |
| -------------- | ------- | ------------------------------------------------------------------ |
| `status`       | string  | Filter by status: `planning`, `in_progress`, `review`, `completed` |
| `client_id`    | string  | Filter by client                                                   |
| `team_lead_id` | string  | Filter by team lead                                                |
| `limit`        | integer | Max results per page (default: 20, max: 100)                       |
| `cursor`       | string  | Pagination cursor from previous response                           |

**Example Request:**

```bash theme={null}
curl https://api.nextoriahub.com/v1/projects?status=in_progress&limit=10 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Example Response:**

```json theme={null}
{
  "data": [
    {
      "id": "proj_abc123",
      "name": "Acme Corp Brand Refresh",
      "status": "in_progress",
      "start_date": "2026-02-01",
      "end_date": "2026-04-30",
      "budget": 15000,
      "budget_spent": 6200,
      "client": {
        "id": "client_xyz789",
        "name": "Acme Corp"
      },
      "team_lead": {
        "id": "user_abc456",
        "name": "Alice Smith"
      },
      "task_count": 42,
      "completed_task_count": 18,
      "created_at": "2026-01-28T10:00:00Z",
      "updated_at": "2026-02-15T14:32:00Z"
    }
  ],
  "meta": {
    "total": 87,
    "limit": 10,
    "next_cursor": "cur_def456"
  }
}
```

***

## Create a Project

```bash theme={null}
POST /v1/projects
```

**Request Body:**

```json theme={null}
{
  "name": "Globex Website Redesign",
  "description": "Full redesign of the marketing site and blog.",
  "client_id": "client_globex123",
  "team_lead_id": "user_bob789",
  "start_date": "2026-03-01",
  "end_date": "2026-05-31",
  "budget": 22000,
  "status": "planning"
}
```

**Required fields:** `name`, `client_id`

**Response:** `201 Created` with the created project object.

***

## Update a Project

```bash theme={null}
PATCH /v1/projects/:id
```

Send only the fields you want to update (partial updates are supported):

```json theme={null}
{
  "status": "in_progress",
  "end_date": "2026-06-15"
}
```

**Response:** `200 OK` with the updated project object.

***

## Archive a Project

```bash theme={null}
DELETE /v1/projects/:id
```

Projects are **archived**, not permanently deleted. Archived projects can be restored from **Projects → Archived** in the UI.

**Response:** `204 No Content`

***

## Project Object

```typescript theme={null}
interface Project {
  id: string; // "proj_abc123"
  name: string;
  description: string | null;
  status: "planning" | "in_progress" | "review" | "completed" | "archived";
  start_date: string | null; // ISO 8601 date
  end_date: string | null;
  budget: number | null; // In workspace currency (minor units)
  budget_spent: number;
  client: { id: string; name: string } | null;
  team_lead: { id: string; name: string } | null;
  task_count: number;
  completed_task_count: number;
  created_at: string; // ISO 8601 datetime
  updated_at: string;
}
```