Issues API

Create, retrieve, update, and delete Redmine issues via the REST API.

The Issues API lets you manage Redmine issues programmatically. All endpoints accept and return JSON or XML.

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

Endpoints

Method	Path	Description
GET	/issues.json	List issues.
GET	/issues/:id.json	Get a single issue.
POST	/issues.json	Create an issue.
PUT	/issues/:id.json	Update an issue.
DELETE	/issues/:id.json	Delete an issue.

---

List issues

GET /issues.json

Returns a paginated list of issues visible to the authenticated user.

Query parameters

project_id · string

Filter by project identifier or numeric ID.

tracker_id · number

Filter by tracker ID.

status_id · string · default: "open"

Filter by status. Use open, closed, or * for all, or a numeric status ID.

assigned_to_id · number

Filter by assignee user ID. Use me for the authenticated user.

author_id · number

Filter by author user ID.

priority_id · number

Filter by priority ID.

fixed_version_id · number

Filter by target version ID.

category_id · number

Filter by category ID.

subject · string

Filter issues whose subject contains this string.

created_on · string

Filter by creation date. Supports operators: >=2024-01-01, <=2024-12-31.

updated_on · string

Filter by last update date. Supports operators: >=2024-01-01.

due_date · string

Filter by due date.

include · string

Comma-separated list of associations to embed. Valid values: journals, relations, changesets, attachments, children, watchers, allowed_statuses.

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/issues.json?project_id=myproject&status_id=open&limit=10"

Response

{
  "issues": [
    {
      "id": 42,
      "project": { "id": 1, "name": "My Project" },
      "tracker": { "id": 1, "name": "Bug" },
      "status": { "id": 1, "name": "New" },
      "priority": { "id": 2, "name": "Normal" },
      "author": { "id": 3, "name": "Jane Smith" },
      "assigned_to": { "id": 4, "name": "John Doe" },
      "subject": "Login page throws 500 error",
      "description": "Steps to reproduce...",
      "start_date": "2024-03-01",
      "due_date": "2024-03-15",
      "done_ratio": 0,
      "is_private": false,
      "estimated_hours": 4.0,
      "created_on": "2024-03-01T09:00:00Z",
      "updated_on": "2024-03-02T14:30:00Z",
      "closed_on": null
    }
  ],
  "total_count": 1,
  "offset": 0,
  "limit": 25
}

---

Get issue

GET /issues/:id.json

Returns a single issue by ID.

Path parameters

id · number · required

The numeric ID of the issue.

Query parameters

include · string

Comma-separated list of associations to embed. Valid values: journals, relations, changesets, attachments, children, watchers, allowed_statuses.

Example

# Get issue with journals and relations embedded
curl -H "X-Redmine-API-Key: YOUR_API_KEY" \
  "https://redmine.example.com/issues/42.json?include=journals,relations"

Response fields

issue · object · required

Show issue properties

id · number

Unique issue ID.

project · object

Project reference (id, name).

tracker · object

Tracker reference (id, name).

status · object

Status reference (id, name).

priority · object

Priority reference (id, name).

author · object

Author reference (id, name).

assigned_to · object

Assignee reference (id, name).

fixed_version · object

Target version reference (id, name).

category · object

Category reference (id, name).

subject · string

Issue subject/title.

description · string

Full issue description (Textile or Markdown).

start_date · string

Start date in YYYY-MM-DD format.

due_date · string

Due date in YYYY-MM-DD format.

done_ratio · number

Percentage of completion (0–100).

is_private · boolean

Whether the issue is private.

estimated_hours · number

Estimated effort in hours.

spent_hours · number

Total hours logged on this issue.

total_spent_hours · number

Hours logged on this issue and its descendants.

custom_fields · array

Array of custom field values (id, name, value).

created_on · string

ISO 8601 creation timestamp.

updated_on · string

ISO 8601 last update timestamp.

closed_on · string

ISO 8601 close timestamp, or null.

journals · array

History entries (included when requested).

relations · array

Issue relations (included when requested).

attachments · array

File attachments (included when requested).

changesets · array

Related VCS changesets (included when requested).

---

Create issue

POST /issues.json

Creates a new issue. The authenticated user must have the Add issues permission in the target project.

Request body

Wrap all fields inside an issue object.

issue.project_id · number · required

ID of the project to create the issue in.

issue.tracker_id · number

Tracker ID. Defaults to the project’s first tracker.

issue.status_id · number

Initial status ID. Defaults to the first status in the workflow.

issue.priority_id · number

Priority ID. Defaults to the default priority.

issue.subject · string · required

Issue subject. Maximum 255 characters.

issue.description · string

Issue description.

issue.category_id · number

Category ID.

issue.fixed_version_id · number

Target version ID.

issue.assigned_to_id · number

Assignee user or group ID.

issue.parent_issue_id · number

Parent issue ID for creating subtasks.

issue.start_date · string

Start date in YYYY-MM-DD format.

issue.due_date · string

Due date in YYYY-MM-DD format.

issue.estimated_hours · number

Estimated effort in hours.

issue.done_ratio · number

Percentage completion (0–100).

issue.is_private · boolean

Whether to create a private issue.

issue.watcher_user_ids · number[]

Array of user IDs to add as watchers.

issue.custom_fields · object[]

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

Example

curl -X POST \
  -H "X-Redmine-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "issue": {
      "project_id": 1,
      "tracker_id": 1,
      "subject": "Login page throws 500 error",
      "description": "Steps to reproduce: 1. Go to /login ...",
      "priority_id": 2,
      "assigned_to_id": 4
    }
  }' \
  https://redmine.example.com/issues.json

A successful response returns 201 Created with the new issue in the body, and a Location header pointing to the new resource.

---

Update issue

PUT /issues/:id.json

Updates an existing issue. Only include fields you want to change — omitted fields are left unchanged.

Path parameters

id · number · required

The numeric ID of the issue to update.

Request body fields

All the same fields as Create issue apply, plus:

issue.notes · string

A journal note to attach to this update.

issue.private_notes · boolean

Whether the journal note is private.

Example

curl -X PUT \
  -H "X-Redmine-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "issue": {
      "status_id": 2,
      "done_ratio": 50,
      "notes": "Started working on this."
    }
  }' \
  https://redmine.example.com/issues/42.json

A successful response returns 200 OK.

---

Delete issue

DELETE /issues/:id.json

Deletes an issue. This action is irreversible. The authenticated user must have the Delete issues permission.

Path parameters

id · number · required

The numeric ID of the issue to delete.

Example

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

A successful response returns 200 OK with no body.

Deleting an issue also deletes all its associated journals, time entries, attachments, and relations.

Issue watchers

You can manage issue watchers with dedicated watcher endpoints.

# Add a watcher
curl -X POST \
  -H "X-Redmine-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id": 5}' \
  https://redmine.example.com/issues/42/watchers.json

# Remove a watcher
curl -X DELETE \
  -H "X-Redmine-API-Key: YOUR_API_KEY" \
  https://redmine.example.com/issues/42/watchers/5.json