Mobile
- GET/approvals
- POST/approvals
- GET/service_catalog
- POST/service_catalog
- GET/workflow_tasks
- POST/workflow_tasks
- GET/ticket_attachments
- POST/ticket_attachments
Approvals the caller may decide right now (service catalog requests + workflow approval tasks)
Needs a user token (API keys denied) and Tickets (catalog) and/or Departments (workflow) access. Same rules as agent/service_catalog_approvals.php and the workflow run page; administrators also see every other pending catalog request (decided as an override). Module-only (limited) logins get 403.
Example request
curl "https://YOUR-HOST/api/v1/approvals" \
-H "Authorization: Bearer $TOKEN"
import requests
response = requests.get(
"https://YOUR-HOST/api/v1/approvals",
headers={"Authorization": f"Bearer {TOKEN}"},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/approvals", {
method: "GET",
headers: { "Authorization": `Bearer ${TOKEN}` },
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/approvals");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$data = json_decode(curl_exec($ch), true);
Responses
200Pending approvals, oldest first
| Field | Type | Description |
|---|---|---|
| items | array of object | |
| items[].kind | string (catalog_request | workflow_task) | |
| items[].id | integer | request_id (catalog_request) or run_task_id (workflow_task) |
| items[].title | string | |
| items[].requester | string | |
| items[].summary | string | |
| items[].risk_score | integer | |
| items[].step | string | |
| items[].ticket_id | integer | |
| items[].requested_at | string | |
| items[].due_at | string | |
| items[].fields | array of object | |
| items[].fields[].label | string | |
| items[].fields[].value | string | |
| counts | object | |
| counts.total | integer |
Example response
{
"items": [
{
"kind": "catalog_request",
"id": 1,
"title": "string",
"requester": "string",
"summary": "string",
"risk_score": 1,
"step": "string",
"ticket_id": 1,
"requested_at": "2026-10-06 09:00:00",
"due_at": "string",
"fields": [
null
]
}
],
"counts": {
"total": 1
}
}
401Missing or invalid credentials
| Field | Type | Description |
|---|---|---|
| error | string |
403Authenticated but not permitted
| Field | Type | Description |
|---|---|---|
| error | string |
Approve or reject one approval
Goes through ServiceCatalogService::decide / WorkflowService::approveTask|rejectTask, so state machine, notifications, audit and ticket hold/release behave as on the web. An id that does not exist, is already decided, or is not addressed to the caller returns the same 404.
Request body (application/json, required)
| Field | Type | Description |
|---|---|---|
| kindrequired | string (catalog_request | workflow_task) | |
| idrequired | integer | |
| decisionrequired | string (approve | reject) | |
| comment | string | Required for reject; up to 2000 characters |
Example request
curl -X POST "https://YOUR-HOST/api/v1/approvals" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"kind":"catalog_request","id":1,"decision":"approve","comment":"string"}'
import requests
response = requests.post(
"https://YOUR-HOST/api/v1/approvals",
headers={"Authorization": f"Bearer {TOKEN}"},
json={
"kind": "catalog_request",
"id": 1,
"decision": "approve",
"comment": "string"
},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/approvals", {
method: "POST",
headers: { "Authorization": `Bearer ${TOKEN}`, "Content-Type": "application/json" },
body: JSON.stringify({
"kind": "catalog_request",
"id": 1,
"decision": "approve",
"comment": "string"
}),
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/approvals");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => ["Authorization: Bearer $token", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => '{"kind":"catalog_request","id":1,"decision":"approve","comment":"string"}',
]);
$data = json_decode(curl_exec($ch), true);
Responses
200Decision recorded
| Field | Type | Description |
|---|---|---|
| ok | boolean | |
| status | string | approved, rejected, or pending_approval (a further catalog step is now waiting) |
Example response
{
"ok": true,
"status": "string"
}
401Missing or invalid credentials
| Field | Type | Description |
|---|---|---|
| error | string |
403Authenticated but not permitted
| Field | Type | Description |
|---|---|---|
| error | string |
404Resource not found
| Field | Type | Description |
|---|---|---|
| error | string |
409Lost a race - the approval was decided in the meantime
422Validation error (bad kind/id/decision, or a reject without a comment)
Active service catalog items with their request forms
Needs a user token and Tickets access. popular = top 5 items of the last 30 days; recent = the caller's last 5 distinct items.
Example request
curl "https://YOUR-HOST/api/v1/service_catalog" \
-H "Authorization: Bearer $TOKEN"
import requests
response = requests.get(
"https://YOUR-HOST/api/v1/service_catalog",
headers={"Authorization": f"Bearer {TOKEN}"},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/service_catalog", {
method: "GET",
headers: { "Authorization": `Bearer ${TOKEN}` },
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/service_catalog");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$data = json_decode(curl_exec($ch), true);
Responses
200Catalog
| Field | Type | Description |
|---|---|---|
| items | array of object | |
| items[].id | integer | |
| items[].name | string | |
| items[].description | string | |
| items[].icon | string | |
| items[].requires_approval | boolean | |
| items[].risk_score | integer | |
| items[].fields | array of object | |
| items[].fields[].key | string | |
| items[].fields[].label | string | |
| items[].fields[].type | string (text | textarea | select | checkbox | date | number) | |
| items[].fields[].options | array of string | |
| items[].fields[].required | boolean | |
| items[].fields[].placeholder | string | |
| items[].fields[].show_if | object | Show this field only when an earlier field matches: {field, op: equals|in|not_empty, value}. A hidden field is never required and its answer is ignored. null = always visible. |
| popular | array of integer | |
| recent | array of integer |
Example response
{
"items": [
{
"id": 1,
"name": "string",
"description": "string",
"icon": "string",
"requires_approval": true,
"risk_score": 1,
"fields": [
null
]
}
],
"popular": [
1
],
"recent": [
1
]
}
401Missing or invalid credentials
| Field | Type | Description |
|---|---|---|
| error | string |
403Authenticated but not permitted
| Field | Type | Description |
|---|---|---|
| error | string |
Raise a ticket from a catalog item
Validated exactly like the web form (required, type, select choices, 500/5000 length caps); answers whose key is not a defined field are ignored. The caller is the requester. Needs Tickets edit access and access to client_id's department.
Request body (application/json, required)
| Field | Type | Description |
|---|---|---|
| catalog_item_idrequired | integer | |
| answers | object | field key to value; booleans and numbers are accepted for checkbox/number fields |
| client_id | integer |
Example request
curl -X POST "https://YOUR-HOST/api/v1/service_catalog" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"catalog_item_id":1,"answers":{},"client_id":1}'
import requests
response = requests.post(
"https://YOUR-HOST/api/v1/service_catalog",
headers={"Authorization": f"Bearer {TOKEN}"},
json={
"catalog_item_id": 1,
"answers": {},
"client_id": 1
},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/service_catalog", {
method: "POST",
headers: { "Authorization": `Bearer ${TOKEN}`, "Content-Type": "application/json" },
body: JSON.stringify({
"catalog_item_id": 1,
"answers": {},
"client_id": 1
}),
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/service_catalog");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => ["Authorization: Bearer $token", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => '{"catalog_item_id":1,"answers":{},"client_id":1}',
]);
$data = json_decode(curl_exec($ch), true);
Responses
201Ticket created (held when the item needs approval)
| Field | Type | Description |
|---|---|---|
| ok | boolean | |
| ticket_id | integer | |
| status | string (created | pending_approval) |
Example response
{
"ok": true,
"ticket_id": 1,
"status": "created"
}
401Missing or invalid credentials
| Field | Type | Description |
|---|---|---|
| error | string |
403Authenticated but not permitted
| Field | Type | Description |
|---|---|---|
| error | string |
404Resource not found
| Field | Type | Description |
|---|---|---|
| error | string |
422Validation error; error holds the messages joined, errors the list
Open onboarding/offboarding checklist tasks
scope=mine (default): assigned to the caller plus unassigned tasks of runs the caller may access (Departments view + department access). scope=all: every open task of accessible runs, needs Departments edit access. status can also be running or rejected besides the listed values.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| scope | query | string (mine | all) |
Example request
curl "https://YOUR-HOST/api/v1/workflow_tasks" \
-H "Authorization: Bearer $TOKEN"
import requests
response = requests.get(
"https://YOUR-HOST/api/v1/workflow_tasks",
headers={"Authorization": f"Bearer {TOKEN}"},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/workflow_tasks", {
method: "GET",
headers: { "Authorization": `Bearer ${TOKEN}` },
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/workflow_tasks");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$data = json_decode(curl_exec($ch), true);
Responses
200Tasks, soonest due first
| Field | Type | Description |
|---|---|---|
| items | array of object | |
| items[].id | integer | |
| items[].run_id | integer | |
| items[].run_title | string | |
| items[].task_title | string | |
| items[].instructions | string | |
| items[].due_at | string | |
| items[].status | string (pending | blocked | running | action_failed | rejected) | |
| items[].type | string (manual | approval | action) | |
| items[].blocked_by | array of string | |
| items[].contact_name | string | |
| items[].assignee | string | |
| counts | object | |
| counts.open | integer | |
| counts.overdue | integer |
Example response
{
"items": [
{
"id": 1,
"run_id": 1,
"run_title": "string",
"task_title": "string",
"instructions": "string",
"due_at": "string",
"status": "pending",
"type": "manual",
"blocked_by": [
null
],
"contact_name": "string",
"assignee": "string"
}
],
"counts": {
"open": 1,
"overdue": 1
}
}
401Missing or invalid credentials
| Field | Type | Description |
|---|---|---|
| error | string |
403Authenticated but not permitted
| Field | Type | Description |
|---|---|---|
| error | string |
422Unknown scope
Complete or skip a checklist task
Same rules as the web handlers (WorkflowService): blocked tasks and approval tasks cannot be completed by hand, skipping needs a reason, only administrators may skip an approval. Unknown and inaccessible tasks return the same 404.
Request body (application/json, required)
| Field | Type | Description |
|---|---|---|
| idrequired | integer | |
| actionrequired | string (complete | skip) | |
| reason | string | Required for skip; up to 500 characters |
Example request
curl -X POST "https://YOUR-HOST/api/v1/workflow_tasks" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"id":1,"action":"complete","reason":"string"}'
import requests
response = requests.post(
"https://YOUR-HOST/api/v1/workflow_tasks",
headers={"Authorization": f"Bearer {TOKEN}"},
json={
"id": 1,
"action": "complete",
"reason": "string"
},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/workflow_tasks", {
method: "POST",
headers: { "Authorization": `Bearer ${TOKEN}`, "Content-Type": "application/json" },
body: JSON.stringify({
"id": 1,
"action": "complete",
"reason": "string"
}),
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/workflow_tasks");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => ["Authorization: Bearer $token", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => '{"id":1,"action":"complete","reason":"string"}',
]);
$data = json_decode(curl_exec($ch), true);
Responses
200Done; status is the task's new status
| Field | Type | Description |
|---|---|---|
| ok | boolean | |
| status | string |
Example response
{
"ok": true,
"status": "string"
}
401Missing or invalid credentials
| Field | Type | Description |
|---|---|---|
| error | string |
403Authenticated but not permitted
| Field | Type | Description |
|---|---|---|
| error | string |
404Resource not found
| Field | Type | Description |
|---|---|---|
| error | string |
422Validation error or a workflow rule (blocked, needs approval, reason required, admin only)
List a ticket's attachments, or download one
ticket_id=N lists. id=A&download=1 streams the file (Content-Disposition: attachment, nosniff, Cache-Control: no-store); id=A without download returns that one item's metadata. 403 for a ticket outside the caller's departments and for an unknown id (indistinguishable). Needs Tickets access.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| ticket_id | query | integer | |
| id | query | integer | |
| download | query | integer (1) |
Example request
curl "https://YOUR-HOST/api/v1/ticket_attachments" \
-H "Authorization: Bearer $TOKEN"
import requests
response = requests.get(
"https://YOUR-HOST/api/v1/ticket_attachments",
headers={"Authorization": f"Bearer {TOKEN}"},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/ticket_attachments", {
method: "GET",
headers: { "Authorization": `Bearer ${TOKEN}` },
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/ticket_attachments");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$data = json_decode(curl_exec($ch), true);
Responses
200Attachment list, or the file bytes when download=1
| Field | Type | Description |
|---|---|---|
| items | array of object | |
| items[].id | integer | |
| items[].name | string | |
| items[].size | integer | |
| items[].mime | string | |
| items[].created_at | string | |
| items[].uploaded_by | string |
Example response
{
"items": [
{
"id": 1,
"name": "string",
"size": 1,
"mime": "string",
"created_at": "string",
"uploaded_by": "string"
}
]
}
401Missing or invalid credentials
| Field | Type | Description |
|---|---|---|
| error | string |
403Authenticated but not permitted
| Field | Type | Description |
|---|---|---|
| error | string |
404The file behind a known attachment is missing
Upload one attachment (multipart)
Fields ticket_id, optional reply_id (must belong to the ticket) and file. Same extension allow-list as the web upload, plus content sniffing (an image extension must hold an image; script/markup content is refused), a check of every extension segment (shell.php.png is refused), a random stored name and the PHP/post size limits.
Request body (multipart/form-data, required)
| Field | Type | Description |
|---|---|---|
| ticket_idrequired | integer | |
| reply_id | integer | |
| filerequired | string (binary) |
Example request
curl -X POST "https://YOUR-HOST/api/v1/ticket_attachments" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"ticket_id":1,"reply_id":1,"file":"string"}'
import requests
response = requests.post(
"https://YOUR-HOST/api/v1/ticket_attachments",
headers={"Authorization": f"Bearer {TOKEN}"},
json={
"ticket_id": 1,
"reply_id": 1,
"file": "string"
},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/ticket_attachments", {
method: "POST",
headers: { "Authorization": `Bearer ${TOKEN}`, "Content-Type": "application/json" },
body: JSON.stringify({
"ticket_id": 1,
"reply_id": 1,
"file": "string"
}),
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/ticket_attachments");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => ["Authorization: Bearer $token", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => '{"ticket_id":1,"reply_id":1,"file":"string"}',
]);
$data = json_decode(curl_exec($ch), true);
Responses
201Stored
| Field | Type | Description |
|---|---|---|
| ok | boolean | |
| id | integer |
Example response
{
"ok": true,
"id": 1
}
401Missing or invalid credentials
| Field | Type | Description |
|---|---|---|
| error | string |
403Authenticated but not permitted
| Field | Type | Description |
|---|---|---|
| error | string |
413File too large
422Missing field, disallowed type or content