API
How to approach and interact with the speckle api • Last modified on 10/12/2020 • edit

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.

postman

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 with fields.
  • fields: which fields to include from every object. _id is always returned. Cannot be used in conjunction with omit.
  • Filtering based on the value of a field. For example, type=Point will only return objects who's type is Point and properties.height<10 will only return objects with properties.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

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.
Query Tester