API Endpoints Reference

Available to: Developers (license type) Minimum plan: Free

Complete reference for all TitanRDM REST API v1 endpoints. All endpoints are prefixed with /api/v1/ and require a valid OAuth Bearer token.

---

Conventions

• {id} — numeric resource ID
• Request body — JSON (Content-Type: application/json)
• Pagination — ?page=1&per_page=100 on all collection endpoints
• Filtering — ?q=search_term on most collection endpoints
• Scopes — enforced per HTTP method: api:read (GET), api:write (POST/PATCH/PUT), api:delete (DELETE), api:admin (admin operations)

---

Table Data

Interact with the actual reference data stored in deployed tables.

Query Data (Grid)

POST /api/v1/table_data/grid

Server-side pagination, filtering, and sorting — compatible with AG Grid's request model.

Parameters (body):

*Provide either table_definition_id or table_definition_key + environment_id.

Response:

{
  "rows": [ { "trdm_sk": 1, "col_name": "value", ... } ],
  "rowCount": 500
}

Filter model format:

{
  "column_name": {
    "filterType": "text|number|date",
    "type": "contains|equals|greaterThan|...",
    "filter": "value"
  }
}

Text filter types: contains, notContains, equals, notEqual, startsWith, endsWith

Number filter types: equals, notEqual, lessThan, lessThanOrEqual, greaterThan, greaterThanOrEqual

Date filter types: equals, notEqual, lessThan, greaterThan (use dateFrom field)

---

Show Record

GET /api/v1/table_data/{id}?table_definition_id={td_id}

Returns a single record by its internal ID.

---

Create Record

POST /api/v1/table_data

Parameters (body):

Response: 201 Created with the created record.

---

Update Record

PATCH /api/v1/table_data/{id}

Parameters (body):

---

Delete Records (Soft Delete)

POST /api/v1/table_data/delete_records

Parameters (body):

Sets trdm_is_deleted = true on the specified records.

---

Table Definitions

Manage table definition metadata and column structure.

List Table Definitions

GET /api/v1/table_definitions

Query parameters:

Response: Paginated collection with domain and branch includes.

---

Show Table Definition

GET /api/v1/table_definitions/{id}

Supports lookup by numeric ID, UUID, or key (requires branch_id query param when using key).

Response: Full detail including column definitions and user groups.

---

Create Table Definition

POST /api/v1/table_definitions

Parameters (body):

---

Update Table Definition

PATCH /api/v1/table_definitions/{id}

Same parameters as create (except branch_id).

---

Delete Table Definition

DELETE /api/v1/table_definitions/{id}

Permanently destroys the table definition and all its column definitions.

Response: 204 No Content

---

Clone Table Definition

POST /api/v1/table_definitions/{id}/clone

Parameters (body):

Requires user context (Authorization Code flow).

---

Remove Table Definition

POST /api/v1/table_definitions/{id}/remove

Removes the table definition and its deployed counterpart (if any). Blocked if other tables reference this table via foreign keys.

Response: 204 No Content

---

Column Definitions

Manage columns within a table definition.

List Column Definitions

GET /api/v1/column_definitions?table_definition_id={td_id}

---

Create Column Definition

POST /api/v1/column_definitions

Parameters (body):

---

Update Column Definition

PATCH /api/v1/column_definitions/{id}

---

Delete Column Definition

DELETE /api/v1/column_definitions/{id}

---

Deployed Table Definitions

Read-only access to tables that have been deployed (physical tables exist).

List Deployed Tables

GET /api/v1/deployed_table_definitions

Query parameters:

Only tables deployed to environments you can access are returned. Look up a single table by key with GET /api/v1/deployed_table_definitions/lookup?key=…&environment_id=….

---

Domains

Manage organisational domains.

List Domains

GET /api/v1/domains

---

Show Domain

GET /api/v1/domains/{id}

Includes user groups and their members.

---

Create Domain

POST /api/v1/domains

Requires api:admin scope.

Parameters (body):

---

Update Domain

PATCH /api/v1/domains/{id}

Requires api:admin scope.

---

Delete Domain

DELETE /api/v1/domains/{id}

Requires api:admin scope.

---

Branches

Manage branches (available on all plans).

List Branches

GET /api/v1/branches

---

Show Branch

GET /api/v1/branches/{id}

Includes parent branch, owner, the environments it deploys to, user groups, and members.

---

Create Branch

POST /api/v1/branches

Creates a development (private) branch for the calling user, together with a private environment it deploys to. Requires user context.

Parameters (body):

---

Update Branch

PATCH /api/v1/branches/{id}

Parameters (body):

---

Delete Branch

DELETE /api/v1/branches/{id}

Deletes (archives) the branch and its private environments. They can be restored in the app for 30 days.

---

---

Environments

Environments are deployment targets — for example Prod, Stage, or a developer's Dev environment. Each environment is deployed from one branch.

List Environments

GET /api/v1/environments

Returns the environments you can access.

---

Show Environment

GET /api/v1/environments/{id}

Includes the branch it is deployed from and its owner (for private environments).

---

Create, Update, Delete Environment

POST   /api/v1/environments
PATCH  /api/v1/environments/{id}
DELETE /api/v1/environments/{id}

Account administrators only. Fields: environment[name], environment[schema_name] (create only), environment[branch_id], environment[parent_environment_id], environment[is_prod], environment[environment_type] (shared or private, create only), environment[owner_id], environment[external_id], environment[description]. Deleting an environment hides it; it can be restored in the app for 30 days.

---

Set Current Environment

PATCH /api/v1/environments/set_current

Requires user context.

---

Deployments

Manage deployments (requires user context). A deployment applies a branch's table definitions to one environment.

List Deployments

GET /api/v1/deployments

Returns deployments to environments you can access, oldest first.

Each deployment includes its environment, source branch, and promotion (if any).

---

Show Deployment

GET /api/v1/deployments/{id}

Returns deployment details, table definitions, computed diffs, warnings (tables changed since the deployment was created, older pending deployments), and older_pending_deployment_ids.

---

Create Deployment

POST /api/v1/deployments

Parameters (body):

*Provide table_definition_ids or all_pending: true. Environments of shared branches normally receive deployments from promotions; creating one directly for such an environment requires an account administrator.

---

Execute Deployment

POST /api/v1/deployments/{id}/deploy

Applies the changes to the environment. Requires the Deployer permission on the environment (or ownership of a private environment). Other pending deployments to the same environment whose changes this deployment applies are marked superseded.

Returns 409 Conflict if the deployment is no longer pending (for example it is already deployed or superseded), or while another deployment to the environment is running.

---

Send Deployment Request

POST /api/v1/deployments/{id}/send_request

---

Reject Deployment

POST /api/v1/deployments/{id}/reject

---

Cancel Deployment

POST /api/v1/deployments/{id}/cancel

---

Abandon Deployment

POST /api/v1/deployments/{id}/abandon

Notifies the environment's deployers via email.

---

Promotions

Manage promotions (requires user context).

List Promotions

GET /api/v1/promotions

---

Show Promotion

GET /api/v1/promotions/{id}

Returns promotion details and computed diffs.

---

Create Promotion

POST /api/v1/promotions

Parameters (body):

*Provide table_definition_ids or all_pending: true.

---

Update Promotion

PATCH /api/v1/promotions/{id}

---

Execute Promotion

POST /api/v1/promotions/{id}/promote

Requires the approve permission on the target branch. Copies the table definitions to the target branch and creates a deployment for every environment the target branch deploys to. The response includes those deployments (id, status, environment).

Only a promotion that is created, requested or failed can be promoted. Otherwise, or while the promotion is already being promoted, the response is 409 Conflict.

---

Send Promotion Request

POST /api/v1/promotions/{id}/send_request

---

Reject Promotion

POST /api/v1/promotions/{id}/reject

---

Cancel Promotion

POST /api/v1/promotions/{id}/cancel

---

Abandon Promotion

POST /api/v1/promotions/{id}/abandon

---

CI/CD

Promote and deploy by external id from a CI/CD pipeline: a promotion by its pull request, an environment by its release stage. Requires user context: the Authorization Code flow, or Client Credentials with a service account. Every call is safe to repeat. See CI/CD Integration for the full flow and examples.

Promote by External Id

POST /api/v1/cicd/promote

Requires the approve permission on the target branch. result is promoted or already_promoted; the response includes the promotion and its deployments. Returns 409 for a promotion that is cancelled, abandoned or rejected, and 422 if promoting fails.

---

Deploy a Release

POST /api/v1/cicd/deploy

Deploys every pending deployment to the environment created by promotions up to and including the released promotion, oldest first. Requires the Deployer permission on the environment.

result is deployed, up_to_date, nothing_to_deploy, planned (dry run) or failed. results lists each deployment with its outcome (deployed, superseded, failed or, for a dry run, pending). skipped lists pending deployments not created by a promotion, which are never deployed by a release.

Returns 409 with later_changes when deploying would also apply changes promoted after the released promotion (unless allow_later_changes), and 409 with a Retry-After header while another deployment to the environment is running.

---

CI/CD Status

GET /api/v1/cicd/status?promotion_external_id={id}
GET /api/v1/cicd/status?environment_external_id={id}

• Promotion: status, promotable, merge_commit_sha, tables, and each environment with its deployment for the promotion.
• Environment: pending_deployments in the order a release applies them, and last_deployment (the last deployment created by a promotion, with its release reference in external_id).

---

Imports

Manage data imports.

List Imports

GET /api/v1/imports

---

Show Import

GET /api/v1/imports/{id}

Returns import details, import tables with metrics, and action history.

---

Create Import

POST /api/v1/imports

Parameters (body):

---

Mark Upload Complete

POST /api/v1/imports/{id}/upload_complete

Signals that all file uploads for this import are done. Triggers auto-finalization if all import tables are in a terminal state.

---

Complete Import

POST /api/v1/imports/{id}/complete

Manually marks the import as complete.

---

Exports

Manage data exports.

List Exports

GET /api/v1/exports

Query parameters:

---

Show Export

GET /api/v1/exports/{id}

Returns export details including download_url (when complete), rows_exported, bytes_exported.

---

Create Export

POST /api/v1/exports

Parameters (body):

The export job runs asynchronously. Poll the export GET endpoint until status is completed.

---

Import Mappings

Manage reusable import column mappings for table definitions.

List Import Mappings

GET /api/v1/import_mappings?table_definition_id={td_id}

---

Create Import Mapping

POST /api/v1/import_mappings

---

Update Import Mapping

PATCH /api/v1/import_mappings/{id}

---

Delete Import Mapping

DELETE /api/v1/import_mappings/{id}

---

Users

Manage account users (requires api:admin scope).

List Users

GET /api/v1/users

---

Show User

GET /api/v1/users/{id}

---

Create User

POST /api/v1/users

---

Update User

PATCH /api/v1/users/{id}

---

Delete User

DELETE /api/v1/users/{id}

---

User Groups

List User Groups

GET /api/v1/user_groups

---

Show User Group

GET /api/v1/user_groups/{id}

---

User Group Assignments

List Assignments

GET /api/v1/user_group_assignments?user_group_id={group_id}

---

Create Assignment

POST /api/v1/user_group_assignments

Parameters (body):

---

Delete Assignment

DELETE /api/v1/user_group_assignments/{id}

---

Account

Show Account

GET /api/v1/account

Returns the current account's details, plan, and billing status.

---

Update Account

PATCH /api/v1/account

---

Permissions

List Permissions

GET /api/v1/permissions

Returns all permissions in the account (read-only).

---

Related Pages

• API Overview — general concepts, response format, error codes
• Authentication — OAuth flows and token management
• API Quick Start — hands-on tutorial