Projects API

List, create, update, archive, and delete Redmine projects via the REST API.

The Projects API gives you programmatic access to Redmine projects and their configuration.

Requests must be authenticated. See REST API authentication for details.

Endpoints

Method	Path	Description
GET	/projects.json	List projects.
GET	/projects/:id.json	Get a single project.
POST	/projects.json	Create a project.
PUT	/projects/:id.json	Update a project.
DELETE	/projects/:id.json	Delete a project.
PUT	/projects/:id/archive.json	Archive a project.
PUT	/projects/:id/unarchive.json	Unarchive a project.
PUT	/projects/:id/close.json	Close a project.
PUT	/projects/:id/reopen.json	Reopen a project.

---

List projects

GET /projects.json

Returns projects visible to the authenticated user.

Query parameters

status · number

Filter by project status. 1 = active, 5 = closed, 9 = archived.

include · string

Comma-separated list of associations to embed. Valid values: trackers, issue_categories, enabled_modules.

offset · number · default: "0"

Number of records to skip.

limit · number · default: "25"

Number of records per page (max 100).

Example

curl -H "X-Redmine-API-Key: YOUR_API_KEY" \
  "https://redmine.example.com/projects.json?status=1&include=trackers"

Response

{
  "projects": [
    {
      "id": 1,
      "name": "My Project",
      "identifier": "myproject",
      "description": "An example project.",
      "homepage": "https://example.com",
      "status": 1,
      "is_public": true,
      "inherit_members": false,
      "created_on": "2024-01-15T10:00:00Z",
      "updated_on": "2024-03-01T08:00:00Z"
    }
  ],
  "total_count": 1,
  "offset": 0,
  "limit": 25
}

---

Get project

GET /projects/:id.json

Returns a single project. You can use the project’s numeric ID or its string identifier.

Path parameters

id · string · required

The project’s numeric ID or identifier string (e.g., myproject).

Query parameters

include · string

Comma-separated list of associations to embed. Valid values: trackers, issue_categories, enabled_modules.

Example

curl -H "X-Redmine-API-Key: YOUR_API_KEY" \
  "https://redmine.example.com/projects/myproject.json?include=trackers,issue_categories"

Response fields

project · object · required

Show project properties

id · number

Unique project ID.

name · string

Project display name (max 255 characters).

identifier · string

URL-safe project identifier (lowercase letters, digits, dashes, underscores; max 100 characters).

description · string

Project description.

homepage · string

Project homepage URL.

status · number

Project status: 1 (active), 5 (closed), 9 (archived).

is_public · boolean

Whether the project is publicly visible.

inherit_members · boolean

Whether this project inherits members from its parent.

parent · object

Parent project reference (id, name), if applicable.

default_version · object

Default version reference (id, name).

trackers · array

Enabled trackers (included when requested).

issue_categories · array

Issue categories (included when requested).

enabled_modules · array

Enabled module names (included when requested).

custom_fields · array

Custom field values.

created_on · string

ISO 8601 creation timestamp.

updated_on · string

ISO 8601 last update timestamp.

---

Create project

POST /projects.json

Creates a new project. The authenticated user must have the Create project global permission.

Request body

Wrap all fields inside a project object.

project.name · string · required

Project display name. Maximum 255 characters.

project.identifier · string · required

Unique project identifier. Lowercase letters, digits, dashes, and underscores only. Maximum 100 characters. Cannot start with a digit.

project.description · string

Project description.

project.homepage · string

Project homepage URL.

project.is_public · boolean · default: "true"

Whether the project is publicly visible.

project.parent_id · number

ID of the parent project.

project.inherit_members · boolean · default: "false"

Whether to inherit members from the parent project.

project.tracker_ids · number[]

Array of tracker IDs to enable for this project.

project.enabled_module_names · string[]

Array of module names to enable. Examples: issue_tracking, time_tracking, wiki, documents, files, forums, news, repository.

project.custom_fields · object[]

Array of custom field values: [{"id": 1, "value": "value"}].

Example

curl -X POST \
  -H "X-Redmine-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": {
      "name": "New Project",
      "identifier": "new-project",
      "description": "A newly created project.",
      "is_public": false,
      "tracker_ids": [1, 2],
      "enabled_module_names": ["issue_tracking", "time_tracking", "wiki"]
    }
  }' \
  https://redmine.example.com/projects.json

A successful response returns 201 Created with the new project in the body.

---

Update project

PUT /projects/:id.json

Updates an existing project. Only include fields you want to change.

Path parameters

id · string · required

The project’s numeric ID or identifier string.

Example

curl -X PUT \
  -H "X-Redmine-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": {
      "description": "Updated description.",
      "is_public": false
    }
  }' \
  https://redmine.example.com/projects/myproject.json

A successful response returns 200 OK.

---

Delete project

DELETE /projects/:id.json

Deletes a project and all of its data. This action is irreversible.

Deleting a project permanently removes all issues, time entries, wiki pages, forums, and files associated with it.

Path parameters

id · string · required

The project’s numeric ID or identifier string.

Example

curl -X DELETE \
  -H "X-Redmine-API-Key: YOUR_API_KEY" \
  https://redmine.example.com/projects/myproject.json

A successful response returns 200 OK.

---

Archive and unarchive

Archiving a project makes it read-only and hides it from regular navigation.

# Archive a project
curl -X PUT \
  -H "X-Redmine-API-Key: YOUR_API_KEY" \
  https://redmine.example.com/projects/myproject/archive.json

# Unarchive a project
curl -X PUT \
  -H "X-Redmine-API-Key: YOUR_API_KEY" \
  https://redmine.example.com/projects/myproject/unarchive.json

Only administrators can archive and unarchive projects.

Close and reopen

# Close a project
curl -X PUT \
  -H "X-Redmine-API-Key: YOUR_API_KEY" \
  https://redmine.example.com/projects/myproject/close.json

# Reopen a closed project
curl -X PUT \
  -H "X-Redmine-API-Key: YOUR_API_KEY" \
  https://redmine.example.com/projects/myproject/reopen.json