MokoGitea-Fork/wiki/project-api.md

# Project Board API Reference

Complete REST API for managing Gitea project boards, columns, and issue cards. This API was added by MokoGitea and is not available in upstream Gitea.

## Authentication

All write endpoints require a token with `issue` scope:
```
Authorization: token YOUR_TOKEN
```

## Projects

### List Projects
```
GET /api/v1/repos/{owner}/{repo}/projects
```
Query parameters:
- `state` — `open` (default), `closed`, or `all`
- `page` — page number (1-based)
- `limit` — results per page

Response: Array of Project objects

### Create Project
```
POST /api/v1/repos/{owner}/{repo}/projects
```
Body:
```json
{
  "title": "Sprint Q2 2026",
  "description": "Second quarter sprint",
  "board_type": 1,
  "card_type": 0
}
```
- `board_type`: 0=none, 1=basic kanban, 2=bug triage
- `card_type`: 0=text only, 1=images and text

### Get Project
```
GET /api/v1/repos/{owner}/{repo}/projects/{id}
```

### Update Project
```
PATCH /api/v1/repos/{owner}/{repo}/projects/{id}
```
Body:
```json
{
  "title": "Updated Title",
  "description": "Updated description"
}
```

### Delete Project
```
DELETE /api/v1/repos/{owner}/{repo}/projects/{id}
```

### Close/Reopen Project
```
POST /api/v1/repos/{owner}/{repo}/projects/{id}/close
POST /api/v1/repos/{owner}/{repo}/projects/{id}/reopen
```

## Columns

### List Columns
```
GET /api/v1/repos/{owner}/{repo}/projects/{id}/columns
```

### Create Column
```
POST /api/v1/repos/{owner}/{repo}/projects/{id}/columns
```
Body:
```json
{
  "title": "Backlog",
  "color": "#0075ca"
}
```

### Delete Column
```
DELETE /api/v1/repos/{owner}/{repo}/projects/{id}/columns/{columnId}
```

## Issue Cards

### List Issues in Column
```
GET /api/v1/repos/{owner}/{repo}/projects/{id}/columns/{columnId}/issues
```

Response: Array of ProjectColumnIssue objects with `issue_id`, `project_id`, `column_id`, `sorting`

### Add Issue to Column
```
POST /api/v1/repos/{owner}/{repo}/projects/{id}/columns/{columnId}/issues
```
Body:
```json
{
  "issue_id": 42
}
```

### Move Issue Between Columns
```
PATCH /api/v1/repos/{owner}/{repo}/projects/{id}/issues/{issueId}/move
```
Body:
```json
{
  "column_id": 5,
  "sorting": 0
}
```

### Remove Issue from Project
```
DELETE /api/v1/repos/{owner}/{repo}/projects/{id}/issues/{issueId}
```

## Data Types

### Project
```json
{
  "id": 1,
  "title": "Roadmap",
  "description": "Development roadmap",
  "owner_id": 2,
  "repo_id": 68,
  "creator_id": 1,
  "is_closed": false,
  "created_at": "2026-05-08T00:06:45Z",
  "updated_at": "2026-05-08T00:06:45Z",
  "closed_at": null
}
```

### ProjectColumn
```json
{
  "id": 7,
  "title": "Backlog",
  "sorting": 0,
  "color": "#0075ca",
  "project_id": 1,
  "default": false,
  "created_at": "2026-05-08T00:06:58Z",
  "updated_at": "2026-05-08T00:06:58Z"
}
```

### ProjectColumnIssue
```json
{
  "id": 1,
  "issue_id": 42,
  "project_id": 1,
  "column_id": 7,
  "sorting": 0
}
```

## MCP Integration

The `project-mcp` server wraps this API. Key tool: `project_setup_roadmap` creates a full project board with columns and loads all open issues in one call.

## Quick Start

```bash
# Create a project
curl -X POST -H "Authorization: token TOKEN" \
  https://git.mokoconsulting.tech/api/v1/repos/MokoConsulting/MokoCRM/projects \
  -d '{"title":"Roadmap","board_type":1}'

# Add columns
curl -X POST -H "Authorization: token TOKEN" \
  https://git.mokoconsulting.tech/api/v1/repos/MokoConsulting/MokoCRM/projects/1/columns \
  -d '{"title":"Backlog"}'

# Add an issue
curl -X POST -H "Authorization: token TOKEN" \
  https://git.mokoconsulting.tech/api/v1/repos/MokoConsulting/MokoCRM/projects/1/columns/1/issues \
  -d '{"issue_id":42}'
```

---

*Repo: [MokoGitea](https://git.mokoconsulting.tech/MokoConsulting/MokoGitea) · [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)*

| Revision | Date | Author | Description |
|---|---|---|---|
| 1.0 | 2026-05-09 | Moko Consulting | Initial version |