Treefort’s API allows you to automate any task that can be accomplished through the admin dashboard. This is a developer tool and requires technical skill to setup.
Host
The Treefort API and authentication services are available via the primary domain that you’ve setup for your Treefort app. For example, if your web app is hosted at mytreefortapp.com then you will make API and authentication calls to endpoints (documented below) on that host.
Endpoints
API endpoint: /api/v1
OAuth token endpoint: /oauth2/token
Reference documentation
By version: /api/v1/docs
Latest version: /api/v1/docs/latest
Headers
Send the following headers along with every API request.
X-Treefort-Version
Our API is versioned by date, with the latest date reflecting the latest iteration of the API. See the reference documentation above for the list of available versions. We will do our best to continue support for older versions of the API, but please stick as close to the latest available version as you can.
Authentication
🚧 API access is invite only. Please reach out to us for API credentials.
Use the OAuth Client Credentials grant to authenticate your calls to the API. This is a standardized, two-step process:
Send your client ID and client secret along with the scope
target-entity:de24cc4d-765c-4649-bc41-925bc5d9eee0to the OAuth token endpoint to fetch an access token.curl -X POST \
-u "<client_id>:<client_secret>" \
"https://<your domain>/oauth2/token?grant_type=client_credentials&scope=target-entity%3Ade24cc4d-765c-4649-bc41-925bc5d9eee0"Send this access token to the API in the Authorization header (prefixed with “Bearer“) to authenticate your calls.
curl -H "Authorization: Bearer <access_token>" \
-H "X-Treefort-Version: <api_version>" \
"https://<your domain>/api/v1"
Permissions
Our API endpoints are locked behind fairly granular permissions via OAuth scopes. Expand the “Authorizations” section at the top of the documentation page for an endpoint to see the required scopes (e.g. content:read or entitlements:write). We currently enable these scopes for your API client on a case-by-case basis. If you’d like access to a particular scope, just ask us.
When exchanging your client credentials for an access token you must request the scope target-entity:de24cc4d-765c-4649-bc41-925bc5d9eee0. This will generate an access token that contains all of the API scopes that your client has access to.
Rate limits
We hope that our API allows you to accomplish more than ever with Treefort, but we do ask that you use this resource responsibly. Our goal is to maintain a reliable and efficient service for you and your users. To help us achieve this, requests to our API are limited at the following rates:
PUT/POST/PATCH/DELETE /api/* - 10 requests / 5 seconds
GET /api/v1/users, GET /api/v1/content - 20 requests / 10 seconds
GET /api/* - 200 requests / 10 seconds
POST /oauth2/token - 10 requests / 10 seconds
Rate limits aside, please be mindful of your usage and avoid unnecessary API calls. If we detect that your usage causes an undue burden on the system we may restrict your access and reach out to help you accomplish your goals with fewer API calls. We appreciate your cooperation in helping us provide a stable service!