Documentation | 2025.1

# Swarm API basics

From Swarm 2022.2, Swarm no longer supports APIs older than v9.

This section describes the API endpoints that are commonly used when constructing an API call to Swarm.

## Authentication

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

API endpoints require authentication unless require_login is set to false.

For example:

curl -u "apiuser:ticket" https://myswarm.url/api/v9/projects

Swarm accepts a ticket from the Helix Core Server (previous versions of Swarm required this ticket to be host-unlocked, this is no longer true since Swarm 2017.1). It might also be possible to use a password in place of the ticket if your Helix Core Server allows it.

To acquire a ticket, run the following command:

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

For a Helix Core Server that has been configured for security level 3, passwords are not accepted. For more information on security levels, see on Server security levels in the Helix Core Server Administration Documentation.

If you use a ticket to authenticate against the Swarm API and the ticket expires, you need to acquire a new ticket to continue using the API.

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

    HTTP/1.1 200 OK

    {
      "error": "Unauthorized"
    }

## Requests

Some API endpoints have undocumented metadata parameters, these are for internal Swarm use only. The metadata returned is subject to change without notice and is not suitable for use in customer API calls.

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

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

    HTTP/1.1 200 OK

    {
      "error": "Method Not Allowed"
    }

### GET information

GET requests require authentication unless require_login is set to false.

Use HTTP GET requests to ask for information from the API.

For example, to get the list of reviews using the v11 API:

curl -u "username:ticket" "https://my-swarm-host/api/v11/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.

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

curl -u "username:ticket" "https://my-swarm-host/api/v11/projects/jam?fields=id,description,members"

The following endpoints support fields:

#### API (v9)

- /api/v9/activity

- /api/v9/comments

- /api/v9/groups

- /api/v9/groups/{id}

- /api/v9/projects

- /api/v9/reviews

- /api/v9/reviews/{id}

- /api/v9/users

- /api/v9/workflows

- /api/v9/workflows/{id}

#### API (v11)

- /api/v11/files/{id}

- /api/v11/projects

- /api/v11/projects/{id}

- /api/v11/reviews

- /api/v11/reviews/{id}

- /api/v11/reviews/{id}/files

- /api/v11/reviews/{id}/testruns

- /api/v11/search

- /api/v11/specs/{spec}/fields

- /api/v11/testdefinitions

- /api/v11/workflows

- /api/v11/workflows/{id}

### 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:ticket" -X POST -d"change=12345" https://myswarm.url/api/v9/reviews

The response should be similar to:

    HTTP/1.1 200 OK

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

To create a review using JSON:

curl -u "apiuser:ticket" -H "Content-type: application/json" -X POST -d'{"change": 12345}' https://myswarm.url/api/v9/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.

## 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.

- Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix Core Server, can see the project, its activity streams, and ongoing reviews. API responses honor these private project restrictions. For more information about private project restrictions, see Private projects.
- Permissions: if a public review contains files that the user does not have permission to view, the review is returned but the restricted files are not displayed.

Your search for returned results