Skip to main content

CEEMS API (1.0)

Download OpenAPI specification:Download

OpenAPI specification (OAS) for the CEEMS REST API.

See the Interactive Docs to try CEEMS API methods without writing code, and get the complete schema of resources exposed by the API.

If basic auth is enabled, all the endpoints require authentication.

All the endpoints, except health, swagger, debug and demo, must send a user-agent header.

Timestamps must be specified in milliseconds, unless otherwise specified.

clusters

List clusters

This endpoint will list all the cluster IDs in the CEEMS DB. The current user is always identified by the header X-Grafana-User in the request.

This will list all the cluster IDs in the DB. This is primarily used to verify the CEEMS load balancer's backend IDs that should match with cluster IDs.

Authorizations:
BasicAuth
header Parameters
X-Grafana-User
required
string

Current user name

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "error": "string",
  • "errorType": "",
  • "status": "string",
  • "warnings": [
    ]
}

demo

Demo Units/Usage endpoints

This endpoint returns sample response for units and usage models. This endpoint do not require the setting of X-Grafana-User header as it only returns mock data for each request. This can be used to introspect the response models for different resources.

The endpoint requires a path parameter resource which takes either:

  • units which returns a mock units response
  • usage which returns a mock usage response.

The mock data is generated randomly for each request and there is no guarantee that the data has logical sense.

path Parameters
resource
required
string
Enum: "units" "usage"

Whether to return mock units or usage data

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "error": "string",
  • "errorType": "",
  • "status": "string",
  • "warnings": [
    ]
}

health

Health status

This endpoint returns the health status of the server.

A healthy server returns 200 response code and any other responses should be treated as unhealthy server.

Responses

projects

Show project details

This endpoint will show details of the queried project of current user. The current user is always identified by the header X-Grafana-User in the request.

The details include list of users in that project. If current user attempts to query a project that they are not part of, empty response will be returned

Authorizations:
BasicAuth
query Parameters
project
Array of strings

Project

cluster_id
Array of strings

Cluster ID

header Parameters
X-Grafana-User
required
string

Current user name

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "error": "string",
  • "errorType": "",
  • "status": "string",
  • "warnings": [
    ]
}

Admin ednpoint to fetch project details

This endpoint will show details of the queried project. The current user is always identified by the header X-Grafana-User in the request.

The user who is making the request must be in the list of admin users configured for the server.

The details include list of users in that project. If current user attempts to query a project that they are not part of, empty response will be returned

Authorizations:
BasicAuth
query Parameters
project
Array of strings

Project

cluster_id
Array of strings

Cluster ID

header Parameters
X-Grafana-User
required
string

Current user name

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "error": "string",
  • "errorType": "",
  • "status": "string",
  • "warnings": [
    ]
}

units

User endpoint for fetching compute units

This user endpoint will fetch compute units of the current user. The current user is always identified by the header X-Grafana-User in the request.

If multiple query parameters are passed, for instance, ?uuid=<uuid>&project=<project>, the intersection of query parameters are used to fetch compute units rather than the union. That means if the compute unit's uuid does not belong to the queried project, null response will be returned.

In order to return the running compute units as well, use the query parameter running.

If to query parameter is not provided, current time will be used. If from query parameter is not used, a default query window of 24 hours will be used. It means if to is provided, from will be calculated as to - 24hrs.

To limit the number of fields in the response, use field query parameter. By default, all fields will be included in the response if they are non-empty.

Authorizations:
BasicAuth
query Parameters
cluster_id
Array of strings

Cluster ID

uuid
Array of strings

Unit UUID

project
Array of strings

Project

running
boolean

Whether to fetch running units

from
string

From timestamp

to
string

To timestamp

field
Array of strings

Fields to return in response

header Parameters
X-Grafana-User
required
string

Current user name

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "error": "string",
  • "errorType": "",
  • "status": "string",
  • "warnings": [
    ]
}

Admin endpoint for fetching compute units.

This admin endpoint will fetch compute units of any user, compute unit and/or project. The current user is always identified by the header X-Grafana-User in the request.

The user who is making the request must be in the list of admin users configured for the server.

If multiple query parameters are passed, for instance, ?uuid=<uuid>&user=<user>, the intersection of query parameters are used to fetch compute units rather than the union. That means if the compute unit's uuid does not belong to the queried user, null response will be returned.

In order to return the running compute units as well, use the query parameter running.

If to query parameter is not provided, current time will be used. If from query parameter is not used, a default query window of 24 hours will be used. It means if to is provided, from will be calculated as to - 24hrs.

To limit the number of fields in the response, use field query parameter. By default, all fields will be included in the response if they are non-empty.

Authorizations:
BasicAuth
query Parameters
cluster_id
Array of strings

Cluster ID

uuid
Array of strings

Unit UUID

project
Array of strings

Project

user
Array of strings

User name

running
boolean

Whether to fetch running units

from
string

From timestamp

to
string

To timestamp

field
Array of strings

Fields to return in response

header Parameters
X-Grafana-User
required
string

Current user name

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "error": "string",
  • "errorType": "",
  • "status": "string",
  • "warnings": [
    ]
}

Verify unit ownership

This endpoint will check if the current user is the owner of the queried UUIDs. The current user is always identified by the header X-Grafana-User in the request.

A response of 200 means that the current user is the owner of the queried UUIDs. Any other response code should be treated as the current user not being the owner of the queried units.

The ownership check passes if any of the following conditions are true:

  • If the current user is the direct owner of the compute unit.
  • If the current user belongs to the same account/project/namespace as the compute unit. This means the users belonging to the same project can access each others compute units.

The above checks must pass for all the queried units. If the check does not pass for at least one queried unit, a response 403 will be returned.

Any 500 response codes should be treated as failed check as well.

Authorizations:
BasicAuth
query Parameters
uuid
Array of strings

Unit UUID

header Parameters
X-Grafana-User
required
string

Current user name

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "error": "string",
  • "errorType": "",
  • "status": "string",
  • "warnings": [
    ]
}

usage

Usage statistics

This endpoint will return the usage statistics current user. The current user is always identified by the header X-Grafana-User in the request.

A path parameter mode is required to return the kind of usage statistics. Currently, two modes of statistics are supported:

  • current: In this mode the usage between two time periods is returned based on from and to query parameters.
  • global: In this mode the total usage statistics are returned. For instance, if the retention period of the DB is set to 2 years, usage statistics of last 2 years will be returned.

The statistics can be limited to certain projects by passing project query, parameter.

If to query parameter is not provided, current time will be used. If from query parameter is not used, a default query window of 24 hours will be used. It means if to is provided, from will be calculated as to - 24hrs.

To limit the number of fields in the response, use field query parameter. By default, all fields will be included in the response if they are non-empty.

Authorizations:
BasicAuth
path Parameters
mode
required
string
Enum: "current" "global"

Whether to get usage stats within a period or global

query Parameters
cluster_id
Array of strings

cluster ID

project
Array of strings

Project

from
string

From timestamp

to
string

To timestamp

field
Array of strings

Fields to return in response

header Parameters
X-Grafana-User
required
string

Current user name

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "error": "string",
  • "errorType": "",
  • "status": "string",
  • "warnings": [
    ]
}

Admin Usage statistics

This admin endpoint will return the usage statistics of queried user. The current user is always identified by the header X-Grafana-User in the request.

The user who is making the request must be in the list of admin users configured for the server.

A path parameter mode is required to return the kind of usage statistics. Currently, two modes of statistics are supported:

  • current: In this mode the usage between two time periods is returned based on from and to query parameters.
  • global: In this mode the total usage statistics are returned. For instance, if the retention period of the DB is set to 2 years, usage statistics of last 2 years will be returned.

The statistics can be limited to certain projects by passing project query, parameter.

If to query parameter is not provided, current time will be used. If from query parameter is not used, a default query window of 24 hours will be used. It means if to is provided, from will be calculated as to - 24hrs.

To limit the number of fields in the response, use field query parameter. By default, all fields will be included in the response if they are non-empty.

Authorizations:
BasicAuth
path Parameters
mode
required
string
Enum: "current" "global"

Whether to get usage stats within a period or global

query Parameters
cluster_id
Array of strings

cluster ID

project
Array of strings

Project

from
string

From timestamp

to
string

To timestamp

field
Array of strings

Fields to return in response

header Parameters
X-Grafana-User
required
string

Current user name

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "error": "string",
  • "errorType": "",
  • "status": "string",
  • "warnings": [
    ]
}

users

Show user details

This endpoint will show details of the current user. The current user is always identified by the header X-Grafana-User in the request.

The details include list of projects that user is currently a part of.

Authorizations:
BasicAuth
query Parameters
cluster_id
Array of strings

Cluster ID

header Parameters
X-Grafana-User
required
string

Current user name

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "error": "string",
  • "errorType": "",
  • "status": "string",
  • "warnings": [
    ]
}

Admin endpoint for fetching user details of _any_ user.

This endpoint will show details of the queried user(s). The current user is always identified by the header X-Grafana-User in the request.

The user who is making the request must be in the list of admin users configured for the server.

The details include list of projects that user is currently a part of.

Authorizations:
BasicAuth
query Parameters
user
Array of strings

User name

cluster_id
Array of strings

Cluster ID

header Parameters
X-Grafana-User
required
string

Current user name

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "error": "string",
  • "errorType": "",
  • "status": "string",
  • "warnings": [
    ]
}