This chapter describes the REST-like API provided by Swarm, which can be used to automate common Swarm interactions or integrate with external systems.

Authentication

Swarm’s API requires an authenticated connection for all data-modifying endpoints. Authenticated connections are achieved using HTTP Basic Access Authentication.

For example:

$ curl -u "apiuser:password" https://myswarm.url/api/v6/projects

Swarm accepts a ticket from the Helix Versioning Engine (previous versions of Swarm required this ticket to be host-unlocked, this is no longer true since Swarm 2017.1). It may also be possible to use a password in place of the ticket.

To acquire a ticket, run the following command:

$ p4 -p myp4host:1666 -u apiuser login -p

If you make a request that requires authentication and you have not authenticated, the response is:

{
  "error": "Unauthorized"
}

Requests

Swarm’s API includes endpoints that provide, create, and update information within Swarm.

If you make a request against an endpoint that is not supported, the response is:

{
  "error": "Method Not Allowed"
}

GET information

Use HTTP <literal>GET</literal> requests to ask for information from the API.

For example, to get the list of reviews:

$ curl https://myswarm.url/api/v6/reviews

Certain API calls support a fields parameter that allows you to specify which fields to include in the response, enabling more compact data sets. The following endpoints support fields:

Fields can be expressed as a comma-separated list, or using array-notation. For example:

$ curl 'https://myswarm.url/api/v6/reviews?fields=id,description,participants'

Or:

$ curl 'https://myswarm.url/api/v6/reviews?fields[]=id,fields[]=description,fields[]=participants'

POST new information

Use HTTP <literal>POST</literal> requests to create information via the API.

For example, to create a review using form-encoded values:

$ curl -u "apiuser:password" -d"change=12345" https://myswarm.url/api/v6/reviews

The response should be similar to:

{
  "isValid": true,
  "id": 12206
}

To create a review using JSON:

$ curl -u "apiuser:password" -H "Content-type: application/json" \
  -d'{"change": 12345}' https://myswarm.url/api/v6/reviews

Update

Use HTTP <literal>PATCH</literal> requests to update information via the API.

If your HTTP client does not support PATCH requests, you can emulate this behavior by submitting an HTTP POST with a "?_method=PATCH" parameter.

Pagination

Most Swarm endpoints that provide data include the ability to paginate their results.

Each time data is requested, up to max results are included in the response, as is a value called lastSeen. lastSeen identifies the id of the last entry included in the results. If there are no further results, lastSeen is null.

To get the next set of results, include after set to the value of lastSeen in the API request. Entries up to and including the id specified by after are excluded from the response, and the next max entries are included.

See the Activity endpoint for example usage that demonstrates pagination.

Responses

Swarm’s API responses are JSON formatted.

API versions

The current Swarm API version is v4. Here is a list of historical API versions: