STACK API - Data Models

Data Models

Account,
Attachment,
Backup,
Changeset,
Comment,
Component,
CustomFieldValue,
Involvement,
Message,
Milestone,
Notebook,
Page,
Person,
Project,
Repository,
Severity,
Subscription,
Ticket,
TicketAssociation,
TicketReport,
TimeEntry,
Version

Introduction

The following list contains definitions for all data models used in the STACK API.

All field values are strings unless otherwise specified via the 'type' attribute.

If the value of a field is restricted to closed set of values, these values have been provided in brackets [v1,v2,etc].

Read/write fields are normal colored, versus read only fields which are red.

If the model is returned in a response body as something other than XML, then the fields will be the same, but the format will naturally be different (i.e. fields in JSON will have underscores, not dashes).

When using the query string parameter "formatted=true", all "created_at" and "updated_at" fields will have the formatted counterparts "created_at_formatted" and "updated_at_formatted".

Account

<account>
  <access-key> </access-key>
  <created-at type="datetime"> </created-at>
  <default-ticket-report-id type="integer"> </default-ticket-report-id>
  <default-time-zone> <!-- i.e. "Pacific Time (US & Canada)" --> </default-time-zone>
  <description> </description>
  <disk-usage type="integer"> <!-- in Kilobytes --> </disk-usage>
  <id type="integer"> </id>
  <plan> [private, micro, compact, corporate, enterprise] </plan>
  <subdomain> </subdomain>
  <!-- a list with valid markups; the first value is the default one -->
  <text-markup> [markdown, textile, plain] </text-markup>
  <title> </title>
  <updated-at type="datetime"> </updated-at>

  <!-- the following is read-only and describes the feature set of an account -->
  <features>
    <attachments type="boolean"> [true, false] </attachments>
    <ssl type="boolean"> [true, false] </ssl>
    <storage type="integer"> <!-- in Megabytes --> </storage>
    <time-tracking type="boolean"> [true, false] </time-tracking>
  </features>
</account>

Attachment

<attachment>
  <content-type> </content-type>
  <created-at type="datetime"> </created-at>
  <filename> </filename>
  <id type="integer"> </id>
  <parent-id type="integer"> </parent-id>
  <parent-type> [Message, Ticket, Notebook, Comment] </parent-type>
  <size> </size>
  <updated-at type="datetime"> </updated-at>

  <!--
  when creating a new attachment, the following section must also
  be including in order to reference the upload key you received
  after uploading the file to the API
  -->
  <upload>
    <key> </key>
  </upload>
</attachment>

Backup

<backup>
  <created-at type="datetime"> </created-at>
  <id type="integer"> </id>
  <parts type"integer"> </parts>
  <processed type="boolean"> [true, false] </processed>
  <processed-at type="datetime"> </processed-at>
  <project-id type="integer"> </project-id>
  <requester-id type="integer"> </requester-id>
</backup>

Changeset

<changeset>
  <!--
  Note that not all repositories systems distinguish between
  the author and committer (i.e. Subversion does not)
  -->
  <author-id type="integer"> </author-id>
  <author-name> </author-name>
  <author-email> </author-email>
  <author-date type="datetime"> <!-- the date the patch was authored --> </author-date>
  <committer-id type="integer"> </committer-id>
  <committer-name> </committer-name>
  <committer-email> </committer-email>
  <committer-date type="datetime"> <!-- the date of the commit --> </committer-date>
  <created-at type="datetime"> </created-at>
  <id type="integer"> </id>
  <message> </message>
  <message-formatted> <!-- only available if formatted=true --> </message-formatted>
  <repository-id type="integer"> </repository-id>
  <revision> </revision>
</changeset>

Comment

<comment>
  <author-id type="integer"> </author-id>
  <body> </body>
  <body-format> [markdown, textile, plain] </body-format>
  <body-formatted> <!-- only available if formatted=true --> </body-formatted>
  <created-at type="datetime"> </created-at>
  <id type="integer"> </id>
  <parent-id type="integer"> </parent-id>
  <parent-type> [Message, Ticket] </parent-type>
  <updated-at type="datetime"> </updated-at>

  <attachments type="array"><!-- only available for GET requests if attachments=true -->
    <attachment>...</attachment>
    ...
  </attachments>
</comment>

Component

<component>
  <created-at type="datetime"> </created-at>
  <id type="integer"> </id>
  <name> </name>
  <project-id type="integer"> </project-id>
  <updated-at type="datetime"> </updated-at>
</component>

CustomFieldValue

<custom-field-value>
  <created-at type="datetime"> </created-at>
  <field-number type="integer"> [1, 2, 3] </field-number>
  <id type="integer"> </id>
  <project-id type="integer"> </project-id>
  <updated-at type="datetime"> </updated-at>
  <value> </value>
</custom-field-value>

Involvement

<involvement>
  <created-at type="datetime"> </created-at>
  <id type="integer"> </id>
  <!--
  Within the Involvement model, setting 'is-administrator' to true will
  make the person a project administrator for the given project.
  -->
  <is-administrator type="boolean"> [true, false] </is-administrator>
  <messages> [none, read, readcreate, manage] </messages>
  <milestones> [none, read, manage] </milestones>
  <notebooks> [none, read, manage] </notebooks>
  <people> [none, read, invite, manage] </people>
  <person-id type="integer"> </person-id>
  <project-id type="integer"> </project-id>
  <source> [none, read, commit] </source>
  <tickets> [none, read, create, readcreate, manage] </tickets>
  <updated-at type="datetime"> </updated-at>
</involvement>

Message

<message>
  <author-id type="integer"> </author-id>
  <body> </body>
  <body-format> [markdown, textile, plain] </body-format>
  <body-formatted> <!-- only available if formatted=true --> </body-formatted>
  <created-at type="datetime"> </created-at>
  <id type="integer"> </id>
  <project-id type="integer"> </project-id>
  <title> </title>
  <updated-at type="datetime"> </updated-at>

  <!--
  If categories are specified on UPDATE, then the existing categories
  will be completely replaced by the newly provided categories.
  -->
  <categories>
    <category id="5555"/>
    ...
  </categories>

  <comments type="array"><!-- only available for GET requests if comments=true -->
    <comment></comment>
    ...
  </comments>

  <attachments type="array"><!-- only available for GET requests if attachments=true -->
    <attachment>...</attachment>
    ...
  </attachments>
</message>

Milestone

<milestone>
  <archived type="boolean"> [true, false] </archived>
  <completed type="boolean"> [true, false] </completed>
  <created-at type="datetime"> </created-at>
  <description> </description>
  <due-on type="date"> </due-on>
  <due-on-formatted> </due-on-formatted>
  <id type="integer"> </id>
  <person-responsible-id type="integer"> </person-responsible-id>
  <project-id type="integer"> </project-id>
  <title> </title>
  <updated-at type="datetime"> </updated-at>
</milestone>

Notebook

<notebook>
  <created-at type="datetime"> </created-at>
  <default-page-id type="integer"> </default-page-id>
  <id type="integer"> </id>
  <project-id type="integer"> </project-id>
  <title> </title>
  <updated-at type="datetime"> </updated-at>

  <attachments type="array"><!-- only available for GET requests if attachments=true -->
    <attachment>...</attachment>
    ...
  </attachments>
</notebook>

Page

<page>
  <author-id type="integer"> </author-id>
  <body> </body>
  <body-format> [markdown, textile, plain] </body-format>
  <body-formatted> <!-- only available if formatted=true --> </body-formatted>
  <created-at type="datetime"> </created-at>
  <id type="integer"> </id>
  <message> </message>
  <message-formatted> <!-- only available if formatted=true --> </message-formatted>
  <notebook-id type="integer"> </notebook-id>
  <number type="integer"> </number>
  <title> </title>
  <updated-at type="datetime"> </updated-at>
  <version type="integer"> </version>

  <!--
  This is not an actual attribute, but when updating a page,
  including this boolean and setting it to true will cause the
  page to be overwritten as a minor change.
  -->
  <minor type="boolean"> [true, false] </minor>
</page>

Person

<person>
  <!-- only available for the /api/v1/people/current endpoint -->
  <access-key> </access-key>
  <account-id type="integer"> </account-id>
  <created-at type="datetime"> </created-at>
  <email> </email>
  <first-name> </first-name>
  <id type="integer"> </id>
  <!--
  Within the Person model, setting 'is-administrator' to true will
  make the person an account administrator.
  -->
  <is-administrator type="boolean"> [true, false] </is-administrator>
  <is-removed type="boolean"> [true, false] </is-removed>
  <last-name> </last-name>
  <last-signed-in type="datetime"> </last-signed-in>
  <last-signed-in-formatted> <!-- only available if formatted=true --> </last-signed-in-formatted>
  <notification-frequency> [immediate, 30mins, hourly, dailyam, dailypm, never] </notification-frequency>
  <notification-ignore-self type="boolean"> [true, false] </notification-ignore-self>
  <notification-last-sent type="datetime"> </notification-last-sent>
  <notification-scope-messages> [all, none] </notification-scope-messages>
  <notification-scope-milestones> [all, none] </notification-scope-milestones>
  <notification-scope-source> [all, none] </notification-scope-source>
  <notification-scope-tickets> [all, involved, none] </notification-scope-tickets>
  <show-help-messages type="boolean"> [true, false] </show-help-messages>
  <text-markup> [markdown, textile, plain] </text-markup>
  <time-zone> <!-- i.e. "Pacific Time (US & Canada)" --> </time-zone>
  <updated-at type="datetime"> </updated-at>
  <!-- The username it is not available for removed people -->
  <username> </username>
</person>

Project

<project>
  <account-id type="integer"> </account-id>
  <archived type="boolean"> [true, false] </archived>
  <assignee-on-resolve> [reporter, none, nochange] </assignee-on-resolve>
  <backup-frequency type="integer">0</backup-frequency>
  <close-ticket-simultaneously-default type="boolean"> [true, false] </close-ticket-simultaneously-default>
  <created-at type="datetime"> </created-at>
  <default-ticket-report-id type="integer"> </default-ticket-report-id>
  <description> </description>
  <disk-usage type="integer"> <!-- in Kilobytes --> </disk-usage>
  <enable-time-tracking type="boolean"> [true, false] </enable-time-tracking>
  <id type="integer"> </id>
  <s3-access-key-id></s3-access-key-id>
  <s3-backup-enabled type="boolean">false</s3-backup-enabled>
  <s3-bucket-name></s3-bucket-name>
  <short-name> </short-name>
  <!-- Custom statuses inclusion is still experimental -->
  <statuses type="array">
    <status>
      <name> </name>
      <color> </name>
      <id> </id>
    </status>
    ...
  </statuses>
  <theme> [blue, green, grey, orange, purple, red, teal] </theme>
  <ticket-field1-active type="boolean"> [true, false] </ticket-field1-active>
  <ticket-field1-title> </ticket-field1-title>
  <ticket-field1-disposition> [list, text] </ticket-field1-disposition>
  <ticket-field2-active type="boolean"> [true, false] </ticket-field2-active>
  <ticket-field2-title> </ticket-field2-title>
  <ticket-field2-disposition> [list, text] </ticket-field2-disposition>
  <ticket-field3-active type="boolean"> [true, false] </ticket-field3-active>
  <ticket-field3-title> </ticket-field3-title>
  <ticket-field3-disposition> [list, text] </ticket-field3-disposition>
  <title> </title>
  <updated-at type="datetime"> </updated-at>
</project>

Repository

<repository>
  <abbreviation> </abbreviation>
  <account-id type="integer"> </account-id>
  <created-at type="datetime"> </created-at>
  <description> </description>
  <id type="integer"> </id>
  <system> [git,svn] </system>
  <title> </title>
  <updated-at type="datetime"> </updated-at>

  <!--
  If projects are specified on UPDATE, then the existing projects
  will be completely replaced by the newly provided projects.
  -->
  <projects>
    <project id="22222"/>
    ...
  </projects>
</repository>

Severity

<severity>
  <created-at type="datetime"> </created-at>
  <id type="integer"> </id>
  <name> </name>
  <project-id type="integer"> </project-id>
  <updated-at type="datetime"> </updated-at>
</severity>

Subscription

<subscription>
  <created-at type="datetime"> </created-at>
  <id type="integer"> </id>
  <parent-id type="integer"> </parent-id>
  <parent-type> [Ticket] </parent-type>
  <person-id type="integer"> </person-id>
  <updated-at type="datetime"> </updated-at>
</subscription>

Ticket

<ticket>
  <assignee-id type="integer"> </assignee-id>
  <component-id type="integer"> </component-id>
  <created-at type="datetime"> </created-at>
  <description> </description>
  <description-format> [markdown, textile, plain] </description-format>
  <description-formatted> <!-- only available if formatted=true --> </description-formatted>
  <due-on type="date"> </due-on>
  <due-on-formatted> </due-on-formatted>
  <field1-value-id="integer"> </field1-value-id>
  <field2-value-id="integer"> </field2-value-id>
  <field3-value-id="integer"> </field3-value-id>
  <hours-estimate-current type="float"> </hours-estimate-current>
  <hours-estimate-initial type="float"> </hours-estimate-initial>
  <id type="integer"> </id>
  <milestone-id type="integer"> </milestone-id>
  <number type="integer"> </number>
  <priority> [1, 2, 3, 4, 5] </priority>
  <project-id type="integer"> </project-id>
  <reporter-id type="integer"> </reporter-id>
  <resolution> [fixed, works_for_me, postponed, duplicate, will_not_fix, invalid] </resolution>
  <resolution-description> </resolution-description>
  <resolution-description-format> [markdown, textile, plain] </resolution-description-format>
  <resolution-description-formatted> <!-- only available if formatted=true --> </resolution-description-formatted>
  <severity-id type="integer"> </severity-id>
  <status> [new, unaccepted, reassigned, reopened, accepted, resolved, closed] </status>
  <summary> </summary>
  <updated-at type="datetime"> </updated-at>
  <version-id type="integer"> </version-id>

  <!--
  The following are not actual ticket attributes, but when creating or updating
  a ticket, including any of these three attributes instead of the corresponding
  <fieldN-value-id> attributes will allow you to create a new value for
  the ticket field if that field is of the "text" disposition.
  -->
  <field1-value> </field1-value>
  <field2-value> </field2-value>
  <field3-value> </field3-value>

  <comments type="array"><!-- only available for GET requests if comments=true -->
    <comment></comment>
    ...
  </comments>

  <attachments type="array"><!-- only available for GET requests if attachments=true -->
    <attachment>...</attachment>
    ...
  </attachments>
</ticket>

TicketAssociation

<ticket-association>
  <created-at type="datetime"> </created-at>
  <id type="integer"> </id>
  <relationship> [parent, duplicate, related] </relationship>
  <ticket1-id type="integer"> </ticket1-id>
  <ticket2-id type="integer"> </ticket2-id>
</ticket-association>

TicketReport

<ticket-report>
  <conditions-string>
    <!--
    A comma or vertical bar separated list of report criteria composed as
      "field-expr-value, field-expr-value | field-expr-value"

      "field" is one of the following: [number, summary, priority, status, resolution, milestone, component, version, severity, reporter, assignee, created_at, updated_at, last_comment_at, due_on, field_1, field_2, field_3]
      "expr" is one of the following: [eq, neq, gt, lt, gteq, lteq]
      "value" is an appropriate value for the given field; "value" can also be "current" for fields that represent people.

    Note: The comma acts as the AND operator and the vertical bar as the OR operator
    Example: "assignee-eq-current,status-eq-closed|status-eq-resolved,milestone-eq-34584"
               translates into
             Assignee is the Current user AND (Status is Closed OR Status is Resolved) AND Milestone is 34584
    -->
  </conditions-string>
  <created-at type="datetime"> </created-at>
  <fields-string>
    <!--
    A comma separated list composed of any or all of the following:

    [project, number, summary, priority, component, version, severity, milestone, due_on, reporter, assignee, status, resolution, comments, associations, hours_estimate_initial, hours_estimate_current, hours_actual, percentage_complete, created_at, updated_at, closed_on, field_1, field_2, field_3]
    -->
  </fields-string>
  <group-by> [project, priority, component, version, severity, milestone, due_on, reporter, assignee, status, resolution, field_1, field_2, field_3] </group-by>
  <id type="integer"> </id>
  <parent-id type="integer"> </parent-id>
  <parent-type> [Account, Project] </parent-type>
  <sort-by> </sort-by>
  <sort-direction> [ASC, DESC] </sort-direction>
  <title> </title>
  <updated-at type="datetime"> </updated-at>

  <!--
  If you 'generate' the report, then the following section will also
  be available in the response.
  -->
  <groups>
    <group>
      <title> </title>
      <tickets>
        <ticket> ... </ticket>
        ...
      </tickets>
    </group>
    ...
  </groups>
</ticket-report>

Time Entry

<time-entry>
  <created-at type="datetime">  </created-at>
  <date type="date"> </date>
  <description> </description>
  <hours type="float"> </hours>
  <id type="integer"> </id>
  <person-id type="integer"> </person-id>
  <ticket-id type="integer"> </ticket-id>
  <updated-at type="datetime"> </updated-at>
</time-entry>

Version

<version>
  <created-at type="datetime"> </created-at>
  <id type="integer"> </id>
  <name> </name>
  <project-id type="integer"> </project-id>
  <updated-at type="datetime"> </updated-at>
</version>

Unfuddle STACK API

Usage Scenarios

Reference