SDK Imports and Exports

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

This guide covers how to automate bulk data imports and exports programmatically using the TitanRDM API. These workflows are designed for ETL pipelines, scheduled syncs, and CI/CD integrations that need to move data in and out of TitanRDM without manual intervention.

---

Prerequisites

• An OAuth Application with api:write scope (for imports) or api:read scope (for exports)
• A valid access token (see Authentication)
• At least one deployed table on the target branch

---

Export Workflow

Exports extract data from a deployed table into a downloadable file. The process is asynchronous — you create the export, then poll until it completes.

Step 1: Identify the Table

Find the table you want to export by listing deployed table definitions:

curl -H "Authorization: Bearer $TOKEN" \
  "https://{subdomain}.titanrdm.com/api/v1/deployed_table_definitions?branch_id=1"

Note the key and branch_id of your target table.

Step 2: Create the Export

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  https://{subdomain}.titanrdm.com/api/v1/exports \
  -d '{
    "branch_id": 1,
    "table_definition_key": "currency_codes",
    "pattern": "full",
    "correlation_code": "nightly-sync-2024-06-01"
  }'

Parameters:

Response (201):

{
  "id": 42,
  "correlation_code": "nightly-sync-2024-06-01",
  "table_definition_key": "currency_codes",
  "pattern": "full",
  "status": "created",
  "download_url": null
}

Step 3: Poll for Completion

The export runs asynchronously as a background job. Poll the export endpoint:

curl -H "Authorization: Bearer $TOKEN" \
  https://{subdomain}.titanrdm.com/api/v1/exports/42

Statuses:

Step 4: Download the File

Once status is completed, the download_url field contains a pre-signed URL to download the exported file:

curl -o currency_codes.csv "$DOWNLOAD_URL"

Incremental Exports

For delta/change-data-capture workflows, use the incremental pattern:

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  https://{subdomain}.titanrdm.com/api/v1/exports \
  -d '{
    "branch_id": 1,
    "table_definition_key": "currency_codes",
    "pattern": "incremental",
    "high_water_mark": "2024-05-31T00:00:00Z"
  }'

This exports only rows where trdm_updated_at > 2024-05-31T00:00:00Z.

Tip: Store the complete_datetime from the export response and use it as the high_water_mark for the next incremental export.

---

Import Workflow

Imports load data from files into deployed tables. The API import workflow involves creating an import, uploading data for each table, and then signalling completion.

Step 1: Create the Import

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  https://{subdomain}.titanrdm.com/api/v1/imports \
  -d '{
    "branch_id": 1,
    "correlation_code": "etl-run-2024-06-01"
  }'

Response (201):

{
  "id": 99,
  "correlation_code": "etl-run-2024-06-01",
  "status": "created",
  "branch": { "id": 1, "name": "prod", "branch_type": "shared" }
}

Step 2: Upload Data Files

Upload data files for each table in the import. The upload mechanism depends on your deployment configuration (direct upload or pre-signed URL).

Each file upload creates an import table record that tracks the processing of that specific table's data.

Step 3: Signal Upload Complete

Once all files are uploaded:

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  https://{subdomain}.titanrdm.com/api/v1/imports/99/upload_complete

This triggers auto-finalization: if all import tables have finished processing (merged, completed, or failed), the import status is set automatically.

Step 4: Check Status

curl -H "Authorization: Bearer $TOKEN" \
  https://{subdomain}.titanrdm.com/api/v1/imports/99

Response includes: - import — overall import status and metadata - import_tables — per-table processing details (status, row counts, duration) - metrics — summary metrics per import table - import_actions — audit trail of all actions

Step 5: Complete the Import (Optional)

If you want to explicitly mark the import as complete:

curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://{subdomain}.titanrdm.com/api/v1/imports/99/complete

---

Import Table Metrics

Each import table tracks detailed metrics:

---

Automation Patterns

Nightly Full Sync

#!/bin/bash
# Export all reference data nightly

TABLES=("currency_codes" "country_codes" "product_categories")
BRANCH_ID=1
DATE=$(date +%Y-%m-%d)

for TABLE in "${TABLES[@]}"; do
  # Create export
  EXPORT_ID=$(curl -s -X POST -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    https://{subdomain}.app.titanrdm.com/api/v1/exports \
    -d "{\"branch_id\": $BRANCH_ID, \"table_definition_key\": \"$TABLE\", \"pattern\": \"full\", \"correlation_code\": \"nightly-$DATE-$TABLE\"}" \
    | jq -r '.id')

  # Poll until complete
  while true; do
    STATUS=$(curl -s -H "Authorization: Bearer $TOKEN" \
      https://{subdomain}.app.titanrdm.com/api/v1/exports/$EXPORT_ID \
      | jq -r '.status')

    if [ "$STATUS" = "completed" ]; then
      # Download the file
      URL=$(curl -s -H "Authorization: Bearer $TOKEN" \
        https://{subdomain}.app.titanrdm.com/api/v1/exports/$EXPORT_ID \
        | jq -r '.download_url')
      curl -o "/data/exports/${TABLE}_${DATE}.csv" "$URL"
      break
    elif [ "$STATUS" = "failed" ]; then
      echo "Export failed for $TABLE"
      break
    fi
    sleep 5
  done
done

Incremental Change Detection

#!/bin/bash
# Track changes since last sync

LAST_SYNC=$(cat /data/last_sync_timestamp.txt)

EXPORT_ID=$(curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  https://{subdomain}.app.titanrdm.com/api/v1/exports \
  -d "{\"branch_id\": 1, \"table_definition_key\": \"currency_codes\", \"pattern\": \"incremental\", \"high_water_mark\": \"$LAST_SYNC\"}" \
  | jq -r '.id')

# Poll and download as above...

# Update high water mark
date -u +%Y-%m-%dT%H:%M:%SZ > /data/last_sync_timestamp.txt

Direct Data Operations (No File)

For smaller datasets, use the Table Data API directly instead of file-based imports:

# Create records one at a time
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  https://{subdomain}.app.titanrdm.com/api/v1/table_data \
  -d '{
    "table_definition_id": 1,
    "record": {
      "currency_code": "EUR",
      "currency_name": "Euro"
    }
  }'

# Update a record
curl -X PATCH -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  https://{subdomain}.app.titanrdm.com/api/v1/table_data/42 \
  -d '{
    "table_definition_id": 1,
    "record": {
      "currency_name": "Euro (EUR)"
    }
  }'

# Soft-delete records
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  https://{subdomain}.app.titanrdm.com/api/v1/table_data/delete_records \
  -d '{
    "table_definition_id": 1,
    "ids": [42, 43, 44]
  }'

---

Error Handling

---

Usage Limits

Imports and exports count against your plan's usage allowances:

If overage billing is enabled, operations beyond the limit are charged at the overage rate. Otherwise, they are blocked with a 429 response.

---

Related Pages

• API Overview — general API concepts
• API Endpoints Reference — full endpoint documentation
• Authentication — obtaining tokens
• Importing Data — UI import workflow
• Exporting Data — UI export workflow