The Graviton API

Most services on a graviton instance have a predictable API surface.

Each service comes in two parts, the schema declaration as well as the actual API endpoints.

The examples below are based around the /core/app/ services which usually exist on all graviton instances.

Only a very small amount of graviton services do not follow this convention. In fact the only currently exception should be the version service which has its own documentation.

More documentation is always available

Full documentation on all the available services is self hosted on each graviton instance.

A basic service listing may be found at the root URL.


A more complete overview is available through a swagger definition.




All of our output has adequate schema documentation that may be used for validation of graviton data structures. Much more important is that this schema information allows us to add inline documentation on the semantics of the data provided by graviton.

Schema describing an individual document


Schema describing a collection of documents


Collection schemas are available as a convenience so you may use them against our collection endpoints. For the most part they contain the same data you would also find in the corresponding item schema.


GET collection of documents


You can search in collections using RQL.

Getting invalid data with RQL select() operator

Note that it is possible to export data that does not adhere to the schemas using the RQL select() operator.

As a rule of thumb, if you plan on modifying retrieved documents and want to PUT them into graviton again, you should probably not use the operator.

POST a new document (server defines id)

curl -X POST -d '{}'

Check the response headers to see what id your document was stored at.

PUT a new document or update an existing one (client defines id)

curl -X PUT -d '{"id": "my-id"}'

This is also referred to as an upsert operation.

GET an existing document

curl -X GET

DELETE a document

curl -X DELETE

Learn More