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):

Field	Type	Required	Description
`table_definition_id`	integer	Yes*	ID of the deployed table definition
`table_definition_key`	string	Yes*	Key of the table (alternative to ID)
`branch_id`	integer	Yes*	Branch ID (required when using `table_definition_key`)
`startRow`	integer	Yes	Starting row index (0-based)
`endRow`	integer	Yes	Ending row index (max 1000 rows per request)
`filterModel`	object	No	AG Grid filter model
`sortModel`	array	No	AG Grid sort model

*Provide either table_definition_id or table_definition_key + branch_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):

Field	Type	Required	Description
`table_definition_id`	integer	Yes	Deployed table definition ID
`record`	object	Yes	Column name/value pairs

Response: 201 Created with the created record.

Update Record

PATCH /api/v1/table_data/{id}

Parameters (body):

Field	Type	Required	Description
`table_definition_id`	integer	Yes	Deployed table definition ID
`record`	object	Yes	Column name/value pairs to update

Delete Records (Soft Delete)

POST /api/v1/table_data/delete_records

Parameters (body):

Field	Type	Required	Description
`table_definition_id`	integer	Yes	Deployed table definition ID
`ids`	array[integer]	Yes	Array of `trdm_sk` values to soft-delete

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:

Parameter	Description
`branch_id`	Filter by branch
`q`	Search by name

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):

Field	Type	Required	Description
`branch_id`	integer	Yes	Branch to create on
`table_definition[name]`	string	Yes	Table name
`table_definition[description]`	string	No	Description
`table_definition[domain_id]`	integer	Yes	Domain ID
`table_definition[load_type]`	string	No	`manual` or `source`
`table_definition[lookup_display_column_id]`	integer	No	Column ID for FK display

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):

Field	Type	Required	Description
`target_branch_id`	integer	Yes	Branch to clone to

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):

Field	Type	Required	Description
`table_definition_id`	integer	Yes	Parent table definition
`column_definition[name]`	string	Yes	Column name
`column_definition[data_type]`	string	Yes	Data type (e.g., `string`, `integer`, `decimal`, `date`, `datetime`, `boolean`, `text`)
`column_definition[length]`	integer	No	Max length (for string type)
`column_definition[scale]`	integer	No	Decimal places (for decimal type)
`column_definition[is_primary_key]`	boolean	No	Part of composite primary key
`column_definition[is_required]`	boolean	No	NOT NULL constraint
`column_definition[foreign_key_table_id]`	integer	No	Referenced table definition ID
`column_definition[valid_values]`	string	No	Pipe-delimited list of allowed values
`column_definition[description]`	string	No	Column description

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:

Parameter	Description
`branch_id`	Filter by branch
`domain_id`	Filter by domain
`q`	Search by name

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):

Field	Type	Required	Description
`domain[name]`	string	Yes	Domain name
`domain[abbreviation]`	string	No	Short code
`domain[description]`	string	No	Description

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 (requires Business/Enterprise for create/update/delete).

List Branches

GET /api/v1/branches

Available on all plans.

Show Branch

GET /api/v1/branches/{id}

Includes parent branch, owner, user groups, and members.

Create Branch

POST /api/v1/branches

Requires branching-enabled plan and user context.

Parameters (body):

Field	Type	Required	Description
`branch[name]`	string	Yes	Branch name

Update Branch

PATCH /api/v1/branches/{id}

Parameters (body):

Field	Type	Required	Description
`branch[name]`	string	No	New name
`branch[description]`	string	No	New description

Delete Branch

DELETE /api/v1/branches/{id}

Set Current Branch

POST /api/v1/branches/set_current_branch

Requires user context.

Field	Type	Required	Description
`branch_id`	integer	Yes	Branch to set as current

Deployments

Manage deployments (requires branching-enabled plan and user context).

List Deployments

GET /api/v1/deployments

Show Deployment

GET /api/v1/deployments/{id}

Returns deployment details, table definitions, and computed diffs.

Create Deployment

POST /api/v1/deployments

Parameters (body):

Field	Type	Required	Description
`branch_id`	integer	Yes	Target branch
`table_definition_ids`	array[integer]	Yes	Table definitions to deploy

Execute Deployment

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

Builds diffs and executes SQL changes against the database.

Send Deployment Request

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

Field	Type	Required	Description
`comment`	string	No	Message for approvers

Reject Deployment

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

Field	Type	Required	Description
`comment`	string	No	Rejection reason

Cancel Deployment

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

Abandon Deployment

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

Notifies approvers via email.

Promotions

Manage promotions (requires branching-enabled plan and 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):

Field	Type	Required	Description
`from_branch_id`	integer	Yes	Source branch
`to_branch_id`	integer	Yes	Target branch
`table_definition_ids`	array[integer]	Yes	Table definitions to promote

Execute Promotion

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

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

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):

Field	Type	Required	Description
`branch_id`	integer	Yes	Target branch
`correlation_code`	string	No	Custom correlation code (auto-generated if omitted)

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:

Parameter	Description
`table_definition_key`	Filter by table key
`branch_id`	Filter by branch

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):

Field	Type	Required	Description
`branch_id`	integer	Yes	Source branch
`table_definition_key`	string	Yes	Table key to export
`pattern`	string	Yes	`full` or `incremental`
`high_water_mark`	string	Conditional	Required for incremental exports (ISO 8601 datetime)
`correlation_code`	string	No	Custom correlation code

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):

Field	Type	Required	Description
`user_id`	integer	Yes	User to assign
`user_group_id`	integer	Yes	Target group

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).

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