REST API Connection
This guide describes how to configure Retool to execute semantic queries against the Timbr REST API using either a Timbr API token or an OAuth 2.0 (JWT) authentication flow.
Creating a Resource with Timbr API Token
Follow these steps to create a Retool Resource that authenticates using a Timbr-issued token.
- In Retool, open the Resources tab and click Create new → Resource.
- Under the APIs category, select REST API.
- Configure the resource with the following values:
Configuration (Token Based)
| Field | Value |
|---|---|
| Base URL | Timbr environment URL including protocol (e.g., https://demo-env.timbr.ai) |
| URL Parameters | /timbr/api/query/ |
Header: Content-Type | application/json |
Header: x-api-key | <Timbr API token> |
| Body | (leave empty) |
| Cookies | (leave empty) |
| Authentication | None |
The trailing slash in
/timbr/api/query/is required if present in your environment's routing configuration. Remove it if your gateway normalizes paths.
- Click Create resource. If any validation errors occur, review each field and correct the values as needed.
Creating a Resource with OAuth 2.0 (JWT)
Use this option when your organization enforces SSO or centralized identity governance.
- In Retool, open the Resources tab and click Create new → Resource.
- Select REST API.
- Configure the resource as follows:
Configuration (OAuth 2.0 JWT)
| Field | Value |
|---|---|
| Base URL | Timbr environment URL including protocol (e.g., https://demo-env.timbr.ai) |
| URL Parameters | (leave empty) |
Header: x-jwt-token | OAUTH2_TOKEN (Retool automatically substitutes this placeholder) |
| Body | (leave empty) |
| Cookies | (leave empty) |
| Authentication | OAuth 2.0 → Authorization Code Grant |
| Authorization URL | e.g., https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize |
| Access Token URL | e.g., https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token |
| Client ID | Value from your identity provider |
| Client Secret | Value from your identity provider |
| Scopes | (list scopes if required by provider) |
| Prompt | consent (or retain default) |
- Click Connect with OAuth to initiate the authorization flow.
- After successful authentication you are redirected back to the Create resource page with a success notification.
- Click Create resource to finalize.
| Topic | Guidance |
|---|---|
| Token Substitution | Retool injects the resolved JWT into the x-jwt-token header automatically. Do not hard-code tokens. |
| Tenant ID | In Azure AD this is the Directory (tenant) ID. Ensure you're using the correct directory for the Timbr environment. |
| Scopes | Only include those required for issuing a valid JWT. Extraneous scopes can cause consent failures. |
Executing Semantic Queries Using the Resource
Once the resource is created, you can issue semantic SQL queries to Timbr.
The following example uses the resource with Timbr API Token to execute the semantic query.
- Open (or create) a Retool app and drag a query-capable component (e.g., Query JSON with REST API, Table binding, etc.).
- Select the previously created REST API resource.
- Set the HTTP method to POST and set the endpoint path to
timbr/api/query(omit a leading slash unless Retool requires it based on your Base URL format). - In the Body section, choose JSON and provide the required payload fields:
| Field | Description |
|---|---|
ontology_name | The ontology name defined in Timbr |
query | Semantic SQL statement (e.g., SELECT * FROM concept_name LIMIT 10) |
- Click Preview to validate. If results look correct, click Save.
- If your UI component does not automatically render data, select the component and in the right-hand panel set its data source to:
{{query1.data.data}}.
Replace query1 with the actual name of your Retool query.
Troubleshooting
| Symptom | Possible Cause | Resolution |
|---|---|---|
| 401 Unauthorized | Invalid or expired token | Regenerate token or re-authenticate OAuth resource |
| 404 Not Found | Incorrect endpoint path | Verify timbr/api/query vs /timbr/api/query/ based on Base URL normalization |
| CORS / network error | Corporate proxy or firewall rules | Whitelist Timbr domain and Retool egress |
Summary
You can integrate Retool with Timbr via either direct API token authentication or enterprise SSO using OAuth 2.0 JWT flows. After configuring the resource, semantic SQL queries can be posted to timbr/api/query, returning ontology-aware results for rapid application prototyping and internal tooling.
For expanded capabilities (relationships expansion, calculated properties, pagination, etc.) refer to the official Timbr API documentation.