Besides the server, everything else in the Speckle platform is, at the end of the day, an API client. The Speckle REST API's documentation lives in a separate place. It covers all the essential endpoints, specifically:
- Accounts: creating new users, logging in, etc.
- Streams: creating, updating, deleting and diffing streams
- Objects: base create, read, update, delete
- Projects: grouping streams together and setting permissions
- etc.
Interacting & Testing the API
The Speckle API is documented in the OpenAPI v3 format, which allows you to easily import it into an API tool of choice and start hacking. Which API tools? There's quite a few to choose from: Postman, Insomnia, Paw, etc.
If you want a leg up, you can download and import in the API tool of your choice the raw specification file, if it supports OpenApi specs. You can, of course, interact with Speckle straight from the command line, if you're so inclined! TIP: jq will help you parse JSON in the command line.
curl -X POST https://hestia.speckle.works/api/streams \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: API_KEY'
Querying
The Speckle REST API supports powerful querying features. For example, below are some of the queries you could apply to the StreamGetObjects
request.
limit
: maximum number of objects returned.offset
: number of objects to skip (or offset) before returning.omit
: which fields to omit from every object. Cannot be used in conjunction withfields
.fields
: which fields to include from every object._id
is always returned. Cannot be used in conjunction withomit
.- Filtering based on the value of a field. For example,
type=Point
will only return objects who's type isPoint
andproperties.height<10
will only return objects withproperties.height
less than 10.- Supports standard comparison operators (i.e.,
=
,!=
,>
,<
,>=
,<=
) - Supports multiple matches with comma separated lists (e.g.,
type=Point,Mesh
) - Supports regex patterns (e.g.,
type=/^.+?esh/
) - For more information, see query-to-mongo filtering
- Supports standard comparison operators (i.e.,
You can use the tool below to test out some queries. Please note, if nothing happens when you click test, navigate away from this page and return. It's a weird bug.