Overview

The annotations API lets you attach external actions (e.g. build failures, mentions in IRC, etc.) to a given item's activity feed. Every annotation is comprised of a label (e.g. "Jenkins"), action (e.g. "broke the build"), and a free-form Markdown body. Annotations added to an item will also trigger an email alert to the people working on that item.

Example Annotation

/api/products/{product_id}/items/{item_number}/annotations.json

GET

Return a list of item annotation objects for the given item_number.

Arguments

This endpoint takes no arguments.

Example Response

[
    {
        "action": "broke the build", 
        "body": "Tests are broken", 
        "id": 17, 
        "user": {
            "created_at": "2012-05-15T19:58:45+00:00", 
            "email": "joe@joestump.net", 
            "first_name": "Joe", 
            "id": 1, 
            "last_login": "2012-07-12T22:11:37+00:00", 
            "last_name": "Stump"
        }, 
        "verb": "Jenkins"
    }
]

Error Codes

404 If item_number or product_id are invalid or unknown.

POST

Sending an HTTP POST to this endpoint will append a new annotation to the given item_number on behalf of the user making the request. NOTE: This will also trigger an email alert to the team working on the given item_number with details about the new annotation.

Arguments

label (string) The generic label for the action. We suggest using the name of the software that triggered the event (e.g. Jenkins, Campfire, or HipChat). This is used to group similar actions.
action (string) The action that was performed by the user in the third party software. Remember that this is appended to the user's name who performed the action. (e.g. "Joe broke the build." would have an action of "broke the build.").
body (string, Markdown) A free-form field that allows you to add more contextual data to the annotation. This will be hidden behind a click in the activity feed.

Example Response

{
    "action": "broke the build", 
    "body": "Tests are broken", 
    "id": 17, 
    "user": {
        "created_at": "2012-05-15T19:58:45+00:00", 
        "email": "joe@joestump.net", 
        "first_name": "Joe", 
        "id": 1, 
        "last_login": "2012-07-12T22:11:37+00:00", 
        "last_name": "Stump"
    }, 
    "verb": "Jenkins"
}

Error Codes

404 If item_number or product_id are invalid or unknown.