Monorail API v1

Monorail API v1 aims to provide nearly identical interface to Google Code issue tracker's API for existing clients' smooth transition. You can get a high-level overview from the documents below.

Rate limiting:

  • We count requests for each signed in account.
  • The rate limit is currently 450 requests per minute. We can adjust that per-account if needed.
  • We enforce the limit in a five-minute window, so 2250 requests are allowed within any given 5 minutes.
  • Individual requests that take more than 5s count as 2 requests. This could happen for complex issue searches, especially free text and negated free text terms.
  • If the client exceeds the rate limit, it will get response code 400, in which case it should wait and try again.
  • These parameters are defined in settings.py and framework/ratelimiter.py.

This API provides the following methods to read/write user/issue/comment objects in Monorail:

monorail.groups.create

  • Description: Create a new user group.
  • Permission: The requester needs permission to create groups.
  • Parameters:
    • groupName(required, string): The name of the group to create.
    • who_can_view_members(required, string): The visibility setting of the group. Available options are 'ANYONE', 'MEMBERS' and 'OWNERS'.
    • ext_group_type(string): The type of the source group if the new group is imported from the source. Available options are 'BAGGINS', 'CHROME_INFRA_AUTH' and 'MDB'.
  • Return message:
    • groupID(int): The ID of the newly created group.
  • Error code:
    • 400: The group already exists.
    • 403: The requester has no permission to create a group.

monorail.groups.get

  • Description: Get a group's settings and users.
  • Permission: The requester needs permission to view this group.
  • Parameters:
    • groupName(required, string): The name of the group to view.
  • Return message:
    • groupID(int): The ID of the newly created group.
    • groupSettings(dict):
      • groupName(string): The name of the group.
      • who_can_view_members(string): The visibility setting of the group.
      • ext_group_type(string): The type of the source group.
      • last_sync_time(int): The timestamp when the group was last synced from the source. This field is only meaningful for groups with ext_group_type set.
    • groupOwners(list): A list of group owners' emails.
    • groupMembers(list): A list of group members' emails.
  • Error code:
    • 403: The requester has no permission to view this group.
    • 404: The group does not exist.

monorail.groups.settings.list

  • Description: List all group settings.
  • Permission: None.
  • Parameters:
    • importedGroupsOnly(boolean): A flag indicating whether only fetching settings of imported groups. The default is False.
  • Return message:
    • groupSettings(list of dict):
      • groupName(string): The name of the group.
      • who_can_view_members(string): The visibility setting of the group.
      • ext_group_type(string): The type of the source group.
      • last_sync_time(int): The timestamp when the group was last synced from the source. This field is only meaningful for groups with ext_group_type set.
  • Error code: None.

monorail.groups.update

  • Description: Update a group's settings and users.
  • Permission: The requester needs permission to edit this group.
  • Parameters:
    • groupName(required, string): The name of the group to edit.
    • who_can_view_members(string): The visibility setting of the group.
    • ext_group_type(string): The type of the source group.
    • last_sync_time(int): The timestamp when the group was last synced from the source.
    • body(dict):
      • groupOwners(list of string): A list of owner emails.
      • groupMembers(list of string): A list of member emails.
  • Return message: Empty.
  • Error code:
    • 403: The requester has no permission to edit this group.

monorail.issues.comments.delete

  • Description: Delete a comment.
  • Permission: The requester needs permission to delete this comment.
  • Parameters:
    • projectId(required, string): The name of the project.
    • issueId(required, int): The ID of the issue.
    • commentId(required, int): The ID of the comment.
  • Return message: Empty.
  • Error code:
    • 403: The requester has no permission to delete this comment.
    • 404: The issue and/or comment does not exist.

monorail.issues.comments.insert

  • Description: Add a comment.
  • Permission: The requester needs permission to comment an issue.
  • Parameters:
    • projectId(required, string): The name of the project.
    • issueId(required, int): The ID of the issue.
    • sendEmail(boolean): A flag indicating whether to send notifications. The default is True.
    • Request body(dict):
      • content(string): Content of the comment to add.
      • updates(dict): Issue fields to update.
        • summary(string): The new summary of the issue.
        • status(string): The new status of the issue.
        • owner(string): The new owner of the issue.
        • labels(list of string): The labels to add/remove.
        • cc(list of string): A list of emails to add/remove from cc field.
        • blockedOn(list of string): The ID of the issues on which the current issue is blocked.
        • blocking(list of string): The ID of the issues which the current issue is blocking.
        • mergedInto(string): The ID of the issue to merge into.
        • components(list of string): The components to add/remove.
  • Return message:
    • author(dict):
      • htmlLink(string): The link to the author profile.
      • name(string): The name of the author.
    • canDelete(boolean): Whether current requester could delete the new comment.
    • content(string): Content of the new comment.
    • id(int): ID of the new comment.
    • published(string): Published datetime of the new comment.
    • updates(dict): Issue fields updated by the new comment.
  • Error code:
    • 403: The requester has no permission to comment this issue.
    • 404: The issue does not exist.

monorail.issues.comments.list

  • Description: List all comments for an issue.
  • Permission: The requester needs permission to view this issue.
  • Parameters:
    • projectId(required, string): The name of the project.
    • issueId(required, int): The ID of the issue.
    • maxResults(int): The max number of comments to retrieve in one request. The default is 100.
    • startIndex(int): The starting index of comments to retrieve. The default is 0.
  • Return message:
    • totalResults(int): Total number of comments retrieved.
    • items(list of dict): A list of comments.
      • attachments(dict): The attachment of this comment.
      • author(dict): The author of this comment.
      • canDelete(boolean): Whether the requester could delete this comment.
      • content(string): Content of this comment.
      • deletedBy(dict): The user who has deleted this comment.
      • id(int): The ID of this comment.
      • published(string): Published datetime of this comment.
      • updates(dict): Issue fields updated by this comment.
  • Error code:
    • 403: The requester has no permission to view this issue.
    • 404: The issue does not exist.

monorail.issues.comments.undelete

  • Description: Restore a deleted comment.
  • Permission: The requester needs permission to delete this comment.
  • Parameters:
    • projectId(required, string): The name of the project.
    • issueId(required, int): The ID of the issue.
    • commentId(required, int): The ID of the comment.
  • Return message: Empty.
  • Error code:
    • 403: The requester has no permission to delete this comment.
    • 404: The issue and/or comment does not exist.

monorail.issues.get

  • Description: Get an issue.
  • Permission: The requester needs permission to view this issue.
  • Parameters:
    • projectId(required, string): The name of the project.
    • issueId(required, int): The ID of the issue.
  • Return message:
    • id(int): ID of this issue.
    • summary(string): Summary of this issue.
    • stars(int): Number of stars of this issue.
    • starred(boolean): Whether this issue is starred by the requester.
    • status(string): Status of this issue.
    • state(string): State of this issue. Available values are 'closed' amd 'open'.
    • labels(list of string): Labels of this issue.
    • author(dict): The reporter of this issue.
    • owner(dict): The owner of this issue.
    • cc(list of dict): The list of emails to cc.
    • updated(string): Last updated datetime of this issue.
    • published(string): Published datetime of this issue.
    • closed(string): Closed datetime of this issue.
    • blockedOn(list of dict): The issues on which the current issue is blocked.
    • blocking(list of dict): The issues which the current issue is blocking.
    • projectId(string): The name of the project.
    • canComment(boolean): Whether the requester can comment on this issue.
    • canEdit(boolean): Whether the requester can edit this issue.
    • components(list of string): Components of the issue.
  • Error code:
    • 403: The requester has no permission to view this issue.
    • 404: The issue does not exist.

monorail.issues.insert

  • Description: Add a new issue.
  • Permission: The requester needs permission to create a issue.
  • Parameters:
    • projectId(required, string): The name of the project.
    • sendEmail(boolean): A flag indicating whether to send notifications. The default is True.
    • body(dict):
      • blockedOn(list of dict): The issues on which the current issue is blocked.
      • blocking(list of dict): The issues which the current issue is blocking.
      • cc(list of dict): The list of emails to cc.
      • description(required, string): Content of the issue.
      • labels(list of string): Labels of this issue.
      • owner(dict): The owner of this issue.
      • status(required, string): Status of this issue.
      • summary(requred, string): Summary of this issue.
      • components(list of string): Components of this issue.
  • Return message:
    • id(int): ID of this issue.
    • summary(string): Summary of this issue.
    • stars(int): Number of stars of this issue.
    • starred(boolean): Whether this issue is starred by the requester.
    • status(string): Status of this issue.
    • state(string): State of this issue. Available values are 'closed' and 'open'.
    • labels(list of string): Labels of this issue.
    • author(dict): The reporter of this issue.
    • owner(dict): The owner of this issue.
    • cc(list of dict): The list of emails to cc.
    • updated(string): Last updated datetime of this issue.
    • published(string): Published datetime of this issue.
    • closed(string): Closed datetime of this issue.
    • blockedOn(list of dict): The issues on which the current issue is blocked.
    • blocking(list of dict): The issues which the current issue is blocking.
    • projectId(string): The name of the project.
    • canComment(boolean): Whether the requester can comment on this issue.
    • canEdit(boolean): Whether the requester can edit this issue.
    • components(list of string): Components of this issue.
  • Error code:
    • 403: The requester has no permission to create a issue.

monorail.issues.list

  • Description: List issues for projects.
  • Permission: The requester needs permission to view issues in requested projects.
  • Parameters:
    • projectId(required, string): The name of the project.
    • additionalProject(list of string): Additional projects to search issues.
    • can(string): Canned query. Available values are 'all', 'new', 'open', 'owned', 'starred' and 'to_verify'.
    • label(string): Search for issues with this label.
    • maxResults(int): The max number of issues to retrieve in one request. The default is 100.
    • owner(string): Search for issues with this owner.
    • publishedMax(int): Search for issues published before the timestamp.
    • publishedMin(int): Search for issues published after the timestamp.
    • q(string): Custom query criteria, e.g. 'status:New'.
    • sort(string): Fields to sort issues by.
    • startIndex(int): The starting index of issues to retrieve. The default is 0.
    • status(string): Search for issues of this status.
    • updatedMax(int): Search for issues updated before the timestamp.
    • updatedMin(int): Search for issues updated after the timestamp.
  • Return message:
    • totalResults(int): Total number of issues retrieved.
    • items(list of dict): A list of issues.
      • author(dict): The reporter of this issue.
      • blockedOn(list of dict): The issues on which the current issue is blocked.
      • blocking(list of dict): The issues which the current issue is blocking.
      • canComment(boolean): Whether the requester can comment on this issue.
      • canEdit(boolean): Whether the requester can edit this issue.
      • cc(list of dict): The list of emails to cc.
      • closed(string): Closed datetime of this issue.
      • description(string): Content of this issue.
      • id(int): ID of this issue.
      • labels(list of string): Labels of this issue.
      • owner(dict): The owner of this issue.
      • published(string): Published datetime of this issue.
      • starred(boolean): Whether this issue is starred by the requester.
      • stars(int): Number of stars of this issue.
      • state(string): State of this issue. Available values are 'closed' and 'open'.
      • status(string): Status of this issue.
      • summary(string): Summary of this issue.
      • updated(string): Last updated datetime of this issue.
  • Error code:
    • 403: The requester has no permission to view issues in the projects.

monorail.users.get

  • Description: Get a user.
  • Permission: None.
  • Parameters:
    • userId(required, string): The email of the user.
    • ownerProjectsOnly(boolean): Whether to only return projects the user owns. The default is False.
  • Return message:
    • projects(dict):
      • name(string): The name of the project.
      • htmlLink(string): The relative url of this project.
      • summary(string): Summary of this project.
      • description(string): Description of this project.
      • role(string): Role of the user in this project.
      • issuesConfig(dict): Issue configurations.
  • Error code: None.

monorail.components.create

  • Description: Create a component.
  • Permission: The requester needs permission to edit the requested project.
  • Parameters:
    • projectId(required, string): The name of the project.
    • componentName(required, string): The leaf name of the component to create.
    • body(dict):
      • parentPath(string): Full path of the parent component.
      • description(string): Description of the new component.
      • admin(list of string): A list of user emails who can administer this component.
      • cc(list of string): A list of user emails who will be added to cc list when this component is added to an issue.
      • deprecated(boolean): A flag indicating whether this component is deprecated. The default is False.
  • Return message:
    • componentId(int): The ID of the new component.
    • projectName(string): The name of the project this new component belongs to.
    • componentPath(string): The full path of the component.
    • description(string): Description of the new component.
    • admin(list of string): A list of user emails who can administer this component.
    • cc(list of string): A list of user emails who will be added to cc list when this component is added to an issue.
    • deprecated(boolean): A flag indicating whether this component is deprecated.
    • created(datetime): Created datetime.
    • creator(string): Email of the creator.
    • modified(datetime): Last modified datetime.
    • modifier(string): Email of last modifier.
  • Error code:
    • 400: The component name is invalid or already in use.
    • 403: The requester has no permission to create components in the project.
    • 404: The parent component does not exist, or the project does not exist.

monorail.components.delete

  • Description: Delete a component.
  • Permission: The requester needs permission to edit the requested component.
  • Parameters:
    • projectId(required, string): The name of the project.
    • componentPath(required, string): The full path of the component to delete.
  • Return message: None.
  • Error code:
    • 403: The requester has no permission to delete this component, or tries to delete component that has subcomponents.
    • 404: The component does not exist, or the project does not exist.

monorail.components.list

  • Description: List all components of a given project.
  • Permission: None.
  • Parameters:
    • projectId(required, string): The name of the project.
  • Return message:
    • components(list of dict):
      • componentId(int): The ID of the new component.
      • projectName(string): The name of the project this new component belongs to.
      • componentPath(string): The full path of the component.
      • description(string): Description of the new component.
      • admin(list of string): A list of user emails who can administer this component.
      • cc(list of string): A list of user emails who will be added to cc list when this component is added to an issue.
      • deprecated(boolean): A flag indicating whether this component is deprecated.
      • created(datetime): Created datetime.
      • creator(string): Email of the creator.
      • modified(datetime): Last modified datetime.
      • modifier(string): Email of last modifier.
  • Error code:
    • 403: The requester has no permission to delete this component, or tries to delete component that has subcomponents.
    • 404: The project does not exist.

monorail.components.update

  • Description: Update a component.
  • Permission: The requester needs permission to edit the requested component.
  • Parameters:
    • projectId(required, string): The name of the project.
    • componentPath(required, string): The full path of the component to delete.
    • updates(list of dict):
      • field(required, string): Component field to update. Available options are 'LEAF_NAME', 'DESCRIPTION', 'ADMIN', 'CC' and 'DEPRECATED'.
      • leafName(string): The new leaf name of the component.
      • description(string): The new description of the component.
      • admin(list of string): The new list of user emails who can administer this component.
      • cc (list of string): The new list of user emails who will be added to cc list when this component is added to an issue.
      • deprecated(boolean): The new boolean value indicating whether this component is deprecated.
  • Return message: None.
  • Error code:
    • 400: The new component name is invalid or already in use.
    • 403: The requester has no permission to edit this component.
    • 404: The component does not exist, or the project does not exist.