Helix Core is now P4 and Helix Swarm is now P4 Code Review. Learn more >>

Documentation | 2025.2

# P4 Code Review API basics

From P4 Code Review 2022.2, P4 Code Review no longer supports APIs older than v9.

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

## Authentication

P4 Code Review’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

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

To acquire a ticket, run the following command:

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

For a P4 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 P4 Server Administration Documentation.

If you use a ticket to authenticate against the P4 Code Review 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 P4 Code Review use only. The metadata returned is subject to change without notice and is not suitable for use in customer API calls.

P4 Code Review’s API includes endpoints that provide, create, and update information within P4 Code Review.

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 P4 Code Review 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

P4 Code Review’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 P4 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