REST API overview

An overview of the Redmine REST API — base URL, response formats, pagination, error codes, and curl examples.

Redmine exposes a REST API that lets you programmatically read and write project data. All standard resources — issues, projects, users, time entries, and wiki pages — are available as JSON or XML.

The REST API must be enabled by an administrator before it can be used. Go to Administration → Settings → API and enable the Enable REST web service option.

Base URL

All API endpoints are relative to your Redmine installation’s root URL:

https://redmine.example.com

Append .json or .xml to any resource path to request that format:

GET https://redmine.example.com/issues.json
GET https://redmine.example.com/issues.xml

Response formats

Redmine supports two response formats.

JSON

Append .json to the resource path or set the Accept: application/json header.

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

{
  "issues": [
    {
      "id": 1,
      "subject": "Example issue",
      "status": { "id": 1, "name": "New" }
    }
  ],
  "total_count": 1,
  "offset": 0,
  "limit": 25
}

XML

Append .xml to the resource path or set the Accept: application/xml header.

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

<?xml version="1.0" encoding="UTF-8"?>
<issues total_count="1" offset="0" limit="25" type="array">
  <issue>
    <id>1</id>
    <subject>Example issue</subject>
    <status id="1" name="New"/>
  </issue>
</issues>

Pagination

List endpoints return paginated results. Use offset and limit to navigate pages.

offset · number · default: "0"

Number of records to skip before returning results.

limit · number · default: "25"

Maximum number of records to return. The server-side maximum is typically 100.

The response always includes total_count, offset, and limit fields so you can calculate whether more pages exist.

# Fetch the second page of 25 issues
curl -H "X-Redmine-API-Key: YOUR_API_KEY" \
  "https://redmine.example.com/issues.json?offset=25&limit=25"

Common query parameters

Most list endpoints accept these parameters in addition to their own resource-specific filters.

Parameter	Type	Description
offset	integer	Number of records to skip.
limit	integer	Number of records per page (max 100).
sort	string	Column to sort by, optionally suffixed with :desc (e.g., created_on:desc).
include	string	Comma-separated list of extra associations to embed in the response.

Requesting extra associations

Some endpoints support an include parameter that embeds related objects directly in the response, avoiding additional requests.

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

Common include values per resource:

Resource	Supported values
Issue	journals, relations, changesets, attachments, children, watchers, allowed_statuses
Project	trackers, issue_categories, enabled_modules
User	memberships, groups

HTTP methods

Method	Purpose
GET	Retrieve a resource or list of resources.
POST	Create a new resource.
PUT	Update an existing resource.
DELETE	Delete a resource.

Content type for write requests

When sending a request body (POST or PUT), set the Content-Type header to match your payload format.

JSON

curl -X POST \
  -H "X-Redmine-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"issue":{"project_id":1,"subject":"New issue"}}' \
  https://redmine.example.com/issues.json

HTTP status codes

Code	Meaning
200 OK	Request succeeded.
201 Created	Resource created successfully.
204 No Content	Request succeeded with no response body (e.g., DELETE).
401 Unauthorized	Authentication failed or missing.
403 Forbidden	Authenticated user lacks permission.
404 Not Found	Resource does not exist.
409 Conflict	Conflict with the current state (e.g., stale update).
422 Unprocessable Entity	Validation failed. Response body contains error details.
500 Internal Server Error	Unexpected server error.

Validation error response

When a 422 is returned, the body contains the validation errors:

{
  "errors": [
    "Subject cannot be blank",
    "Project is invalid"
  ]
}

Rate limiting

Redmine does not enforce rate limiting by default. If you are running Redmine behind a reverse proxy (nginx, Apache), you can configure rate limiting at that layer.

For high-volume integrations, prefer bulk or filtered queries over fetching individual resources in a loop.

Quick reference

Authentication

API key, HTTP Basic Auth, and OAuth2.

Issues API

Create, read, update, and delete issues.

Projects API

Manage projects and their settings.

Users API

Manage user accounts (admin only).

Time entries API

Log and query time entries.

Wiki API

Read and write wiki pages.