Using the API

Detailed information about using the Refactr API. The API can be used by advanced users to extend the functionality of the application.

The Refactr Platform provides a full-featured RESTful API. 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.refactr.it/v1

Reference documentation for the API can be found here:

API Browser: https://api.refactr.it/v1

OpenAPI Specification: https://api.refactr.it/v1/spec

Accept and Content-Type

The request and response format for API endpoints is application/json. It’s recommended to always provide the Accept header in all requests, although it is not required.

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.

API Authentication

Every request to the API must be authenticated using a Bearer token. Tokens can be generated from the application by navigating to Account Settings from the top-right dropdown, 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 as follows:

GET https://api.refactr.it/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.refactr.it/v1/path/to/endpoint

See here for more information about HTTP authentication schemes.

Returning extra fields

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

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

GET https://api.refactr.it/v1/projects/123/runs/123?fields=pipeline

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