• Table of contents
• Redmine API
  • API Description
  • General topics
    • Authentication
    • Collection resources and pagination
    • Fetching associated data
    • Working with custom fields
  • API Usage in various languages/tools
  • API Change history
    • 2012-01-29: Multiselect custom fields (r8721, 1.4.0)

Redmine API¶

Redmine exposes some of its data through a REST API. This API provides access and basic CRUD operations (create, update, delete) for the resources described below.

API Description¶

Resource	Status	Notes	Availability
Issues	Stable	Usable with some bugs and rough edges.	1.0
Projects	Stable	Usable with some bugs and rough edges.	1.0
Project Memberships	Alpha		1.4
Users	Stable		1.1
Time Entries	Stable		1.1
News	Prototype	Prototype implementation for index only	1.1
Issue Relations	Alpha		1.3
Versions	Alpha		1.3
Queries	Alpha		1.3
Attachments	Alpha		1.3
Issue Statuses	Alpha	Provides the list of all statuses	1.3
Trackers	Alpha	Provides the list of all trackers	1.3
Issue Categories	Alpha		1.3
Roles	Alpha		1.4

Status legend:

• Stable - feature complete, no major changes planned
• Beta - usable for integrations with some bugs or missing minor functionality
• Alpha - major functionality in place, needs feedback from API users and integrators
• Prototype - very rough implementation, possible major breaking changes mid-version. Not recommended for integration
• Planned - planned in a future version, depending on developer availability

General topics¶

Authentication¶

Most of the time, the API requires authentication. To enable the API-style authentication, you have to check Enable REST API in Administration -> Settings -> Authentication. Then, authentication can be done in 2 different ways:

• using your regular login/password via HTTP Basic authentication.
• using your API key which is a handy way to avoid putting a password in a script. The API key may be attached to each request in one of the following way:
  • passed in as a "key" parameter
  • passed in as a username with a random password via HTTP Basic authentication
  • passed in as a "X-Redmine-API-Key" HTTP header (added in Redmine 1.1.0)

You can find your API key on your account page ( /my/account ) when logged in, on the right-hand pane of the default layout.

Collection resources and pagination¶

The response to a GET request on a collection ressources (eg. /issues.xml, /users.xml) generally won't return all the objects available in your database. Redmine 1.1.0 introduces a common way to query such ressources using the following parameters:

• offset: the offset of the first object to retrieve
• limit: the number of items to be present in the response (default is 25, maximum is 100)

Alternatively, you can use the page parameter, instead of offset, in conjunction with limit.

Examples:

GET /issues.xml
=> returns the 25 first issues

GET /issues.xml?limit=100
=> returns the 100 first issues

GET /issues.xml?offset=30&limit=10
=> returns 10 issues from the 30th

GET /issues.xml?page=3&limit=10
=> same as above

Responses to GET requests on collection ressources provide information about the total object count available in Redmine and the offset/limit used for the response. Examples:

GET /issues.xml

<issues type="array" total_count="2595" limit="25" offset="0">
  ...
</issues>

GET /issues.json

{ "issues":[...], "total_count":2595, "limit":25, "offset":0 }

Note: if you're using a REST client that does not support such top level attributes (total_count, limit, offset), you can set the nometa parameter or X-Redmine-Nometa HTTP header to 1 to get responses without them. Example:

GET /issues.xml?nometa=1

<issues type="array">
  ...
</issues>

Fetching associated data¶

Since of 1.1.0, you have to explicitly specify the associations you want to be included in the query result by appending the include parameter to the query url :

Example:

To retrieve issue journals with its description:

GET /issues/296.xml?include=journals

<issue>
  <id>296</id>
  ...
  <journals type="array">
  ...
  </journals>
</issue>

You can also load multiple associations using a coma separated list of items.

Example:

GET /issues/296.xml?include=journals,changesets

<issue>
  <id>296</id>
  ...
  <journals type="array">
  ...
  </journals>
  <changesets type="array">
  ...
  </changesets>
</issue>

Working with custom fields¶

Most of the Redmine objects support custom fields. Their values can be found in the custom_fields attributes.

XML Example:

GET /issues/296.xml      # an issue with 2 custom fields

<issue>
  <id>296</id>
  ...
  <custom_fields type="array">
    <custom_field name="Affected version" id="1">
      <value>1.0.1</value>
    </custom_field>
    <custom_field name="Resolution" id="2">
      <value>Fixed</value>
    </custom_field>
  </custom_fields>
</issue>

JSON Example:

GET /issues/296.json      # an issue with 2 custom fields

{"issue":
  {
    "id":8471,
    ...
    "custom_fields":
      [
        {"value":"1.0.1","name":"Affected version","id":1},
        {"value":"Fixed","name":"Resolution","id":2}
      ]
  }
}

You can also set/change the values of the custom fields when creating/updating an object using the same syntax (except that the custom field name is not required).

XML Example:

PUT /issues/296.xml

<issue>
  <subject>Updating custom fields of an issue</subject>
  ...
  <custom_fields type="array">
    <custom_field id="1">
      <value>1.0.2</value>
    </custom_field>
    <custom_field id="2">
      <value>Invalid</value>
    </custom_field>
  </custom_fields>
</issue>

Note: the type="array" attribute on custom_fields XML tag is strictly required.

JSON Example:

PUT /issues/296.json

{"issue":
  {
    "subject":"Updating custom fields of an issue",
    ...
    "custom_fields":
      [
        {"value":"1.0.2","id":1},
        {"value":"Invalid","id":2}
      ]
  }
}

API Usage in various languages/tools¶

• Ruby
• PHP
• Python
• Java
• cURL
• Drupal Redmine API module, 2.x branch
• .NET
• Delphi

API Change history¶

This section lists changes to the existing API features only. New features of the API are listed in the API Description.

2012-01-29: Multiselect custom fields (r8721, 1.4.0)¶

Custom fields with multiple values are now supported in Redmine and may be found in API responses. These custom fields have a multiple=true attribute and their value attribute is an array.

Example:

GET /issues/296.json

{"issue":
  {
    "id":8471,
    ...
    "custom_fields":
      [
        {"value":["1.0.1","1.0.2"],"multiple":true,"name":"Affected version","id":1},
        {"value":"Fixed","name":"Resolution","id":2}
      ]
  }
}