Swarm 2016.1 Guide (May 2016)

Returns the complete list of projects in Swarm.

HTTP/1.1 200 OK

{
  "projects": [
    {
      "id": "testproject",
      "branches": [
        {
          "id": "main",
          "name": "main",
          "paths": ["//depot/main/TestProject/..."],
          "moderators": []
        }
      ],
      "deleted": false,
      "description": "Test test test",
      "followers": [],
      "jobview": "subsystem=testproject",
      "members": ["alice"],
      "name": "TestProject",
      "owners": [],
      "subgroups": []
    }
  ]
}

To list all projects:

curl -u "username:password" "https://my-swarm-host/api/v2/projects?fields=id,description,members,name"

Pagination is not currently supported by this endpoint. Swarm responds with a list of all projects:

{
  "projects": [
    {
      "id": "testproject",
      "description": "Test test test",
      "members": ["alice"],
      "name": "TestProject"
    },
    {
      "id": "testproject2",
      "description": "Test test test",
      "members": ["alice"],
      "name": "TestProject"
    }
  ]
}

Project admins wishing to see the "tests" and "deploy" fields must fetch projects individually.

Retrieve information about a project.

HTTP/1.1 200 OK

{
  "project": {
    "id": "testproject",
    "branches": [
      {
        "id": "main",
        "name": "main",
        "paths": ["//depot/main/TestProject/..."],
        "moderators": []
      }
    ],
    "deleted": false,
    "description": "Test test test",
    "jobview": "subsystem=testproject",
    "members": ["alice"],
    "name": "TestProject",
    "owners": [],
    "subgroups": []
  }
}

To fetch an individual project:

curl -u "username:password" \
     "https://my-swarm-host/api/v2/projects/testproject2?fields=id,description,members,name"

Swarm responds with a project entity:

{
  "project": {
    "id": "testproject2",
    "description": "Test test test",
    "members": ["alice"],
    "name": "TestProject 2"
  }
}

Project admins have access to additional fields ("tests" and "deploy") when fetching individual projects using this endpoint.

Creates a new project in Swarm.

HTTP/1.1 200 OK

{
  "project": {
    "id": "testproject",
    "branches": [
      {
        "id": "main",
        "name": "main",
        "paths": ["//depot/main/TestProject/..."],
        "moderators": []
      }
    ],
    "deleted": false,
    "deploy": {"url": "", "enabled": false},
    "description": "Test test test",
    "followers": [],
    "jobview": "subsystem=testproject",
    "members": ["alice"],
    "name": "TestProject",
    "owners": [],
    "subgroups": [],
    "tests": {"url": "", "enabled": false}
  }
}

To create a project:

curl -u "username:password" \
     -d "name=TestProject 3" \
     -d "description=The third iteration of our test project." \
     -d "members[]=alice" \
     -d "members[]=bob" \
     "https://my-swarm-host/api/v2/projects/"

Swarm responds with the new project entity:

{
  "project": {
    "id": "testproject3",
    "branches": [],
    "deleted": false,
    "deploy": {"url": "", "enabled": false},
    "description": "The third iteration of our test project.",
    "followers": [],
    "jobview": "subsystem=testproject",
    "members": ["alice", "bob"],
    "name": "TestProject 3",
    "owners": [],
    "subgroups": [],
    "tests": {"url": "", "enabled": false}
  }
}

Change the settings of a project in Swarm. If a project has owners set, only the owners can perform this action.

HTTP/1.1 200 OK

{
  "project": {
    "id": "testproject",
    "branches": [
      {
        "id": "main",
        "name": "main",
        "paths": ["//depot/main/TestProject/..."],
        "moderators": []
      }
    ],
    "deleted": false,
    "deploy": {"url": "", "enabled": false},
    "description": "New Project Description",
    "followers": [],
    "jobview": "subsystem=testproject",
    "members": ["alice"],
    "name": "TestProject",
    "owners": [],
    "subgroups": [],
    "tests": {"url": "", "enabled": false}
  }
}

To edit a project:

curl -u "username:password" \
     -X PATCH
     -d "description=Witness the power of a fully operational Swarm project." \
     "https://my-swarm-host/api/v2/projects/testproject3"

Swarm responds with the updated project entity:

{
  "project": {
    "id": "testproject3",
    "branches": [],
    "deleted": false,
    "deploy": {"url": "", "enabled": false},
    "description": "Witness the power of a fully operational Swarm project.",
    "followers": [],
    "jobview": "subsystem=testproject",
    "members": ["alice"],
    "name": "TestProject 3",
    "owners": [],
    "subgroups": [],
    "tests": {"url": "", "enabled": false}
  }
}

Mark a Swarm project as deleted. The project ID and name cannot be reused. If a project has owners set, only the owners can perform this action.

HTTP/1.1 200 OK

{
  "id": "testproject"
}

Super users, admins, and owners can delete projects. Members can delete projects that have no owners set.

curl -u "username:password" -X DELETE "https://my-swarm-host/api/v2/projects/testproject3"

Assuming that the authenticated user has permission, Swarm responds with the id of the deleted project:

{
  "id": "testproject3"
}

Retrieve information about a review.

HTTP/1.1 200 OK

{
  "review": {
    "id": 12204,
    "author": "bruno",
    "changes": [10667],
    "commits": [10667],
    "commitStatus": [],
    "created": 1399325913,
    "deployDetails": [],
    "deployStatus": null,
    "description": "Adding .jar that should have been included in r10145\n",
    "participants": {
      "alex_qc": [],
      "bruno": {
        "vote": 1,
        "required": true
      },
      "vera": []
    },
    "pending": false,
    "projects": {
      "swarm": ["main"]
    },
    "state": "archived",
    "stateLabel": "Archived",
    "testDetails": {
      "url": "http://jenkins.example.com/job/project_ci/123/"
    },
    "testStatus": null,
    "type": "default",
    "updated": 1399325913
  }
}

HTTP/1.1 404 Not Found

{
  "error": "Not Found"
}

To fetch a review:

curl -u "username:password" "https://my-swarm-host/api/v2/reviews/123"

Swarm responds with a review entity:

{
  "review": {
    "id": 123,
    "author": "bruno",
    "changes": [122,124],
    "commits": [124],
    "commitStatus": [],
    "created": 1399325913,
    "deployDetails": [],
    "deployStatus": null,
    "description": "Adding .jar that should have been included in r110\n",
    "groups": [],
    "participants": {
      "alex_qc": [],
      "bruno": {
        "vote": 1,
        "required": true
      },
      "vera": []
    },
    "pending": false,
    "projects": {
      "swarm": ["main"]
    },
    "state": "archived",
    "stateLabel": "Archived",
    "testDetails": {
      "url": "http://jenkins.example.com/job/project_ci/123/"
    },
    "testStatus": null,
    "type": "default",
    "updated": 1399325913,
    "versions": []
  }
}

Pass in a changelist ID to create a review. Optionally, you can also provide a description and a list of reviewers.

HTTP/1.1 200 OK

{
  "review": {
    "id": 12204,
    "author": "bruno",
    "changes": [10667],
    "commits": [10667],
    "commitStatus": [],
    "created": 1399325913,
    "deployDetails": [],
    "deployStatus": null,
    "description": "Adding .jar that should have been included in r10145\n",
    "participants": {
      "bruno": []
    },
    "pending": false,
    "projects": [],
    "state": "archived",
    "stateLabel": "Archived",
    "testDetails": [],
    "testStatus": null,
    "type": "default",
    "updated": 1399325913
  }
}

To start a review for a committed change or a non-empty shelved changelist:

curl -u "username:password" -d"change=122" "https://my-swarm-host/api/v2/reviews/"

Swarm responds with the new review entity:

{
  "review": {
    "id": 123,
    "author": "bruno",
    "changes": [122],
    "commits": [],
    "commitStatus": [],
    "created": 1399325913,
    "deployDetails": [],
    "deployStatus": null,
    "description": "Adding .jar that should have been included in r110\n",
    "groups": [],
    "participants": {
      "bruno": []
    },
    "pending": true,
    "projects": [],
    "state": "needsReview",
    "stateLabel": "Needs Review",
    "testDetails": [],
    "testStatus": null,
    "type": "default",
    "updated": 1399325913,
    "versions": []
  }
}

Links the given change to the review and schedules an update.

HTTP/1.1 200 OK

{
  "review": {
    "id": 12204,
    "author": "bruno",
    "changes": [10667, 12000],
    "commits": [10667, 12000],
    "commitStatus": [],
    "created": 1399325913,
    "deployDetails": [],
    "deployStatus": null,
    "description": "Adding .jar that should have been included in r10145\n",
    "participants": {
      "bruno": []
    },
    "pending": false,
    "projects": [],
    "state": "archived",
    "stateLabel": "Archived",
    "testDetails": [],
    "testStatus": null,
    "type": "default",
    "updated": 1399325913
  }
}

You may want to update a review from a shelved or committed change that is different from the initiating change. This is done by adding a change to the review. To add a change:

curl -u "username:password" -d "change=124" "https://my-swarm-host/api/v2/reviews/123/changes/"

Swarm responds with the updated review entity:

{
  "review": {
    "id": 123,
    "author": "bruno",
    "changes": [122, 124],
    "commits": [],
    "commitStatus": [],
    "created": 1399325913,
    "deployDetails": [],
    "deployStatus": null,
    "description": "Adding .jar that should have been included in r110\n",
    "groups": [],
    "participants": {
      "bruno": []
    },
    "pending": true,
    "projects": [],
    "state": "needsReview",
    "stateLabel": "Needs Review",
    "testDetails": [],
    "testStatus": null,
    "type": "default",
    "updated": 1399325913,
    "versions": [
      {
        "difference": 1,
        "stream": null,
        "change": 124,
        "user": "bruno",
        "time": 1399330003,
        "pending": true,
        "archiveChange": 124,
      }
    ]
  }
}

Transition the review to a new state. When transitioning to approved, you can optionally commit the review. (v2+)

Successful Response contains Review Entity:

HTTP/1.1 200 OK

{
  "review": {
    "id": 12204,
    "author": "bruno",
    "changes": [10667, 12000],
    "commits": [],
    "commitStatus": [],
    "created": 1399325913,
    "deployDetails": [],
    "deployStatus": null,
    "description": "Adding .jar that should have been included in r10145\n",
    "participants": {
      "bruno": []
    },
    "pending": false,
    "projects": [],
    "state": "needsRevision",
    "stateLabel": "Needs Revision",
    "testDetails": [],
    "testStatus": null,
    "type": "default",
    "updated": 1399325913
  },
  "transitions": {
    "needsReview": "Needs Review",
    "approved": "Approve",
    "rejected": "Reject",
    "archived": "Archive"
  }
}

Successful Commit contains Review and Commit Entities:

HTTP/1.1 200 OK

{
  "review": {
    "id": 12204,
    "author": "bruno",
    "changes": [10667, 12000, 12006],
    "commits": [12006],
    "commitStatus": {
      "start": 1399326910,
      "change": 12006,
      "status": "Committed",
      "committer": "bruno",
      "end": 1399326911
    },
    "created": 1399325900,
    "deployDetails": [],
    "deployStatus": null,
    "description": "Adding .jar that should have been included in r10145\n",
    "participants": {
      "bruno": []
    },
    "pending": false,
    "projects": [],
    "state": "needsRevision",
    "stateLabel": "Needs Revision",
    "testDetails": [],
    "testStatus": null,
    "type": "default",
    "updated": 1399325905
  },
  "transitions": {
    "needsReview": "Needs Review",
    "needsRevision": "Needs Revision",
    "rejected": "Reject",
    "archived": "Archive"
  },
  "commit": 12006
}

To commit a review:

curl -u "username:password" -d "state=approved" -d "commit=true" \
     "https://my-swarm-host/api/v2/reviews/123/state/"

Swarm responds with the updated review entity, as well as a list of possible transitions for the review:

{
  "review": {
    "id": 123,
    "author": "bruno",
    "changes": [122, 124],
    "commits": [124],
    "commitStatus": {
        "start": 1399326910,
        "change": 124,
        "status": "Committed",
        "committer": "bruno",
        "end": 1399326911
      },
    "created": 1399325913,
    "deployDetails": [],
    "deployStatus": null,
    "description": "Adding .jar that should have been included in r110\n",
    "groups": [],
    "participants": {
      "bruno": []
    },
    "pending": false,
    "projects": [],
    "state": "approved",
    "stateLabel": "Approved",
    "testDetails": [],
    "testStatus": null,
    "type": "default",
    "updated": 1399325913,
    "versions": []
  },
    "transitions": {
      "needsReview": "Needs Review",
      "approved": "Approve",
      "rejected": "Reject",
      "archived": "Archive"
    }
}

List and optionally filter reviews.

Successful Response:

HTTP/1.1 200 OK

{
  "lastSeen": 12206,
  "reviews": [
    {
      "id": 12206,
      "author": "swarm",
      "changes": [12205],
      "comments": 0,
      "commits": [],
      "commitStatus": [],
      "created": 1402507043,
      "deployDetails": [],
      "deployStatus": null,
      "description": "Review Description\n",
      "participants": {
        "swarm": []
      },
      "pending": true,
      "projects": [],
      "state": "needsReview",
      "stateLabel": "Needs Review",
      "testDetails": [],
      "testStatus": null,
      "type": "default",
      "updated": 1402518492
    }
  ],
  "totalCount": 1
}

When no results are found, the "reviews" array will be empty:

HTTP/1.1 200 OK

{
  "lastSeen": null,
  "reviews": [],
  "totalCount": 0
}

Listing reviews

To list reviews:

curl -u "username:password" "https://my-swarm-host/api/v2/reviews?max=2&fields=id,description,author,state"

Swarm responds with a list of the latest reviews, a "totalCount" field, and a "lastSeen" value for pagination:

{
  "lastSeen": 120,
  "reviews": [
    {
      "id": 123,
      "author": "bruno",
      "description": "Adding .jar that should have been included in r110\n",
      "state": "needsReview"
    },
    {
      "id": 120,
      "author": "bruno",
      "description": "Fixing a tyop\n",
      "state": "needsReview"
    }
  ],
  "totalCount": null
}

The "totalCount" field is populated when keywords are supplied. It indicates how many total matches there are. If keywords are not supplied the "totalCount" field remains null, indicating that the list of all reviews is being queried.

Paginating a review listing

To obtain the next page of a reviews list (based on the previous example):

curl -u "username:password" "https://my-swarm-host/api/v2/reviews\
        ?max=2&fields=id,description,author,state&after=120"

Swarm responds with the second page of results, if any reviews are present after the last seen review:

{
  "lastSeen": 100,
  "reviews": [
    {
      "id": 110,
      "author": "bruno",
      "description": "Updating java files\n",
      "state": "needsReview"
    },
    {
      "id": 100,
      "author": "bruno",
      "description": "Marketing materials for our new cutting-edge product\n",
      "state": "needsReview"
    }
  ],
  "totalCount": null
}

Finding reviews for a change or a list of changes

Given a list of change IDs (5, 6, 7), here is how to check if any of them have reviews attached:

curl -u "username:password" "https://my-swarm-host/api/v2/reviews\
     ?max=2&fields=id,changes,description,author,state&change\[\]=5&change\[\]=6&change\[\]=7"

Swarm responds with a list of reviews that include these changes:

{
  "lastSeen": 100,
  "reviews": [
    {
      "id": 110,
      "author": "bruno",
      "changes": [5],
      "description": "Updating java files\n",
      "state": "needsReview"
    },
    {
      "id": 100,
      "author": "bruno",
      "changes": [6,7],
      "description": "Marketing materials for our new cutting-edge product\n",
      "state": "needsReview"
    }
  ],
  "totalCount": 2
}

If no corresponding reviews are found, Swarm responds with an empty reviews list:

{
  "lastSeen": null,
  "reviews": [],
  "totalCount": 0
}

This can be used to determine the currently-installed Swarm version, and also to check that Swarm's API is responding as expected.

HTTP/1.1 200 OK

{
    "year": "2014",
    "version": "SWARM/2014.3-MAIN/885869 (2014/06/25)"
}

Returns the complete list of groups in Swarm.

HTTP/1.1 200 OK

{
  "groups": [
    {
      "Group": "test-group",
      "MaxLockTime": null,
      "MaxResults": null,
      "MaxScanRows": null,
      "Owners": [],
      "PasswordTimeout": null,
      "Subgroups": [],
      "Timeout": 43200,
      "Users": ["nonadmin"],
      "config": {
        "description": "Our testing group",
        "emailFlags": [],
        "name": "Test Group"
      }
    }
  ]
}

Listing groups

To list groups:

curl -u "username:password" \
     "https://myswarm.url/api/v2/groups?keywords=test-group&fields=Group,Owners,Users,config&max=2"

Swarm responds with a list of groups:

{
  "groups": [
    {
      "Group": "test-group",
      "Owners": [],
      "Users": ["nonadmin"],
      "config": {
        "description": "Our testing group",
        "emailFlags": {
          "reviews": "1",
          "commits": "0"
        },
        "name": "Test Group"
      }
    },
    {
      "Group": "test-group2",
      "Owners": [],
      "Users": ["nonadmin"],
      "config": {
        "description": "Our second testing group",
        "emailFlags": [],
        "name": "Test Group 2"
      }
    }
  ],
  "lastSeen": "test-group2"
}

Paginating the groups list

Based on the previous example, we can pass a lastSeen value of "test-group2" to see if there are any subsequent groups in Swarm.

curl -u "username:password" \
     "https://myswarm.url/api/v2/groups?keywords=test-group&fields=Group,config&max=2&lastSeen=test-group2"

Swarm responds with a list of groups (minus the Owners and Users fields, as we haven't requested them):

{
  "groups": [
    {
      "Group": "test-group3",
      "config": {
        "description": "Our 3rd testing group",
        "emailFlags": [],
        "name": "Test Group 3"
      }
    }
  ],
  "lastSeen": "test-group3"
}

Retrieve information about a group.

HTTP/1.1 200 OK

{
  "group": {
    "Group": "test-group",
    "MaxLockTime": null,
    "MaxResults": null,
    "MaxScanRows": null,
    "Owners": [],
    "PasswordTimeout": null,
    "Subgroups": [],
    "Timeout": 43200,
    "Users": ["nonadmin"],
    "config": {
      "description": "Our testing group",
      "emailFlags": [],
      "name": "Test Group"
    }
  }
}

Fetching a group

To fetch an individual group:

curl -u "username:password" "https://myswarm.url/api/v2/groups/my-group"

Swarm responds with the group entity:

{
  "group": {
    "Group": "test-group",
    "LdapConfig": null,
    "LdapSearchQuery": null,
    "LdapUserAttribute": null,
    "MaxLockTime": null,
    "MaxResults": null,
    "MaxScanRows": null,
    "Owners": [],
    "Users": ["nonadmin"],
    "config": {
      "description": "Our testing group",
      "emailFlags": [],
      "name": "Test Group"
    }
  }
}

Limiting returned fields

To limit the returned fields when fetching an individual group:

curl -u "username:password" "https://myswarm.url/api/v2/groups/my-group?fields=Group,Owners,Users,config"

Swarm responds with the group entity:

{
  "group": {
    "Group": "test-group",
    "Owners": [],
    "Users": ["nonadmin"],
    "config": {
      "description": "Our testing group",
      "emailFlags": [],
      "name": "Test Group"
    }
  }
}

Creates a new group in Swarm.

HTTP/1.1 200 OK

{
  "group": {
    "Group": "test-group",
    "MaxLockTime": null,
    "MaxResults": null,
    "MaxScanRows": null,
    "Owners": [],
    "PasswordTimeout": null,
    "Subgroups": [],
    "Timeout": null,
    "Users": ["alice"],
    "config": {
      "description": "Test test test",
      "emailFlags": [],
      "name": "TestGroup"
    }
  }
}

Important:

  - Only users with super privileges in the Helix Versioning Engine (p4d),
    or users with admin privileges in p4d versions 2012.1 or newer, can
    create groups.
  - This API version is only capable of setting specific fields:
       Group, Users, Owners, Subgroups, config
    Any other fields specified in the creation request are ignored.

To create a new group:

curl -u "username:password" \
     -d "Group=my-group" \
     -d "Owners[]=alice" \
     -d "Owners[]=bob" \
     -d "Users[]=bruno" \
     -d "Users[]=user2" \
     -d "config[description]=This group is special to me." \
     -d "config[name]=My Group" \
     -d "config[emailFlags][reviews]=1" \
     -d "config[emailFlags][commits]=0" \
     "https://myswarm.url/api/v2/groups"

Assuming that the authenticated user has permission, Swarm responds with the new group entity:

{
  "group": {
    "Group": "my-group",
    "MaxLockTime": null,
    "MaxResults": null,
    "MaxScanRows": null,
    "Owners": ["username"],
    "PasswordTimeout": null,
    "Subgroups": [],
    "Timeout": null,
    "Users": [],
    "config": {
      "description": "This group is special to me.",
      "emailFlags": {
        "reviews": "1",
        "commits": "0"
      },
      "name": "My Group"
    }
  }
}

Change the settings of a group in Swarm. Only super users and group owners can perform this action.

HTTP/1.1 200 OK

{
  "group": {
    "Group": "test-group",
    "Users": [],
    "Owners": [],
    "Subgroups": [],
    "config": {
      "description": "New Group Description",
      "name": "TestGroup"
    }
  }
}

Important:

  - Only user with super privileges in the Helix Versioning Engine, or group
    owners, can edit groups.
  - This API version is only capable of modifying specific fields:
       Users, Owners, Subgroups, config
    An error can occur if other fields are specified in the edit request.

Here is how to update the name, description, and email flags of the group 'my-group':

curl -u "username:password" -X PATCH \
     -d "config[description]=This group is special to me." \
     -d "config[name]=My Group" \
     -d "config[emailFlags][commit]=1" \
     "https://myswarm.url/api/v2/groups/my-group"

Assuming that the authenticated user has permission, Swarm responds with the modified group entity:

{
  "group": {
    "Group": "my-group",
    "Users": [],
    "Owners": [],
    "Subgroups": [],
    "config": {
      "description": "This group is special to me.",
      "emailFlags": {
        "reviews": "1",
        "commits": "1"
      },
      "name": "My Group"
    }
  }
}

Delete a group. Only super users and group owners can perform this action.

HTTP/1.1 200 OK

{
  "id": "test-group"
}

Important: Only super users and group owners can delete groups.

curl -u "username:password" -X DELETE "https://myswarm.url/api/v2/groups/my-group"

Assuming that the authenticated user has permission, Swarm responds with the id of the deleted group:

{
  "id": "my-group"
}

Creates an entry in the Activity List. Note: admin-level privileges are required for this action.

HTTP/1.1 200 OK

{
  "activity": {
    "id": 123,
    "action": "ate",
    "behalfOf": null,
    "change": null,
    "depotFile": null,
    "details": [],
    "description": "",
    "followers": [],
    "link": "",
    "preposition": "for",
    "projects": [],
    "streams": [],
    "target": "the manual",
    "time": 1404776681,
    "topic": "",
    "type": "comment",
    "user": "A dingo"
  }
}

Creating an activity entry

To create a plain activity entry:

curl -u "username:password" -d "type=job" -d "user=jira" -d "action=punted" -d "target=review 123" \
     "https://myswarm.url/api/v2/activity"

JSON Response:

{
  "activity": {
    "id": 1375,
    "action": "punted",
    "behalfOf": null,
    "change": null,
    "depotFile": null,
    "description": "",
    "details": [],
    "followers": [],
    "link": "",
    "preposition": "for",
    "projects": [],
    "streams": [],
    "target": "review 123",
    "time": 1461607739,
    "topic": "",
    "type": "job",
    "user": "jira"
  }
}

Linking an activity entry to a review

Linking activity entries to reviews is useful. This involves providing "link", "stream", and "topic" fields in the activity data. The "link" field is used to make the "review 123" string in the activity entry clickable. The "stream" field is needed so that the activity entry can be attached to the review in the Swarm interface. The "topic" field is used to link the activity entry to the comment thread for that topic, in the event that a user wants to comment on the activity. To create a fully linked activity entry:

curl -u "username:password" -d "type=job" -d "user=jira" -d "action=punted" -d "target=review 123" \
     -d "streams[]=review-123" \
     -d "link=reviews/123" \
     -d "topic=reviews/123" \
     "https://myswarm.url/api/v2/activity"

Swarm responds with an activity entity:

{
  "activity": {
    "id": 1375,
    "action": "punted",
    "behalfOf": null,
    "change": null,
    "depotFile": null,
    "description": "",
    "details": [],
    "followers": [],
    "link": "reviews/123",
    "preposition": "for",
    "projects": [],
    "streams": ['review-123],
    "target": "review 123",
    "time": 1461607739,
    "topic": "reviews/123",
    "type": "job",
    "user": "jira"
  }
}

Retrieve the Activity List.

HTTP/1.1 200 OK

{
  "activity": [
    {
      "id": 123,
      "action": "committed",
      "behalfOf": null,
      "behalfOfExists": false,
      "change": 1,
      "date": "2016-01-15T12:12:12-08:00",
      "depotFile": null,
      "description": "test\n",
      "details": [],
      "followers": [],
      "link": ["change", {"change": 1}],
      "preposition": "into",
      "projectList": {"restricted": ["main"]},
      "projects": {"restricted": ["main"]},
      "streams": ["review-2", "user-foo", "personal-foo", "project-restricted"],
      "target": "change 1",
      "time": 1404776681,
      "topic": "changes/1",
      "type": "change",
      "url": "/changes/1",
      "user": "bruno",
      "userExists": true
    }
  ],
  "lastSeen": 1
}

Fetching review history

To get the latest activity entries on a review:

curl -u "username:password" "https://myswarm.url/api/v2/activity?stream=review-1234\
     &fields=id,date,description,type\
     &max=2"

You can tweak "max" and "fields" to fetch the data that works best for you. Swarm responds with an array of activity entities, and a "lastSeen" value that can be used for pagination:

{
  "activity": [
    {
      "id": 10,
      "date": "2016-04-15T16:10:32-07:00",
      "description": "This is a test comment.",
      "type": "comment"
    },
    {
      "id": 9,
      "date": "2016-03-31T13:48:15-07:00",
      "description": "Updating RELNOTE review",
      "type": "review"
    }
  ],
  "lastSeen": 9
}

Activity pagination

To get the second page of activity entries for a review (based on the previous example):

curl -u "username:password" "https://myswarm.url/api/v2/activity?stream=review-1234\
     &fields=id,date,description,type\
     &max=2\
     &lastSeen=9"

Swarm again responds with a list of activity entities and a "lastSeen" value:

{
  "activity": [
    {
      "id": 8,
      "date": "2016-03-30T12:12:12-07:00",
      "description": "This is the first test comment.",
      "type": "comment"
    },
    {
      "id": 7,
      "date": "2016-03-29T12:13:14-07:00",
      "description": "Updating RELNOTE review",
      "type": "review"
    }
  ],
  "lastSeen": 7
}