Unfuddle STACK API

Usage Scenarios

Reference

Projects

Introduction

Each Account can have any number of Projects.

Projects

The collections represents all Projects within the Account to which the requesting person has access. The Project instance contains very basic, high level information about a Project.

URL:
/api/v1/projects[GET, POST]
/api/v1/projects/{id}[GET, PUT, DELETE]
/api/v1/projects/by_short_name/{short_name}[GET]
Response Formats:
XML, JSON
Request/Response Body:
See Project Data Model
Notes:
Please note that the "by_short_name" URL is meant as a convenience only. If you wish to POST or DELETE to a project, or access nested resources such as tickets or messages, you must use the URL based on the project ID.
Example:
curl -i -u username:password -X GET \\
  -H 'Accept: application/xml' \\
  https://mysubdomain.unfuddle.com/api/v1/projects.xml

Project Activity

Returns the activity for the given Project. Query parameters can be passed via the query string parameters or in the request body. If no request body is given, activity for the last two weeks is returned.

URL:
/api/v1/projects/#{id}/activity[GET]
Response Formats:
XML, JSON, RSS
Parameters (via query string or request body):
<request>
  <!-- specifies the inclusive start date of the query -->
  <start-date>2007/1/1</start-date>
  <!-- specifies the inclusive end date of the query -->
  <end-date>2007/12/31</end-date>
  <!-- specifies the maximum number of results to return -->
  <limit>50</limit>
</request>
Response Body:
<events>
  <event>
    <project-id type="integer"> </project-id>
    <created-at type="datetime"> </created-at>
    <record-type> [Message, Milestone, Ticket, TimeEntry, Changeset, Comment] </record-type>
    <record-id type="integer"> </record-id>
    <event> [accept, close, commit, create, delete, reopen, resolve, unaccept, status_update] </event>
    <description> </description>
    <person-id type="integer"> </person-id>
    <summary> </summary>

    <!--
      if a record exists, then it will be included here.
      note that only ONE of these will exist, corresponding to record-type
      see data model documentation for format.
    -->
    <record>
      <message> ... </message>
      <milestone> ... </milestone>
      <ticket> ... </ticket>
      <time-entry> ... </time-entry>
      <changeset> ... </changeset>
      <comment> ... </comment>
    </event>
</events>
Example:
curl -i -u username:password -X GET \\
  -H 'Accept: application/xml' \\
  -H 'Content-Type: application/xml' \\
  'https://mysubdomain.unfuddle.com/api/v1/projects/123/activity.xml?start_date=2007/5/25&end_date=2007/6/25'

Project Search

Searches through the given Project for occurrences of the given query. Query parameters can be passed via the query string parameters or in the request body.

URL:
/api/v1/projects/{id}/search[GET]
Response Formats:
XML, JSON
Parameters (via query string or request body):
<request>
  <!-- REQUIRED: specifies the text of the query -->
  <query>dashboard widget</query>
  <!-- zero-based index specifies where to start in the results (for pagination) -->
  <start-index>20</start-index>
  <!-- zero-based index specifies where to end in the results (for pagination) -->
  <end-index>39</end-index>
  <!-- specifies the number of results that will be returned for each filter -->
  <limit>5</limit>
  <!-- comma separated string of object types by which to filter -->
  <filter>changesets,comments,messages,milestones,notebooks,tickets</filter>
</request>
Response Body:
<results>
  <result>
    <type> [Changeset, Comment, Message, Milestone, Ticket]</type>
    <location> </location>
    <title> </title>
    <description> </description>
    <updated-at type="datetime"> </updated-at>

    <!-- does not exist for results of type 'Milestone' or 'Ticket' -->
    <author-id> </author-id>

    <!-- exists only for results of type 'Milestone' -->
    <archived> </archived>
    <completed> </completed>
    <due-on> </due-on>

    <!-- exists only for results of type 'Ticket' -->
    <status> </status>

  </result>
  ...
</results>
Example:
curl -i -u username:password -X GET \\
  -H 'Accept: application/xml' \\
  'https://mysubdomain.unfuddle.com/api/v1/projects/87534/search.xml?query=john+support+dashboard'

Project Dump

Returns a dump of all data models in the project in XML format. This is equivalent to the XML file that appears in a comprehensive backup. For a comprehensive backup including media files and subversion repository dumps, see Project Backups.

URL:
/api/v1/projects/{id}/dump[GET]
Response Formats:
XML
Example:
curl -i -u username:password -X GET \\
  -H 'Accept: application/xml' \\
  'https://mysubdomain.unfuddle.com/api/v1/projects/455/dump.xml'

Backups

The collection represents any user requested Backups within the given Project.

A Backup is comprehensive archive including an XML file representing all data models, media files and subversion repository dumps. Creating a Backup will initiate a request to backup your project. This process usually takes less than 30 minutes. Once Unfuddle has created the backup, the "processed" field is set to true. At this point, the backup can now be downloaded. Note that backups are automatically purged 4 days after their creation.

If a backup is very large (greater than 1 GB) the generated archive will be split into multiple parts. These parts must be individually downloaded and concatenated together before unarchiving. NOTE: parts are numbered beginning with 1.

URL:
/api/v1/projects/{id}/backups[GET, POST]
/api/v1/projects/{id}/backups/{id}[GET, PUT, DELETE]
/api/v1/projects/{id}/backups/{id}/download[GET]
/api/v1/projects/{id}/backups/{id}/parts/{part_number}/download[GET]
Response Formats:
XML, JSON, TGZ
Example:
curl -i -u username:password -X GET \\
  -H 'Accept: application/xml' \\
  'https://mysubdomain.unfuddle.com/api/v1/projects/455/backups/1771.xml'

Components

The collection represents any Components within the given Project.

URL:
/api/v1/projects/{id}/components[GET, POST]
/api/v1/projects/{id}/components/{id}[GET, PUT, DELETE]
Response Formats:
XML, JSON
Request/Response Body:
See component Data Model
Example:
curl -i -u username:password -X GET \\
  -H 'Accept: application/xml' \\
  'https://mysubdomain.unfuddle.com/api/v1/projects/500/components.xml'

Severities

The collection represents any ticket Severities within the given Project.

URL:
/api/v1/projects/{id}/severities[GET, POST]
/api/v1/projects/{id}/severities/{id}[GET, PUT, DELETE]
Response Formats:
XML, JSON
Request/Response Body:
See severity Data Model
Example:
curl -i -u username:password -X GET \\
  -H 'Accept: application/xml' \\
  'https://mysubdomain.unfuddle.com/api/v1/projects/500/severities.xml'

Versions

The collection represents any Versions within the given Project.

URL:
/api/v1/projects/{id}/versions[GET, POST]
/api/v1/projects/{id}/versions/{id}[GET, PUT, DELETE]
Response Formats:
XML, JSON
Request/Response Body:
See version Data Model
Example:
curl -i -u username:password -X GET \\
  -H 'Accept: application/xml' \\
  'https://mysubdomain.unfuddle.com/api/v1/projects/500/versions.xml'

CustomFieldValues

CustomFieldValues may be assigned to any one of the three custom ticket fields within the project. The collection represents all CustomFieldValues within the given project.

Each project has three custom ticket fields. Each field can be marked as active or inactive dictating whether or not they should be shown in the web interface. The custom fields can also have one of two different dispositions: "list" or "text". The "list" disposition allows an administrator to specify a set list of possible values while the "text" disposition allows for the input of arbitrary values during creation or edit of a ticket.

URL:
/api/v1/projects/{id}/custom_field_values[GET, POST]
/api/v1/projects/{id}/custom_field_values/{id}[GET, PUT, DELETE]
Response Formats:
XML, JSON
Request/Response Body:
See custom_field_value Data Model
Example:
curl -i -u username:password -X GET \\
  -H 'Accept: application/xml' \\
  'https://mysubdomain.unfuddle.com/api/v1/projects/500/custom_field_values.xml'

Custom Statuses

Custom statuses are defined at the project level.

By default, four statuses are created for every new project: new, accepted, resolved and closed. New and closed are mandatory and cannot be modified or removed.

Adding new statuses and editing or deleting existing ones can be achieved with a PUT request on the desired project.

Note: On each PUT request all custom statuses must to be sent in the request. Statuses stored on the project object that are not present in the request will be deleted.

URL:
/api/v1/projects/{id}[PUT]
Response Formats:
XML, JSON
Request Body:
See Project Data Model
Example:
curl -i -u username:password -X PUT \\
  -H 'Accept: application/xml' \\
  -H 'Content-type: application/xml' \\
  -d '<project><statuses type="array"><status><name>custom status</name></status></statuses></project>' \\
  'https://mysubdomain.unfuddle.com/api/v1/projects/500.xml'