Timextender Orchestration API¶

The Public Orchestration API lets external systems, CI/CD pipelines, and third-party tools read orchestration status, trigger executions, and retrieve logs — using the same access controls as the web application.

This API was introduced in Timextender Data Platform 26.2

Contents¶

1. Base URL
2. Getting started — creating an API key
3. Authentication
4. Common parameters
5. Task types reference
6. Endpoints - Workspaces - Process Maps - Tasks - Executions
7. Error reference
8. Quick-start examples

Base URL¶

https://{tenant}.odq.timextender.com

Replace {tenant} with your customer subdomain (e.g. acme → https://acme.odq.timextender.com).

All endpoint paths in this document are relative to the base URL. A full request URL looks like:

https://acme.odq.timextender.com/api/v0/orchestration/workspaces

Note that the endpoint will change later this year to https://acme.timextender.com/api/...

Getting started — creating an API key¶

API keys are managed inside the TDP web application. A key inherits the exact same permissions as the user who created it — workspace access, process map visibility, and everything else. Think of a key as a password for your account that can be used by a script or external system.

Creating a key¶

1. Sign in to the TDP web application.
2. Click your name or avatar in the bottom-left corner of the navigation and select User Preferences, or navigate directly to /all/preferences.
3. Select the API Keys tab.
4. Click Create.
5. Enter a description that identifies what this key will be used for (e.g. Azure DevOps pipeline, Grafana dashboard). Maximum 100 characters.
6. Click Create in the dialog.
7. The full API key is displayed once. Copy it immediately — it cannot be retrieved again.

The key has the format txk_ followed by 32 alphanumeric characters:

txk_ABCDEFGHIJKLMNOPQRSTUWXYZ1234567890

After creation, only a masked preview is shown in the UI (e.g. txk_••••••••j2frD).

Limits: Each user can have a maximum of 3 active keys at the same time. The Create button is disabled when you reach the limit.

Deleting a key¶

To delete one of your own keys:

1. Go to Preferences → API Keys.
2. Select the key in the list.
3. Click Delete and confirm.

Deletion is immediate and permanent. Any request using the deleted key will receive 401 Unauthorized.

Admin: viewing and deleting all keys¶

Administrators can see every active key in the workspace and delete any of them:

1. Go to Settings → API Keys.
2. The grid shows all active keys with the owner's name and email, description, creation date, and last-used date.
3. Select a key and click Delete to invalidate it immediately.

This is useful for offboarding users or responding to a suspected key compromise.

Authentication¶

Pass your API key in every request using the X-API-Key header:

GET /api/v0/orchestration/workspaces HTTP/1.1
Host: acme.odq.timextender.com
X-API-Key: txk_ABCDEFGHIJKLMNOPQRSTUWXYZ1234567890

The API key is validated on every request. The last_used timestamp on the key is updated automatically.

Authorization¶

A key carries the same permissions as the user who created it:

• Only workspaces the user has access to are returned.
• Process maps and tasks the user cannot see are excluded.
• Trigger endpoints require Contributor access on the workspace; read endpoints require Viewer access.

Authentication errors¶

Common parameters¶

uat — Environment¶

Most endpoints accept a uat query parameter to target a specific data environment within the workspace.

If omitted, Production is used. Passing an unrecognised value returns 400 Bad Request.

GET /api/v0/orchestration/finance/tasks?uat=Development

Pagination — limit and offset¶

All list endpoints support offset-based pagination.

limit must be greater than 0 and offset must be 0 or greater — otherwise the request returns 400 Bad Request.

When the number of items returned is less than limit, you are on the last page.

# Page 1
GET /api/v0/orchestration/finance/tasks?limit=50&offset=0

# Page 2
GET /api/v0/orchestration/finance/tasks?limit=50&offset=50

# Page 3
GET /api/v0/orchestration/finance/tasks?limit=50&offset=100

Task types reference¶

The API uses stable PascalCase names for task types. Always use the taskType value returned by a list endpoint when constructing trigger or detail requests.

Endpoints¶

Workspaces¶

GET /api/v0/orchestration/workspaces¶

Returns all workspaces the authenticated user has Viewer or higher access to.

Response 200 OK

[
  {
    "key": "finance",
    "name": "Finance",
    "description": "Finance data governance workspace"
  },
  {
    "key": "sales",
    "name": "Sales",
    "description": null
  }
]

Process Maps¶

GET /api/v0/orchestration/{workspace}/process-maps¶

Returns process maps in the given workspace.

Pass all as {workspace} to retrieve process maps across every workspace the user can access.

Path parameters

Query parameters: uat, limit, offset

Response 200 OK

[
  {
    "processMapId": 42,
    "name": "Daily Finance Load",
    "workspace": "finance",
    "lastExecutionDate": "2026-03-14T22:00:00",
    "successfulTasks": 18,
    "failedTasks": 0,
    "runningTasks": 0,
    "queuedTasks": 0,
    "disabledTasks": 2
  }
]

GET /api/v0/orchestration/{workspace}/process-maps/{processMapId}/tasks¶

Returns all tasks belonging to a specific process map.

Path parameters

Query parameters: uat

Response 200 OK — array of task objects.

Error responses

POST /api/v0/orchestration/{workspace}/process-maps/{processMapId}/trigger¶

Triggers a process map to run. Returns immediately; execution is asynchronous. Requires Contributor access on the workspace.

Path parameters

Request body

{
  "uat": "Production"
}

Response 202 Accepted — empty body.

Error responses

Tasks¶

GET /api/v0/orchestration/{workspace}/tasks¶

Returns all tasks in the workspace, grouped across all process maps.

Pass all as {workspace} to retrieve tasks from every accessible workspace.

Path parameters

Query parameters: uat, limit, offset

Response 200 OK — array of task objects.

GET /api/v0/orchestration/{workspace}/tasks/{taskType}/{taskId}¶

Returns details for a single task.

Path parameters

Query parameters: uat

Response 200 OK — a single task object.

Error responses

POST /api/v0/orchestration/{workspace}/tasks/{taskType}/{taskId}/trigger¶

Triggers a single task to run. Returns immediately; execution is asynchronous. Requires Contributor access on the workspace.

Path parameters

Request body

{
  "uat": "Production"
}

Response 202 Accepted — empty body.

Error responses

Task object¶

Used in both the workspace task list and the process-map task list.

{
  "taskId": 1005,
  "taskName": "Load Customer Dim",
  "taskType": "Package",
  "status": "Finished",
  "processMapId": 42,
  "processMapName": "Daily Finance Load",
  "lastExecutionStartTime": "2026-03-14T22:00:05",
  "lastExecutionEndTime": "2026-03-14T22:01:32"
}

Executions¶

These endpoints provide visibility into when tasks ran, how long they took, and what output they produced.

GET /api/v0/orchestration/{workspace}/executions¶

Returns the latest execution state for every task in the workspace — one entry per task. Use this to build a status dashboard or health check.

Path parameters

Query parameters: uat, limit, offset

Response 200 OK

[
  {
    "taskId": 1005,
    "taskName": "Load Customer Dim",
    "taskType": "Package",
    "status": "Finished",
    "lastStartTime": "2026-03-14T22:00:05",
    "lastEndTime": "2026-03-14T22:01:32",
    "duration": "01m 27s"
  },
  {
    "taskId": 2010,
    "taskName": "Validate Customer Count",
    "taskType": "Query",
    "status": "Failed",
    "lastStartTime": "2026-03-14T22:02:00",
    "lastEndTime": "2026-03-14T22:02:03",
    "duration": "03s"
  },
  {
    "taskId": 3001,
    "taskName": "Send Summary Email",
    "taskType": "EmailSummary",
    "status": "Running",
    "lastStartTime": "2026-03-15T08:30:00",
    "lastEndTime": null,
    "duration": ""
  }
]

Error responses

GET /api/v0/orchestration/{workspace}/tasks/{taskType}/{taskId}/executions¶

Returns the execution history for a specific task, newest first.

Path parameters

Query parameters: uat, limit (default 50), offset

Response 200 OK

[
  {
    "executionId": 98231,
    "startTime": "2026-03-14T22:00:05",
    "endTime": "2026-03-14T22:01:32",
    "status": "Finished",
    "durationSeconds": 87
  },
  {
    "executionId": 97105,
    "startTime": "2026-03-13T22:00:07",
    "endTime": "2026-03-13T22:00:09",
    "status": "Failed",
    "durationSeconds": 2
  },
  {
    "executionId": 97210,
    "startTime": "2026-03-15T08:30:00",
    "endTime": null,
    "status": "Running",
    "durationSeconds": null
  }
]

Error responses

GET /api/v0/orchestration/{workspace}/tasks/{taskType}/{taskId}/executions/{execId}/log¶

Returns the log output recorded during a specific execution.

Log entries contain the output and error messages written by the execution engine during the run. For Query and CompareQuery task types, logs are not stored in this format and an empty array is always returned.

Path parameters

Response 200 OK

[
  {
    "logTime": "2026-03-13T22:00:07",
    "log": "Starting package execution: Load Customer Dim"
  },
  {
    "logTime": "2026-03-13T22:00:08",
    "log": "Connecting to source: dw-prod.database.windows.net"
  },
  {
    "logTime": "2026-03-13T22:00:09",
    "log": "ERROR: Connection timeout after 30s. The remote server did not respond."
  }
]

Returns [] (empty array) for Query and CompareQuery task types.

Error responses

Error reference¶

All error responses return JSON in the following format:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "title": "Not Found",
  "status": 404,
  "traceId": "00-abc123def456..."
}

400 Bad Request responses for an unrecognised taskType return a plain-text message listing the valid values:

Unknown taskType 'Pkg'. Valid values: Query, CompareQuery, Package, ObjectGroup,
Process, ScheduleGroup, TestGroup, OrchestrationMap, Link, EmailSummary, Rule.

Status code summary¶

Interactive API explorer¶

A Swagger UI is available where you can browse all endpoints and test them directly in the browser:

https://{tenant}.odq.timextender.com/swagger          (production)

1. Open the Swagger UI.
2. Click Authorize (top right).
3. Enter your API key in the X-API-Key field.
4. Click Authorize, then Close.
5. Expand any endpoint and click Try it out.

Quick-start examples¶

Discover available workspaces¶

curl https://acme.odq.timextender.com/api/v0/orchestration/workspaces \
  -H "X-API-Key: txk_your_key_here"

List all tasks in a workspace¶

curl "https://acme.odq.timextender.com/api/v0/orchestration/finance/tasks?limit=50" \
  -H "X-API-Key: txk_your_key_here"

Get the current status of every task (dashboard)¶

curl "https://acme.odq.timextender.com/api/v0/orchestration/finance/executions" \
  -H "X-API-Key: txk_your_key_here"

Find failed executions for a task¶

curl "https://acme.odq.timextender.com/api/v0/orchestration/finance/tasks/Package/1005/executions?limit=10" \
  -H "X-API-Key: txk_your_key_here"

Read the log for a specific failed run¶

curl "https://acme.odq.timextender.com/api/v0/orchestration/finance/tasks/Package/1005/executions?limit=10" \
  -H "X-API-Key: txk_your_key_here"

Trigger a task¶

curl -X POST "https://acme.odq.timextender.com/api/v0/orchestration/finance/tasks/Package/1005/trigger" \
  -H "X-API-Key: txk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"uat": "Production"}'

Trigger an entire process map¶

curl -X POST "https://acme.odq.timextender.com/api/v0/orchestration/finance/process-maps/42/trigger" \
  -H "X-API-Key: txk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"uat": "Production"}'

Page through a large task list¶

# Fetch in batches of 25
curl "https://acme.odq.timextender.com/api/v0/orchestration/finance/tasks?limit=25&offset=0"  -H "X-API-Key: txk_your_key_here"
curl "https://acme.odq.timextender.com/api/v0/orchestration/finance/tasks?limit=25&offset=25" -H "X-API-Key: txk_your_key_here"
curl "https://acme.odq.timextender.com/api/v0/orchestration/finance/tasks?limit=25&offset=50" -H "X-API-Key: txk_your_key_here"