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/v2/projects

Swarm accepts a ticket from the Helix Versioning Engine, which is either host-unlocked or locked to the Swarm host. 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

To acquire a host-unlocked ticket, run the following command:

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

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 GET requests to ask for information from the API.

For example, to get the list of reviews:

$ curl https://myswarm.url/api/v2/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/v2/reviews?fields=id,description,participants'

Or:

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

POST new information

Use HTTP POST 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/v2/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/v2/reviews

Update

Use HTTP PATCH 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.

Responses

Swarm's API responses are JSON formatted.

API versions

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