Using the Project API

Usage

Prerequisites

• Have a Forgejo Instance Running
• Make sure you have access to a user that owns at least one repository
  • The repository should also hold some issues
• Make sure you create an API Token with project write permission

To prepare your shell for the commands below, open a shell and set environment variables:

# API access token
export LOCAL_TOKEN="<Token>"
# Base API depending on project type user, organization or repository:
# for user project
export BASE_API="<Schema>://<Host>[:Port]/api/v1/users/<User>"
# for organization project
export BASE_API="<Schema>://<Host>[:Port]/api/v1/orgs/<Org>"
# for repository project
export BASE_API="<Schema>://<Host>[:Port]/api/v1/repos/<UserOrOrg>/<Repo>"

• <Token> is your API access token
  • You can create this token in the Forgejo UI under forgejo.host/user/settings/applications/tokens/new
    • Make sure to set access all and write:project permissions for that token
• <Schema> can be either http or https
• <Host> is your Forgejo host
• [:Port] is an optional port number separated from <Host> with a :
• <User> is your user name and needs to be correctly capitalized
• <Org> is your organization name and needs to be correctly capitalized
• <UserOrOrg> is your user or organization name and needs to be correctly capitalized
• <Repo> is your repository name and needs to be correctly capitalized
• Example:
  • Your organization is MyOrg and can be reached under http://localhost:3001/MyOrg: export BASE_API="http://localhost:3001/api/v1/orgs/MyOrg

Create and get a project

1. Create and save a project.json with following content:

   {
     "title": "Test Project",
     "description": "My first API generated project",
     "template_type": "none",
     "card_type": "text_only",
     "status": "open"
   }

2. Create the project

   curl -X POST \
   ${BASE_API}/projects \
   -H 'accept: application/json' \
   -H "Authorization: token ${LOCAL_TOKEN}" \
   -H 'Content-Type: application/json' \
   -d @project.json

3. We expect a JSON response indicating success like:

   {
     "id": 1,
     "title": "Test Project",
     "description": "My first API generated project",
     "owner_id": 1,
     "owner_name": "me",
     "repo_id": 0,
     "repo_name": "",
     "status": "open",
     "project_type": "individual",
     "template_type": "none",
     "card_type": "text_only"
   }

4. Retrieve the project: Do a GET request against the project_id endpoint (assuming project_id is 1), the response should be like the one above

   curl -X GET \
   ${BASE_API}/projects/1 \
   -H 'accept: application/json' \
   -H "Authorization: token ${LOCAL_TOKEN}"

Add columns and issues

Create and save a project_column.json with the following contents (assuming project_id is 1):

{
  "title": "TODO",
  "color": "#2ccbd6"
}

To add a column do:

curl -X POST \
${BASE_API}/projects/1/columns \
-H 'accept: application/json' \
-H "Authorization: token ${LOCAL_TOKEN}" \
-H 'Content-Type: application/json' \
-d @project_column.json

The response should look like:

{
  "id": 1,
  "title": "TODO",
  "default": false,
  "sorting": 0,
  "color": "#2ccbd6",
  "project_id": 1
}

Create and save a project_issue.json with the following contents:

{
  "issue_id": 1
}

To add an issue to the default column do (the issue has to exist on your server of course):

curl -X POST \
${BASE_API}/projects/1/issues \
-H 'accept: application/json' \
-H "Authorization: token ${LOCAL_TOKEN}" \
-H 'Content-Type: application/json' \
-d @project_issue.json

The response should be:

{
  "id": 1,
  "issue_id": 1,
  "project_id": 1,
  "project_column_id": 1,
  "sorting": 0
}

Edit a project

To edit a project, just make the desired changes in project.json and PATCH it to the /projects/<project_id> endpoint again.

curl -X PATCH \
${BASE_API}/projects/1 \
-H 'accept: application/json' \
-H "Authorization: token ${LOCAL_TOKEN}" \
-H 'Content-Type: application/json' \
-d @project.json

NB: Changes in template_type will be ignored.

Edit a column

To edit a column, similar as above, make the desired changes in project_column.json and send it to the /projects/<project_id>/columns/<column_id> endpoint (assuming column_id is 1):

curl -X PATCH \
${BASE_API}/projects/1/columns/1 \
-H 'accept: application/json' \
-H "Authorization: token ${LOCAL_TOKEN}" \
-H 'Content-Type: application/json' \
-d @project_column.json

Move columns and issues

Suppose there is a TODO (id: 1) and a DONE (id: 2) column in a project with id 1. There are two issues (id: 1 and 2) in the TODO column and the issue with id 1 is done. You want to move issue 1 to the column with id 2:

Create and save a project_issue_update.json:

{
  "project_column_id": 2,
  "sorting": 1
}

And do:

curl -X PATCH \
${BASE_API}/projects/1/columns/1/issues/1 \
-H 'accept: application/json' \
-H "Authorization: token ${LOCAL_TOKEN}" \
-H 'Content-Type: application/json' \
-d @project_issue_update.json

Suppose for some reason the TODO column is switched with the DONE column which messes up the view order. You can change that:

Create and save a project_column_update.json:

{
  "sorting": 0
}

And do:

curl -X PATCH \
${BASE_API}/projects/1/columns/1 \
-H 'accept: application/json' \
-H "Authorization: token ${LOCAL_TOKEN}" \
-H 'Content-Type: application/json' \
-d @project_column_update.json

Delete issue, project and column

To delete do the following:

For the issue with id 1:

curl -X DELETE \
${BASE_API}/projects/1/columns/1/issue/1 \
-H "Authorization: token ${LOCAL_TOKEN}"

For the column with id 1:

curl -X DELETE \
${BASE_API}/projects/1/columns/1 \
-H "Authorization: token ${LOCAL_TOKEN}"

For the project with id 1:

curl -X DELETE \
${BASE_API}/projects/1 \
-H "Authorization: token ${LOCAL_TOKEN}"