The API has a set of HTTP methods to operate on Circuit resources for a specific team.

Currently, Circuit offers no programming SDKs for interacting with the Public API, but you can implement your own interface by calling the methods documented on this page.

This section describes how the Circuit API should be used, if you whish to see example implementations take a look at the API Usage Examples page.

The base API address for this version of the API to be used before every endpoint listed here is: https://api.getcircuit.com/public/v0.2b

Notice the https:// prefix, Circuit API will not accept plain HTTP requests.

To use Circuit Public API endpoints you will first need to generate an API key for authenticating with our servers.

To do this you need to go to your Circuit For Teams settings page > Integrations > API, and generate a new key there.

Once you have the API key you can use it in the Authorization header either using the Basic scheme, or as a Bearer token.

Basic Auth

Basic Authentication is the primary authentication scheme used by Circuit's API.

Basic authentication typically uses a base64 encoded username:password pair, but since we only require an API key we instead structure the payload as [yourApiKey]:[empty]. This value is then base64 encoded as usual.

Example with curl:

curl "https://api.getcircuit.com/public/v0.2b/plans" -u yourApiKey:

If you did everything correctly you should see a list of your team's plans in response to this request.

The -u flag adds a header to the request in the following format:

Authorization: Basic eW91ckFwaUtleToK

Note that curl automatically base64 encoded the data. Other clients will do the same e.g. if using Postman you would configure the request's Authorization option instead of adding a header directly.

Bearer Token

Alternatively you can pass the API key as a Bearer token without any special encoding. i.e. Authorization: Bearer [yourApiKey].

Example with curl:

curl "https://api.getcircuit.com/public/v0.2b/plans" -H "Authorization: Bearer yourApiKey"

Every response from the Circuit Public API will be as JSON Objects, and every request that has a body also needs to be in that type, and the header Content-type: application/json needs to present, so the server knows that the body you are sending is valid JSON. Circuit will reject requests without that header, so be sure to use it.

Every resource in the Circuit Public API has a unique ID. This ID is generated by Circuit and is unique for every resource per collection.

Every resource representation returned by the API will show the ID in the following format:

{
  "id": "collectionName/resourceId"
}

And if the resource is on a sub-collection, it will be in the following format:

{
  "id": "collectionName/resourceId/subcollectionName/subResourceId"
}

For example, a stop with ID stop1 under a plan with ID plan1 will have the following representation on its serialized ID field:

{
  "id": "plans/plan1/stops/stop1"
}

This means that if you wish to directly retrieve this stop by using a GET endpoint you can simply use this ID as follows:

curl "https://api.getcircuit.com/public/v0.2b/`serializedId`" -u yourApiKey:

For the example above this would be:

curl "https://api.getcircuit.com/public/v0.2b/plans/plan1/stops/stop1" -u yourApiKey:

When using list endpoints, you have the ability to combine various query options to locate the desired results. Some endpoints even offer specific filter options to aid in this search.

All the list endpoints employ pagination. This means that a single request might only return a part of the entire set of resources you're aiming to retrieve. To move through the subsequent pages, the Circuit API provides a nextPageToken field in the response of every list endpoint query.

It's crucial to understand that when a nextPageToken is returned, it indicates that more data is available. For every subsequent request, this token should be added as the pageToken query parameter. And, importantly, all the original query parameters used in the first request must also be included.

Here's a step-by-step example to elucidate this:

1. Suppose you initiate a request to list your plans:

curl "https://api.getcircuit.com/public/v0.2b/plans?filter.startsGte=2023-05-01" -u yourApiKey:

2. The Circuit API might return a response like:

{
  // other attributes
  "nextPageToken": "I53Jr5Eu2qK9omh0iA8q"
}

3. To retrieve the next page of data, use the returned nextPageToken as the pageToken query parameter, and ensure all initial query parameters remain the same:

curl "https://api.getcircuit.com/public/v0.2b/plans?filter.startsGte=2023-05-01&pageToken=I53Jr5Eu2qK9omh0iA8q" -u yourApiKey:

4. Repeat step 3 for all subsequent pages, updating the pageToken parameter with the latest nextPageToken value returned until nextPageToken is null in the response.

Circuit also accepts limiting the maximum number of results per page by using the maxPageSize query parameter, but notice that each individual endpoint has a maximum value you can set this to.

Update methods differ from the other methods in the API in the sense that missing values in the JSON representation will not act upon the representation of the resource.

Explaining this by example: Suppose you have a Plan with the ID plan1 in your plans' collection, and you wanted to merely update its title to My API Plan without changing other information, such as assigned drivers or the start date. To do this you would issue the following request:

curl -X PATCH http://localhost:5005/public/v0.2b/plans/plan1 -H 'Content-type: application/json' -d '{"title": "My API Plan"}' -u yourApiKey:

Notice how we don't pass any other information in the JSON, only the title. This ensures that the PATCH request will only operate on the provided parameters and keep the other parameters as-is.

It is important to also notice that when updating an array the whole array will be replaced, Circuit API does not support partial updates on arrays.

All the endpoints in the Circuit Public API are rate-limited, which means we will reject requests that come in too fast.

To know if your request was rate-limited, check if the response has the HTTP status code 429.

Each endpoint has a different rate limit, and Circuit can change this rate limit at any moment.

The rate limits are as follows:

• Rate Limits for Write Endpoints: All write endpoints have a limit of 5 requests per second, which includes Creation (POST), Update (PATCH), and Deletion (DELETE) operations for all models.
• Rate Limits for Read Endpoints: All read endpoints, including list endpoints, are limited to 10 requests per second.
• Rate Limits for Batch Import: The Batch Import endpoints for Stops and Unassigned Stops models are limited to 10 requests per minute. However, these endpoints can handle the import of up to 1,000 stops per minute. The Creation, Update, and Deletion endpoints for these models still maintain a rate limit of 5 requests per second.
• Rate Limits for Optimization Endpoints: The Plan optimization and re-optimization endpoints are limited to 3 requests per minute, due to the long running nature of these operations.

Circuit API will occasionally support bursts of requests, but they cannot be sustained and will be rejected if they last too long.

If Circuit rejects your request because it exceeds the rate limit, you must wait before retrying it. We suggest you use an exponential backoff approach for this.

We also recommend, besides the exponential backoff algorithm, that you add a random delay to each attempt to prevent a thundering herd problem.

If the client keeps retrying rate-limited requests while being rejected with a 429 at a high rate, Circuit will keep rejecting the requests until you turn down the request rate.

Circuit will also limit requests if it keeps receiving them at a high frequency at or close to the requests limit for an extended period, so while we support an occasional burst of requests, if this is sustained for a long period, we will rate-limit the client making them.

While we feel these rate-limits will work for the vast majority of use cases we understand every team is different. So please reach out to us and describe your use case if these limits are not enough for you, and we will evaluate increasing them for your team.

After this section you will find all the Circuit Public API endpoints available.

Every representation of resources that these endpoints create and return are documented in the Models page of the docs.

Endpoints to operate on Plans resources.

Endpoints to operate on Stop resources.

For any Plans created before 2023-04-01 the stop collections and all related operations will not be available.

For any operations here you will need a Plan ID beforehand. You can retrieve an existing Plan by listing your Plans or you can create a new one.

Endpoints to operate on Unassigned Stop resources.