Skip to content

API reference / RivetIT

Mobile

GET /approvals Bearer token or API key

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

FieldTypeDescription
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
json
{
    "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

FieldTypeDescription
error string

403Authenticated but not permitted

FieldTypeDescription
error string
POST /approvals Bearer token or API key

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)

FieldTypeDescription
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

FieldTypeDescription
ok boolean
status string approved, rejected, or pending_approval (a further catalog step is now waiting)
Example response
json
{
    "ok": true,
    "status": "string"
}

401Missing or invalid credentials

FieldTypeDescription
error string

403Authenticated but not permitted

FieldTypeDescription
error string

404Resource not found

FieldTypeDescription
error string

409Lost a race - the approval was decided in the meantime

422Validation error (bad kind/id/decision, or a reject without a comment)

GET /service_catalog Bearer token or API key

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

FieldTypeDescription
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
json
{
    "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

FieldTypeDescription
error string

403Authenticated but not permitted

FieldTypeDescription
error string
POST /service_catalog Bearer token or API key

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)

FieldTypeDescription
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)

FieldTypeDescription
ok boolean
ticket_id integer
status string (created | pending_approval)
Example response
json
{
    "ok": true,
    "ticket_id": 1,
    "status": "created"
}

401Missing or invalid credentials

FieldTypeDescription
error string

403Authenticated but not permitted

FieldTypeDescription
error string

404Resource not found

FieldTypeDescription
error string

422Validation error; error holds the messages joined, errors the list

GET /workflow_tasks Bearer token or API key

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

NameInTypeDescription
scopequerystring (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

FieldTypeDescription
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
json
{
    "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

FieldTypeDescription
error string

403Authenticated but not permitted

FieldTypeDescription
error string

422Unknown scope

POST /workflow_tasks Bearer token or API key

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)

FieldTypeDescription
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

FieldTypeDescription
ok boolean
status string
Example response
json
{
    "ok": true,
    "status": "string"
}

401Missing or invalid credentials

FieldTypeDescription
error string

403Authenticated but not permitted

FieldTypeDescription
error string

404Resource not found

FieldTypeDescription
error string

422Validation error or a workflow rule (blocked, needs approval, reason required, admin only)

GET /ticket_attachments Bearer token or API key

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

NameInTypeDescription
ticket_idqueryinteger
idqueryinteger
downloadqueryinteger (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

FieldTypeDescription
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
json
{
    "items": [
        {
            "id": 1,
            "name": "string",
            "size": 1,
            "mime": "string",
            "created_at": "string",
            "uploaded_by": "string"
        }
    ]
}

401Missing or invalid credentials

FieldTypeDescription
error string

403Authenticated but not permitted

FieldTypeDescription
error string

404The file behind a known attachment is missing

POST /ticket_attachments Bearer token or API key

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)

FieldTypeDescription
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

FieldTypeDescription
ok boolean
id integer
Example response
json
{
    "ok": true,
    "id": 1
}

401Missing or invalid credentials

FieldTypeDescription
error string

403Authenticated but not permitted

FieldTypeDescription
error string

413File too large

422Missing field, disallowed type or content