Workflow API

Record lifecycles and status transitions, approvals, triggers and running workflows.

Version

Service: Data service and workflow engine
Base path: https://your-data-host/api/v1
Authentication: Bearer token and context headers.

Lifecycle and approval definitions are records, so you create them with the Data API or in TAF Studio. These endpoints move records through a lifecycle and run workflows. Status endpoints identify a record by its record-information id (the platform's record envelope), not by the entity's own id.

GET/api/v1/status/available

Get the statuses a record can move to next

Returns the next statuses allowed by the lifecycle, after the transition's filters and validators for the current user.

Authentication: Bearer token and context headers
Permissions: Your role's access to the resource

Name	In	Required	Description
`recordId`	query	Yes	The record-information id of the record.
`entityName`	query	No	Entity name.

Response

200 OK: the available next statuses.

Example request

curl -X GET "https://your-data-host/api/v1/status/available" \
  -H "Authorization: Bearer $TAF_TOKEN" \
  -H "TenantId: $TENANT_ID" \
  -H "AppId: $APP_ID" \
  -H "EnvironmentId: $ENVIRONMENT_ID"

const res = await fetch("https://your-data-host/api/v1/status/available", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`,
    TenantId: tenantId,
    AppId: appId,
    EnvironmentId: environmentId,
  },
});
const result = await res.json();

using var http = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "https://your-data-host/api/v1/status/available");
request.Headers.Authorization = new("Bearer", token);
request.Headers.Add("TenantId", tenantId);
request.Headers.Add("AppId", appId);
request.Headers.Add("EnvironmentId", environmentId);
var response = await http.SendAsync(request);

PUT/api/v1/status/update

Move a record to a new status

Checks the transition, runs its validators, records the transition in history and then starts any workflows configured to run after it.

Authentication: Bearer token and context headers
Permissions: Your role's access to the resource

Name	In	Required	Description
`recordId`	query	Yes	The record-information id of the record.
`nextStatusId`	query	Yes	The status to move to; must be an allowed transition.
`entityName`	query	No	Entity name.

Response

200 OK when the status has changed.

Error responses

A validation error when the transition is not allowed or a validator fails.

Example request

curl -X PUT "https://your-data-host/api/v1/status/update" \
  -H "Authorization: Bearer $TAF_TOKEN" \
  -H "TenantId: $TENANT_ID" \
  -H "AppId: $APP_ID" \
  -H "EnvironmentId: $ENVIRONMENT_ID"

const res = await fetch("https://your-data-host/api/v1/status/update", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${token}`,
    TenantId: tenantId,
    AppId: appId,
    EnvironmentId: environmentId,
  },
});
const result = await res.json();

using var http = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Put, "https://your-data-host/api/v1/status/update");
request.Headers.Authorization = new("Bearer", token);
request.Headers.Add("TenantId", tenantId);
request.Headers.Add("AppId", appId);
request.Headers.Add("EnvironmentId", environmentId);
var response = await http.SendAsync(request);

POST/api/v1/status/bulk-update

Move many records to a status

Authentication: Bearer token and context headers
Permissions: Your role's access to the resource

Request body

JSON

{
  "RecordIds": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "NextStatusId": "00000000-0000-0000-0000-000000000000",
  "EntityName": "Vendor"
}

Response

200 OK with the outcome per record.

Example request

curl -X POST "https://your-data-host/api/v1/status/bulk-update" \
  -H "Authorization: Bearer $TAF_TOKEN" \
  -H "TenantId: $TENANT_ID" \
  -H "AppId: $APP_ID" \
  -H "EnvironmentId: $ENVIRONMENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "RecordIds": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "NextStatusId": "00000000-0000-0000-0000-000000000000",
  "EntityName": "Vendor"
}'

const res = await fetch("https://your-data-host/api/v1/status/bulk-update", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    TenantId: tenantId,
    AppId: appId,
    EnvironmentId: environmentId,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "RecordIds": [
      "00000000-0000-0000-0000-000000000000"
    ],
    "NextStatusId": "00000000-0000-0000-0000-000000000000",
    "EntityName": "Vendor"
  }),
});
const result = await res.json();

using var http = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://your-data-host/api/v1/status/bulk-update");
request.Headers.Authorization = new("Bearer", token);
request.Headers.Add("TenantId", tenantId);
request.Headers.Add("AppId", appId);
request.Headers.Add("EnvironmentId", environmentId);
request.Content = JsonContent.Create(body); // body: the JSON shown in the cURL tab
var response = await http.SendAsync(request);

POST/api/v1/blueprints

Create a lifecycle with its statuses and transitions

Authentication: Bearer token and context headers
Permissions: Your role's access to the resource

Detailed schema in preparation

The route is part of the service today. Its request and response schema will be published here; until then, use the OpenAPI document on your environment.

POST/api/v1/records/insert

Record an approval decision (insert into the decision entity)

Approval requests start automatically when a record of an approval-enabled entity is written (unless the process is set to start manually). Decisions such as approve, reject, return or delegate are inserts into the platform's approval decision entity through the Data API, so the same access rules and audit apply. The client SDK wraps this as workflow.decide(...).

Authentication: Bearer token and context headers
Permissions: Your role's access to the resource

Detailed schema in preparation

The route is part of the service today. Its request and response schema will be published here; until then, use the OpenAPI document on your environment.

POST/api/v1/workflows/execute/{workflowId}

Run a manual workflow

Runs the workflow's action chain. If an action produces a zip, the response is the file.

Authentication: Bearer token and context headers
Permissions: Your role's access to the resource

Name	In	Required	Description
`workflowId`	path	Yes	The workflow's id. Only workflows of the Manual type can be run this way.

Detailed schema in preparation

Served by the workflow engine. The request schema will be published here; it accepts the tokens the workflow's actions read.

POST/api/v1/records/insert

Define a trigger (insert into the trigger entity)

Triggers are records. They fire on create, edit or delete, with field-change criteria, and start workflows and notifications. Scheduled triggers use a cron expression.

Authentication: Bearer token and context headers
Permissions: Your role's access to the resource

Detailed schema in preparation

The route is part of the service today. Its request and response schema will be published here; until then, use the OpenAPI document on your environment.