Using the API

Sophos Factory provides a full-featured RESTful API. The API can be used by developers and advanced users to extend the functionality of Sophos Factory. Nearly every action that can be performed from the application can also be done directly using the API.

The base URL for the API is:

https://api.<region>.factory.sophos.com/v1

Note that <region> is the name of the region where the API is available. For example, the base URL to access the API in US West is:

https://api.us-west-2.factory.sophos.com/v1

The base URL for the API in the default region is:

https://api.us-west-2.factory.sophos.com/v1 

Reference documentation for the API can be found here:

API Browser: https://api.us-west-2.factory.sophos.com/v1

OpenAPI Specification: https://api.us-west-2.factory.sophos.com/v1/spec

Content Type

The request and response format for API endpoints is application/json.

The Content-Type of all requests and responses should be application/json. If you omit this header from your request, the server will respond with a 400 error code.

HTTP Methods

The following HTTP methods may be used:

• GET - Used in endpoints that get single and list multiple resources
• POST - Used in endpoints that create and update resources
• DELETE - Used in endpoints that delete resources

API Authentication

Every request to the API must be authenticated using a Bearer token.

Tokens can be generated from Sophos Factory by navigating to your Account Settings from the top right dropdown menu, then clicking API Tokens on the left nav bar.

Provide the token in the Authorization header of the request. For example, if your token is mF_9.B5f-4.1JqM, an example HTTP request would look like this:

GET https://api.us-west-2.factory.sophos.com/v1/path/to/endpoint HTTP/1.1
Content-Type: application/json
Authorization: Bearer mF_9.B5f-4.1JqM

{"ham": "eggs"}

The same request using cURL:

curl -H 'Content-Type: application/json' \
-H 'Authorization: Bearer mF_9.B5f-4.1JqM' \
-d '{"ham": "eggs"}' \
https://api.us-west-2.factory.sophos.com/v1/path/to/endpoint

See here for more information about HTTP authentication schemes.

Update Endpoints

Endpoints that update existing resources allow partial updates. For example, if you would like to update the name of a pipeline without modifying any other fields, send the following request:

POST https://api.us-west-2.factory.sophos.com/v1/projects/123/pipelines/123 HTTP/1.1

{
  "name": "New Name"
}

Update endpoints also allow you to unset optional fields by providing either an empty string "" or null in the request body. For example, if you would like to unset the description of a pipeline without modifying any other fields, send the following request:

POST https://api.us-west-2.factory.sophos.com/v1/projects/123/pipelines/123 HTTP/1.1

{
  "description": null
}

Returning Extra Fields

Some API endpoints support a fields query parameter, which can be used to request additional data. Often this parameter tells the server that we want to aggregate associated resources into a single response.

For example, when fetching a run, we can also ask for data about the associated pipeline:

GET https://api.us-west-2.factory.sophos.com/v1/projects/123/runs/123?fields=pipeline HTTP/1.1

Paginated Endpoints

Most list endpoints are paginated, which means they will only return a subset of all documents for a single request. In order to fetch more documents, you can provide the following pagination query parameters:

• limit: Specifies the maximum number of documents to return. This is equivalent to a page size.
• offset: Specifies the starting document to return. This equivalent to a page number, multiplied by the page size.

For example, to retrieve the third page of pipelines given a page size of ten, send the following request:

GET https://api.us-west-2.factory.sophos.com/v1/projects/123/pipelines?limit=10&offset=20 HTTP/1.1

Error Responses

When an error occurs, the response body will contain additional information about the error. The basic shape of these error responses looks like the following:

{
  "status": 400,
  "errors": [{
    "code": "SomeErrorCode",
    "message": "Additional information about the error."
  }]
}

The status field is the same as the HTTP response status. The errors array contains additional information about the specific error(s) that occurred, and includes a machine-readable code (errors[].code) and a human-readable description (errors[].message). Some error responses may contain additional error fields, such as the path to an invalid field value.