Swarm 2017.2 Guide (August 2017)

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/v6/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/v6/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
}

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/v6/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/v5/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"
  }
}

List comments.

Successful Response:

HTTP/1.1 200 OK

{
  "topic": "",
  "comments": {
    "51": {
      "id": 51,
      "attachments": [],
      "body": "Short loin ground round sin reprehensible, venison west participle triple.",
      "context": [],
      "edited": null,
      "flags": [],
      "likes": [],
      "taskState": "comment",
      "time": 1461164347,
      "topic": "reviews/885",
      "updated": 1461164347,
      "user": "bruno"
    }
  },
  "lastSeen": 51
}

When no results are found, the comments array is empty:

HTTP/1.1 200 OK

{
  "topic": "jobs/job000011",
  "comments": [],
  "lastSeen": null
}

Listing comments

To list comments:

curl -u "username:password" "https://my-swarm-host/api/v6/comments\
?topic=reviews/911&max=2&fields=id,body,time,user"

Swarm responds with a list of the first two comments for review 911 and a lastSeen value for pagination:

{
  "topic": "reviews/911",
  "comments": {
    "35": {
      "id": 35,
      "body": "Excitation thunder cats intelligent man braid organic bitters.",
      "time": 1461164347,
      "user": "bruno"
    },
    "39": {
      "id": 39,
      "body": "Chamber tote bag butcher, shirk truffle mode shabby chic single-origin coffee.",
      "time": 1461164347,
      "user": "swarm_user"
    }
  },
  "lastSeen": 39
}

Paginating a comment listing

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

curl -u "username:password" "https://my-swarm-host/api/v6/comments\
?topic=reviews/911&max=2&fields=id,body,time,user&after=39"

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

{
  "topic": "reviews/911",
  "comments": {
    "260": {
      "id": 260,
      "body": "Reprehensible do lore flank ham hock.",
      "time": 1461164349,
      "user": "bruno"
    },
    "324": {
      "id": 324,
      "body": "Sinter lo-fi temporary, nihilist tote bag mustache swag consequence interest flexible.",
      "time": 1461164349,
      "user": "bruno"
    }
  },
  "lastSeen": 324
}

Add a comment to a topic (such as a review or a job)

HTTP/1.1 200 OK

{
  "comment": {
    "id": 42,
    "attachments": [],
    "body": "Best. Comment. EVER!",
    "context": [],
    "edited": null,
    "flags": [],
    "likes": [],
    "taskState": "comment",
    "time": 123456789,
    "topic": "reviews/2",
    "updated": 123456790,
    "user": "bruno"
  }
}

Create a comment on a review

To create a comment on a review:

curl -u "username:password" \
     -d "topic=reviews/2" \
     -d "body=This is my comment. It is an excellent comment. It contains a beginning, a middle, and an end." \
     "https://my-swarm-host/api/v6/comments"

JSON Response:

{
  "comment": {
    "id": 42,
    "attachments": [],
    "body": "This is my comment. It is an excellent comment. It contains a beginning, a middle, and an end.",
    "context": [],
    "edited": null,
    "flags": [],
    "likes": [],
    "taskState": "comment",
    "time": 123456789,
    "topic": "reviews/2",
    "updated": 123456790,
    "user": "username"
  }
}

Open a task on a review

To create a comment on a review, and flag it as an open task:

curl -u "username:password" \
     -d "topic=reviews/2" \
     -d "taskState=open" \
     -d "body=If you could go ahead and attach a cover page to your TPS report, that would be great." \
     "https://my-swarm-host/api/v6/comments"

JSON Response:

{
  "comment": {
    "id": 43,
    "attachments": [],
    "body": "If you could go ahead and attach a cover page to your TPS report, that would be great.",
    "context": [],
    "edited": null,
    "flags": [],
    "likes": [],
    "taskState": "open",
    "time": 123456789,
    "topic": "reviews/2",
    "updated": 123456790,
    "user": "username"
  }
}

Edit a comment

HTTP/1.1 200 OK

{
  "comment": {
    "id": 1,
    "attachments": [],
    "body": "Best. Comment. EVER!",
    "context": [],
    "edited": 123466790,
    "flags": [],
    "likes": [],
    "taskState": "comment",
    "time": 123456789,
    "topic": "reviews/42",
    "updated": 123456790,
    "user": "bruno"
  }
}

Edit and archive a comment on a review

To edit and archive a comment on a review:

curl -u "username:password" \
     -X PATCH \
     -d "flags[]=closed" \
     -d "body=This comment wasn't as excellent as I may have lead you to believe. A thousand apologies." \
     "https://my-swarm-host/api/v6/comments/42"

JSON Response:

{
  "comment": {
    "id": 42,
    "attachments": [],
    "body": "This comment wasn't as excellent as I may have lead you to believe. A thousand apologies.",
    "context": [],
    "edited": 123466790,
    "flags": ["closed"],
    "likes": [],
    "taskState": "comment",
    "time": 123456789,
    "topic": "reviews/2",
    "updated": 123456790,
    "user": "username"
  }
}

Flag a task as addressed on a review

To flag an open task as addressed on a review:

curl -u "username:password" \
     -X PATCH \
     -d "taskState=addressed" \
     "https://my-swarm-host/api/v6/comments/43"

JSON Response:

{
  "comment": {
    "id": 43,
    "attachments": [],
    "body": "If you could go ahead and attach a cover page to your TPS report, that would be great.",
    "context": [],
    "edited": 123466790,
    "flags": ["closed"],
    "likes": [],
    "taskState": "comment",
    "time": 123456789,
    "topic": "reviews/2",
    "updated": 123456790,
    "user": "username"
  }
}

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": ["bruno"],
      "config": {
        "description": "Our testing group",
        "emailFlags": [],
        "name": "Test Group"
      }
    }
  ]
}

Listing groups

To list groups:

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

Swarm responds with a list of groups:

{
  "groups": [
    {
      "Group": "test-group",
      "Owners": [],
      "Users": ["bruno"],
      "config": {
        "description": "Our testing group",
        "emailFlags": {
          "reviews": "1",
          "commits": "0"
        },
        "name": "Test Group"
      }
    },
    {
      "Group": "test-group2",
      "Owners": [],
      "Users": ["bruno"],
      "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/v6/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": ["bruno"],
    "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/v6/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": ["bruno"],
    "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/v6/groups/my-group?fields=Group,Owners,Users,config"

Swarm responds with the group entity:

{
  "group": {
    "Group": "test-group",
    "Owners": [],
    "Users": ["bruno"],
    "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"
    }
  }
}

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/v6/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"
    }
  }
}

Here is how to update the name, description, and emailFlags configuration 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][commits]=1" \
     "https://myswarm.url/api/v6/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"
}

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

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

{
  "id": "my-group"
}

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 a list of projects in Swarm that are visible to the current user. Administrators will see all projects, including private ones.

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": [],
      "private": false,
      "subgroups": []
    }
  ]
}

To list all projects:

curl -u "username:password" "https://my-swarm-host/api/v6/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 administrators 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": [],
    "private": false,
    "subgroups": []
  }
}

To fetch an individual project:

curl -u "username:password" \
     "https://my-swarm-host/api/v6/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 administrators 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": [],
    "private": false,
    "subgroups": [],
    "tests": {"url": "", "enabled": false}
  }
}

Creating a new project

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/v6/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": [],
    "private": false,
    "subgroups": [],
    "tests": {"url": "", "enabled": false}
  }
}

Creating a private project with branches

Specifying a branch requires using array notation and providing at least two fields (name and paths) for each branch you wish to create. Creating more than one branch involves incrementing the branches[0] specifier for each branch - an example of this accompanies the PATCH endpoint documentation.

Projects are public by default. Marking a project as Private requires using {private: true} in JSON, and using -d "private=1" in regular form-encoded requests.

curl -u "username:password" \
     -d "name=TestProject 4" \
     -d "private=1" \
     -d "members[]=bob" \
     -d "branches[0][name]=Branch One" \
     -d "branches[0][paths][]=//depot/main/TestProject/..." \
     "https://my-swarm-host/api/v6/projects"

Swarm responds with the new project entity:

{
  "project": {
    "id": "testproject-4",
    "branches": [
      {
        "paths": [
          "//depot/main/TestProject/..."
        ],
        "name": "Branch One",
        "id": "branch-one",
        "moderators": []
      }
    ],
    "deleted": false,
    "deploy": {"url": "", "enabled": false},
    "description": null,
    "emailFlags": [],
    "jobview": null,
    "members": ["bob"],
    "name": "TestProject 4",
    "owners": [],
    "private": true,
    "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": [],
    "private": false,
    "subgroups": [],
    "tests": {"url": "", "enabled": false}
  }
}

Editing a project

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/v6/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": [],
    "private": false,
    "subgroups": [],
    "tests": {"url": "", "enabled": false}
  }
}

Editing a project to add a moderated branch and make the project public

Specifying a branch requires using array notation and providing at least two fields (name and paths) for each branch you wish to create. Creating more than one branch involves incrementing the branches[0] specifier for each branch.

Marking a private project as Public requires using {private: false} in JSON, or using -d "private=0" in regular form-encoded requests.

curl -u "username:password" \
     -X PATCH \
     -d "private=0" \
     -d "branches[0][name]=Branch One" \
     -d "branches[0][paths][]=//depot/main/TestProject/..." \
     -d "branches[1][name]=Branch Two" \
     -d "branches[1][paths][]=//depot/main/SecondBranch/..." \
     -d "branches[1][moderators][]=bob" \
     "https://my-swarm-host/api/v6/projects/testproject-4"

Swarm responds with the new project entity:

{
  "project": {
    "id": "testproject-4",
    "branches": [
      {
        "paths": [
          "//depot/main/TestProject/..."
        ],
        "name": "Branch One",
        "id": "branch-one",
        "moderators": []
      },
      {
        "paths": [
          "//depot/main/SecondBranch/..."
        ],
        "name": "Branch Two",
        "id": "branch-two",
        "moderators": ["bob"]
      },
    ],
    "deleted": false,
    "deploy": {"url": "", "enabled": false},
    "description": null,
    "emailFlags": [],
    "jobview": null,
    "members": ["bob"],
    "name": "TestProject 4",
    "owners": [],
    "private": false,
    "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, administrators, 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/v6/projects/testproject3"

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

{
  "id": "testproject3"
}

Gets reviews for the action dashboard for the authenticated user

HTTP/1.1 200 OK

{
  "lastSeen": 120,
  "reviews": [
    {
      "id": 7,
      "author": "swarm_admin",
      "changes": [6],
      "comments": [0,0],
      "commits": [6],
      "commitStatus": [],
      "created": 1485793976,
      "deployDetails": [],
      "deployStatus": null,
      "description": "test\n",
      "groups": ["swarm-project-test"],
      "participants": {"swarm_admin":[]},
      "pending": false,
      "projects": {"test":["test"]},
      "roles": ["moderator|reviewer|required_reviewer|author"],
      "state": "needsReview",
      "stateLabel": "Needs Review",
      "testDetails": [],
      "testStatus": null,
      "type": "default",
      "updated": 1485958875,
      "updateDate": "2017-02-01T06:21:15-08:00"
    }
  ],
  "totalCount": null
}

To list reviews:

curl -u "username:password" "http://my-swarm-host/api/v6/dashboards/action"

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

{
  "lastSeen": 120,
  "reviews": [
    {
      "id": 7,
      "author": "swarm_admin",
      "changes": [6],
      "comments": [0,0],
      "commits": [6],
      "commitStatus": [],
      "created": 1485793976,
      "deployDetails": [],
      "deployStatus": null,
      "description": "test\n",
      "groups": ["swarm-project-test"],
      "participants": {"swarm_admin":[]},
      "pending": false,
      "projects": {"test":["test"]},
      "roles": ["moderator|reviewer|required_reviewer|author"],
      "state": "needsReview",
      "stateLabel": "Needs Review",
      "testDetails": [],
      "testStatus": null,
      "type": "default",
      "updated": 1485958875,
      "updateDate": "2017-02-01T06:21:15-08:00"
    }
  ],
  "totalCount": null
}

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 is 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/v6/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 typo.\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/v6/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/v6/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
}

Finding inactive reviews (by checking the last updated date)

curl -u "username:password" "https://my-swarm-host/api/v6/reviews\
?max=2&fields=id,changes,description,author,state&notUpdatedSince=2017-01-01"

Swarm responds with a list of reviews that have not been updated since the notUpdatedSince date:

{
  "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
}

Finding reviews I have voted up

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

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
}

Finding reviews I have commented on (current authenticated user)

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

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
}

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/v6/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/v6/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": []
  }
}

Archiving reviews not updated since the date (v6+)

HTTP/1.1 200 OK

{
  "archivedReviews": [
    {
      "id": 836,
      "author": "swarm",
      "changes": [789],
      "commits": [],
      "commitStatus": [],
      "created": 1461164339,
      "deployDetails": [],
      "deployStatus": null,
      "description": "Review description\n",
      "groups": [],
      "participants": {
        "swarm": []
      },
      "pending": false,
      "projects": [],
      "state": "archived",
      "stateLabel": "Archived",
      "testDetails": [],
      "testStatus": null,
      "type": "default",
      "updated": 1478191607
    }
  ],
  "failedReviews": []
}

To archive reviews not updated since 2016/06/30 inclusive:

curl -u "username:password" -d "notUpdatedSince=2016-06-30" \
     "https://my-swarm-host/api/v6/reviews/archive/"

Swarm responds with the list of archived reviews and failed reviews if there are any:

{
  "archivedReviews":[
    {
      "id": 911,
      "author": "swarm",
      "changes": [601],
      "commits": [],
      "commitStatus": [],
      "created": 1461164344,
      "deployDetails": [],
      "deployStatus": null,
      "description": "Touch up references on html pages.\n",
      "groups": [],
      "participants": {
        "swarm":[]
      },
      "pending": false,
      "projects": [],
      "state": "archived",
      "stateLabel": "Archived",
      "testDetails": [],
      "testStatus": null,
      "type": "default",
      "updated": 1478191605
    },
    {
      "id": 908,
      "author": "earl",
      "changes": [605],
      "commits": [],
      "commitStatus": [],
      "created": 1461947794,
      "deployDetails": [],
      "deployStatus": null,
      "description": "Remove (attempted) installation of now deleted man pages.\n",
      "groups": [],
      "participants": {
        "swarm": []
      },
      "pending": false,
      "projects": [],
      "state": "archived",
      "stateLabel": "Archived",
      "testDetails": [],
      "testStatus": null,
      "type": "default",
      "updated": 1478191605
    }
  ],
  "failedReviews":[
    {
    }
  ]
}

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

{
  "archivedReviews": [],
  "failedReviews": []
}

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/v6/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,
      }
    ]
  }
}

Clean up a review for the given id.

HTTP/1.1 200 OK

{
  "complete": [
    {
      "1": ["2"]
    }
  ],
  "incomplete": []
}

Cleanup review number 1, reopening any files into the default changelist.

curl -u "username:password" -d "reopen=true" \
     "https://my-swarm-host/api/v6/reviews/1/cleanup"

Swarm responds with the review and the changelists cleaned. Depending on the completion they will be either detailed in 'complete' or 'incomplete'. Incomplete changelists will have messages indicating why it was not possible to complete:

  {
    "complete": [
      {
        "1": ["2"]
      }
    ],
    "incomplete": []
  }

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" -X PATCH -d "state=approved" -d "commit=1" \
     "https://my-swarm-host/api/v6/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"
    }
}

Update the description field of a review.

Successful Response:

HTTP/1.1 200 OK

{
  "review": {
      "id": 12206,
      "author": "swarm",
      "changes": [12205],
      "comments": 0,
      "commits": [],
      "commitStatus": [],
      "created": 1402507043,
      "deployDetails": [],
      "deployStatus": null,
      "description": "Updated Review Description\n",
      "participants": {
        "swarm": []
      },
      "pending": true,
      "projects": [],
      "state": "needsReview",
      "stateLabel": "Needs Review",
      "testDetails": [],
      "testStatus": null,
      "type": "default",
      "updated": 1402518492
  },
  "transitions": {
      "needsRevision": "Needs Revision",
      "approved": "Approve",
      "rejected": "Reject",
      "archived": "Archive"
  },
  "canEditAuthor": true
}

When no results are found, the reviews array is empty:

HTTP/1.1 200 OK

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