API

The Cirro API follows the OpenAPI 3.0 specification. See our swagger-based UI for a detailed list of all endpoints.

The API can be accessed from the relative path api/ on your Cirro instance URL (i.e., https://app.cirro.bio/api/). All API endpoints use HTTPS and support JSON encoding.

We recommend using our SDK for programmatic access, unless you have specific requirements to interact directly with the API endpoints or need to use a different programming language not supported by the SDK. The SDK simplifies authentication, error handling, and other common tasks, allowing you to focus on your application's core functionality.

Usage

To interact with the API, you can use tools like curl. Here is an example request:

curl -H "Authorization: Bearer YOUR_JWT_TOKEN_HERE" https://app.cirro.bio/api/info

Authenticating

A JWT (JSON Web Token) is required to access the API. Follow these steps to obtain your token:

1. Log into the Cirro UI.
2. Retrieve the token from your browser's local storage or from the network tab in the developer tools. Other authentication methods are currently in development and will be available in future releases.

Programmatic Support

Since we publish an OpenAPI specification, you may use any one of the generators to generate API clients in your language of choice such as Java, C#, R, Go, etc., using the OpenAPI Generator.

We provide the following client libraries:

• TypeScript
• Python

Other notes

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of an API request. Common status codes are described below.

400 - Bad Request

The request was invalid or cannot be served. An accompanying error message will explain further.

Example:

{
    "statusCose": 400,
    "errorCode": "BadRequest",
    "errorDetail": "Name is required",
    "errors": [
        {
            "message": "Name is required"
        },
        {
            "message": "Description is required"
        }
    ]
}

401 - Unauthorized

You need to provide a valid JWT token in the Authorization header or the token has expired.

Example:

{
  "message": "Unauthorized"
}

403 - Forbidden

You do not have permission to access the resource.

404 - Not Found

The requested resource does not exist.

500 - Internal Server Error

We had a problem on our end. Please contact support if this is unexpected.

Compression

The Cirro API supports gzip compression. Please set the Accept-Encoding: gzip header to receive compressed responses.

Using compression reduces the size of the response body, which can decrease download time, lower data usage, and improve rendering speed. Compression is automatically applied to all responses larger than 500KB.

Rate Limiting

The API has a rate limit of 100 requests per minute per user. If you exceed the rate limit, you will receive a 429 - Too Many Requests response. Some endpoints have a lower rate limit.