REST API — Interactive Reference¶

The contract below is generated from the TypeSpec source in contracts/. To regenerate after changing the spec:

mise run contracts:build    # .tsp → openapi.yaml
mise run ui:generate-types  # openapi.yaml → ui/src/api/types.ts

wrkflw Document Approval API 0.1.0¶

REST contract for the document-approval workflow engine. Actor identity and group memberships are supplied via trusted headers (X-Actor-Id, X-Actor-Groups). All command responses reflect the authoritative DB state committed before the corresponding Temporal signal is sent.

Servers¶

Description	URL
Document Approval REST API	/api/v1

Endpoints¶

GET /flows¶

Description List flows submitted by the caller (submitter My Submissions view)

Response 200 OK¶

application/json

[
    {
        "flowId": "835fb55a-23dc-4315-ba86-f3c617670f25",
        "definitionKey": "string",
        "currentState": "string",
        "status": "RUNNING",
        "terminalOutcome": "string",
        "documentRef": "string",
        "submitterId": "string",
        "updatedAt": "2022-04-13T15:42:05.901Z"
    }
]

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "array",
    "items": {
        "$ref": "#/components/schemas/FlowSummary"
    }
}

POST /flows¶

Description Submit a document for approval — only initiator-group members may start (FR-002)

Request body

application/json

{
    "definitionKey": "string",
    "documentRef": "string"
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "type": "object",
    "required": [
        "definitionKey",
        "documentRef"
    ],
    "properties": {
        "definitionKey": {
            "type": "string"
        },
        "documentRef": {
            "type": "string",
            "description": "Reference/identifier of the document"
        }
    }
}

Response 201 Created¶

application/json

{
    "flowId": "3c650bc5-1767-42b3-9ba3-cca43614d3ac",
    "definitionKey": "string",
    "currentState": "string",
    "status": "RUNNING",
    "terminalOutcome": "string",
    "pendingTasks": [
        {
            "taskId": "078adf5d-a121-4c08-9ffc-2cbb602e6e81",
            "flowId": "3e6f71b2-ee29-4997-adee-43e6e4149a45",
            "stateName": "string",
            "candidateGroupId": "string",
            "status": "PENDING",
            "ownerId": "string"
        }
    ]
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "object",
    "required": [
        "flowId",
        "definitionKey",
        "currentState",
        "status",
        "terminalOutcome",
        "pendingTasks"
    ],
    "properties": {
        "flowId": {
            "type": "string",
            "format": "uuid"
        },
        "definitionKey": {
            "type": "string"
        },
        "currentState": {
            "type": "string"
        },
        "status": {
            "$ref": "#/components/schemas/FlowRunStatus"
        },
        "terminalOutcome": {
            "type": "string",
            "nullable": true
        },
        "pendingTasks": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/TaskSummary"
            }
        }
    }
}

Response 403 Forbidden¶

Response 404 Not Found¶

Response 422 Unprocessable Entity¶

GET /flows/{flowId}¶

Description Get flow status, pending tasks, responsible groups, and audit history

Input parameters

Parameter	In	Type	Default	Nullable	Description
flowId	path	string		No

Response 200 OK¶

application/json

{
    "history": [
        {
            "type": "string",
            "actorId": "string",
            "occurredAt": "2022-04-13T15:42:05.901Z",
            "detail": {}
        }
    ]
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "object",
    "required": [
        "history"
    ],
    "properties": {
        "history": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/AuditEntry"
            }
        }
    },
    "allOf": [
        {
            "$ref": "#/components/schemas/FlowStatus"
        }
    ]
}

Response 404 Not Found¶

POST /tasks/{taskId}/claim¶

Description Claim a pending task — caller must be in the candidate group and task must be PENDING (FR-008)

Input parameters

Parameter	In	Type	Default	Nullable	Description
taskId	path	string		No

Response 200 OK¶

application/json

{
    "taskId": "af2290f4-318b-4cb3-bbd0-5ec4f4ae00a6",
    "flowId": "e36c3f44-b8f3-44b2-8555-90c79a1a3f25",
    "stateName": "string",
    "candidateGroupId": "string",
    "status": "PENDING",
    "ownerId": "string"
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "object",
    "required": [
        "taskId",
        "flowId",
        "stateName",
        "candidateGroupId",
        "status"
    ],
    "properties": {
        "taskId": {
            "type": "string",
            "format": "uuid"
        },
        "flowId": {
            "type": "string",
            "format": "uuid"
        },
        "stateName": {
            "type": "string"
        },
        "candidateGroupId": {
            "type": "string"
        },
        "status": {
            "$ref": "#/components/schemas/TaskRunStatus"
        },
        "ownerId": {
            "type": "string",
            "nullable": true
        }
    }
}

Response 403 Forbidden¶

Response 404 Not Found¶

Response 409 Conflict¶

POST /tasks/{taskId}/decision¶

Description Record an approve/reject decision on an owned task (FR-011, FR-012)

Input parameters

Parameter	In	Type	Default	Nullable	Description
taskId	path	string		No

Request body

application/json

{
    "outcome": "APPROVE",
    "comment": "string"
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "type": "object",
    "required": [
        "outcome"
    ],
    "properties": {
        "outcome": {
            "$ref": "#/components/schemas/DecisionOutcome"
        },
        "comment": {
            "type": "string"
        }
    }
}

Response 200 OK¶

application/json

{
    "flowId": "ce2448a0-45c7-41e0-a816-fdc65a2248ee",
    "definitionKey": "string",
    "currentState": "string",
    "status": "RUNNING",
    "terminalOutcome": "string",
    "pendingTasks": [
        {
            "taskId": "4245d4a6-a29c-4dcd-a539-68d49b91bbf2",
            "flowId": "8a5a5988-9394-49dd-a0dd-22e2a4e21862",
            "stateName": "string",
            "candidateGroupId": "string",
            "status": "PENDING",
            "ownerId": "string"
        }
    ]
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "object",
    "required": [
        "flowId",
        "definitionKey",
        "currentState",
        "status",
        "terminalOutcome",
        "pendingTasks"
    ],
    "properties": {
        "flowId": {
            "type": "string",
            "format": "uuid"
        },
        "definitionKey": {
            "type": "string"
        },
        "currentState": {
            "type": "string"
        },
        "status": {
            "$ref": "#/components/schemas/FlowRunStatus"
        },
        "terminalOutcome": {
            "type": "string",
            "nullable": true
        },
        "pendingTasks": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/TaskSummary"
            }
        }
    }
}

Response 403 Forbidden¶

Response 404 Not Found¶

Response 409 Conflict¶

Response 422 Unprocessable Entity¶

POST /tasks/{taskId}/release¶

Description Release a claimed task back to the group (FR-009)

Input parameters

Parameter	In	Type	Default	Nullable	Description
taskId	path	string		No

Response 200 OK¶

application/json

{
    "taskId": "efb075b6-18ac-4c49-a6f4-6d438a904f54",
    "flowId": "7d44da3d-cf04-48cf-b1cf-dcb6a4591015",
    "stateName": "string",
    "candidateGroupId": "string",
    "status": "PENDING",
    "ownerId": "string"
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "object",
    "required": [
        "taskId",
        "flowId",
        "stateName",
        "candidateGroupId",
        "status"
    ],
    "properties": {
        "taskId": {
            "type": "string",
            "format": "uuid"
        },
        "flowId": {
            "type": "string",
            "format": "uuid"
        },
        "stateName": {
            "type": "string"
        },
        "candidateGroupId": {
            "type": "string"
        },
        "status": {
            "$ref": "#/components/schemas/TaskRunStatus"
        },
        "ownerId": {
            "type": "string",
            "nullable": true
        }
    }
}

Response 403 Forbidden¶

Response 404 Not Found¶

Response 409 Conflict¶

GET /worklists/group¶

Description Unclaimed tasks actionable by the caller's group(s) (FR-016)

Response 200 OK¶

application/json

[
    {
        "taskId": "dca5332d-5d8c-411e-aabc-72b07bbd8f95",
        "flowId": "9f401df6-3768-42a6-9df8-3c936d58a05d",
        "stateName": "string",
        "candidateGroupId": "string",
        "status": "PENDING",
        "ownerId": "string"
    }
]

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "array",
    "items": {
        "$ref": "#/components/schemas/TaskSummary"
    }
}

GET /worklists/mine¶

Description Tasks the caller personally owns (FR-017)

Response 200 OK¶

application/json

[
    {
        "taskId": "9ceb080c-0e37-47d8-8120-c9323d2d3597",
        "flowId": "e5b17389-1d7b-455d-bf54-6d625fd796cd",
        "stateName": "string",
        "candidateGroupId": "string",
        "status": "PENDING",
        "ownerId": "string"
    }
]

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "array",
    "items": {
        "$ref": "#/components/schemas/TaskSummary"
    }
}

Schemas¶

AuditEntry¶

Name	Type	Description
actorId	string \| null
detail
occurredAt	string(date-time)
type	string

DecisionOutcome¶

Type: string

DecisionRequest¶

Name	Type	Description
comment	string
outcome	DecisionOutcome

FlowRunStatus¶

Type: string

FlowStatus¶

Name	Type	Description
currentState	string
definitionKey	string
flowId	string(uuid)
pendingTasks	Array<TaskSummary>
status	FlowRunStatus
terminalOutcome	string \| null

FlowStatusWithHistory¶

Name	Type	Description
history	Array<AuditEntry>

FlowSummary¶

Name	Type	Description
currentState	string
definitionKey	string
documentRef	string
flowId	string(uuid)
status	FlowRunStatus
submitterId	string
terminalOutcome	string \| null
updatedAt	string(date-time)

SubmitDocumentRequest¶

Name	Type	Description
definitionKey	string
documentRef	string	Reference/identifier of the document

TaskRunStatus¶

Type: string

TaskSummary¶

Name	Type	Description
candidateGroupId	string
flowId	string(uuid)
ownerId	string \| null
stateName	string
status	TaskRunStatus
taskId	string(uuid)