FlexStack API

FlexStack's API is a RESTful service that allows you to interact with the FlexStack platform. Endpoints are resource-oriented, accept JSON payloads, and return JSON responses. We use HTTP response codes and verbs (GET, POST, etc.) that are consistent with standards.

Authentication

Almost all API methods require authentication. To authenticate your requests, we use prefixed API keys like flex_018bcaea5d6a7678a1d0c9f70e72cd0el.... API keys can be created in your organization dashboard if you have Admin permissions in your org. To authenticate a request, add an API key to the X-API-Key header of your request.

curl https://api.flexstack.com/v1/orgs \
  -H "x-api-key: flex_018bcaea5d6a7678a1d0c9f70e72cd0el4csZ5Etx8BwFZ8QJ9YEwl"

Request lifecycle

Requests are made via GET, POST, PUT, PATCH, and DELETE requests to an API endpoint. The request body will be a JSON object for POST, PUT, and PATCH methods and a query string ?foo=bar for GET and DELETE requests.

curl -X POST https://api.flexstack.com/v1/orgs \
  -H "x-api-key: flex_018bcaea5d6a7678a1d0c9f70e72cd0el4csZ5Etx8BwFZ8QJ9YEwl" \
  -H "Content-Type: application/json" \
  -d '{"name": "Pied Piper, Inc."}'

Successful response body

Successful responses return a 200 OK or 201 Created status code.

{
    "key": "value"
}

Failed response body

Failed responses will always have a code and message key. Sometimes they will also contain a cause.

{
  "code": "not_found",
  "message": "This resource doesn't exist"
}

Paginated requests

Requests that return many items will be paginated. You can specify the number of items returned by using the limit query parameter. Each page will return a next_page cursor if there is another page of results. You can add the value of this property to the after query parameter to get the next page of results.

curl -X GET https://api.flexstack.com/v1/orgs?limit=10&after=csZ5Etx8BwFZ8QJ9YEwl \
  -H "x-api-key: flex_018bcaea5d6a7678a1d0c9f70e72cd0el4csZ5Etx8BwFZ8QJ9YEwl"

Successful paginated response body

Results with pages always have data, has_more, and next_page keys. data contains the current page of results. has_more is true if there are more pages. next_page is a cursor for the next page of results, for example /v1/orgs?after=next_page.

{
  "data": [{"key": "value"}],
  "has_more": true,
  "next_page": "c3VwIGJyYWg="
}

Errors

The FlexStack API uses error codes to indicate the type of error that occurred. The message key of the error object will contain a human-readable description of the error.

Error codes

Code	Response status	Description
not_found	404	The requested resource was not found.
forbidden	403	The requester does not have permission to perform the requested action.
unauthenticated	401	This request requires authentication and the requester is unauthenticated. For example, a request was made without a token.
unauthorized	403	This request has authorization parameters, for example a minimum role in an organization, that the authentication token does not meet.
not_implemented	501	This request reaches an endpoint that is not implemented.
conflict	409	The request could not be completed due to a conflict with the current state. For example, an account could not be created because an account with the same email address already exists.
internal	500	The request could not be completed due to an internal error. The request may succeed if the client retries.
bad_input	400	The request could not be completed due to invalid input. For example, a request to create an account with an invalid email address.
timeout	408	The request could not be completed due to a timeout elsewhere in the system.
rate	429	The requester has exceeded their allowed rate limit. The requester can retry the request after a delay.

Rate limiting

We rate limit API endpoints using a Sliding Window algorithm. The default rate limit is 100 requests per minute, though some endpoints may allow for more or fewer depending on: the limitations of underlying APIs, security considerations, user need. You can assess if you are approaching rate limits by using the X-Ratelimit-Limit, X-Ratelimit-Remaining, and X-Ratelimit-Reset headers per the HTTP standards track for rate limiting headers.

Introspection

The FlexStack API can be introspected using the Swagger Editor. You can view our schema at https://api.flexstack.com/openapi.json