Skip to main content
API Overview

Introduction to the API, including authentication

Jeff Schnitzer avatar
Written by Jeff Schnitzer
Updated over a week ago

OrbitKit provides a JSON REST API to help you manage your organization.

General Conventions

Requests which submit a JSON body (eg, POSTs) must specify Content-Type: application/json

Authentication

All requests must include your organization's secret key in a header named X-Secret. You can find (and regenerate) your secret key on your organization's Settings page:

With all requests, include a header like this:

X-Secret: 5ec3f5b72f76c8dcf5e64999472527c8

This key limits the API to manipulating data for your (and only your) organization.

Errors

Errors will produce a 400 (or 500) level HTTP error code with a JSON body structured like this:

{
"message": "The oscillation overthruster is missing",
"type": "CriticalComponentMissing",
"types": ["CriticalComponentMissing", "Missing"],
}

The types field will read more specific error types to more general error types.

410 GONE

In the case of requests for objects that no longer exist, the OrbitKit API always returns 410 GONE instead of 404 NOT FOUND. It's just too easy to fat-finger a URL or misconfigure a proxy and suddenly your code is misinterpreting the responses.

Pagination

Some API endpoints are paginated. These endpoints accept two extra parameters, limit and cursor. They always return structures that look like this:

{
"data": [{...}, {...}, {...}],
"total": 3947,
"more": "an opaque cursor string",
}

If more is null, you are at the end. Otherwise you can pass the more value to the endpoint as a cursor parameter to receive the subsequent results.

More?

This API is being built out progressively to satisfy user requests. If you want to do something, and you don't see a way to do it, reach out to us and we'll add it.

Did this answer your question?