MokoGitea/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:

{
  "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:

{
  "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:

{
  "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:

{
  "issue_id": 42
}

Move Issue Between Columns

PATCH /api/v1/repos/{owner}/{repo}/projects/{id}/issues/{issueId}/move

Body:

{
  "column_id": 5,
  "sorting": 0
}

Remove Issue from Project

DELETE /api/v1/repos/{owner}/{repo}/projects/{id}/issues/{issueId}

Data Types

Project

{
  "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

{
  "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

{
  "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

# 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 · moko-platform

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