Skip to content

API reference / RivetIT

Tickets

GET /tickets Bearer token or API key

List tickets (paged, filterable)

Parameters

NameInTypeDescription
statusquerystring (open | closed | all)
minequeryinteger (0 | 1)
searchquerystring
pagequeryinteger
limitqueryinteger
priorityquerystringOne or more of low, medium, high (comma-separated or repeated: high,medium)
assignedquerystringComma-separated: me, unassigned, and/or agent ids (me,7)
boardquerystringBoard (top-level category) ids, comma-separated
onsitequerystring1 on-site, 0 remote, or both (0,1 = no filter)
category_idquerystringCategory ids, comma-separated
client_idqueryinteger
contact_idqueryinteger
overduequeryinteger
due_todayqueryinteger

Example request

curl "https://YOUR-HOST/api/v1/tickets" \
  -H "Authorization: Bearer $TOKEN"
import requests

response = requests.get(
    "https://YOUR-HOST/api/v1/tickets",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/tickets", {
  method: "GET",
  headers: { "Authorization": `Bearer ${TOKEN}` },
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/tickets");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$data = json_decode(curl_exec($ch), true);

Responses

200Paged ticket list

FieldTypeDescription
data array of object
data[].id integer
data[].number integer
data[].subject string
data[].priority string
data[].status string
data[].status_color string
data[].client string
data[].assigned_to string
data[].created_at string
data[].due_at string
data[].resolved_at string
data[].updated_at string
total integer
page integer
limit integer
Example response
json
{
    "data": [
        {
            "id": 1,
            "number": 1,
            "subject": "string",
            "priority": "string",
            "status": "string",
            "status_color": "string",
            "client": "string",
            "assigned_to": "string",
            "created_at": "string",
            "due_at": "string",
            "resolved_at": "string",
            "updated_at": "string"
        }
    ],
    "total": 1,
    "page": 1,
    "limit": 1
}

401Missing or invalid credentials

FieldTypeDescription
error string
POST /tickets Bearer token or API key

Create a ticket (JSON or multipart with files)

Request body (application/json, required)

FieldTypeDescription
subjectrequired string
details string
client_id integer
contact_id integer
assigned_to integer
category_id integer
priority string (low | medium | high | critical)
hostname string

Example request

curl -X POST "https://YOUR-HOST/api/v1/tickets" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"subject":"string","details":"string","client_id":1,"contact_id":1,"assigned_to":1,"category_id":1,"priority":"low","hostname":"string"}'
import requests

response = requests.post(
    "https://YOUR-HOST/api/v1/tickets",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={
        "subject": "string",
        "details": "string",
        "client_id": 1,
        "contact_id": 1,
        "assigned_to": 1,
        "category_id": 1,
        "priority": "low",
        "hostname": "string"
    },
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/tickets", {
  method: "POST",
  headers: { "Authorization": `Bearer ${TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({
      "subject": "string",
      "details": "string",
      "client_id": 1,
      "contact_id": 1,
      "assigned_to": 1,
      "category_id": 1,
      "priority": "low",
      "hostname": "string"
  }),
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/tickets");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => '{"subject":"string","details":"string","client_id":1,"contact_id":1,"assigned_to":1,"category_id":1,"priority":"low","hostname":"string"}',
]);
$data = json_decode(curl_exec($ch), true);

Responses

201Ticket created

FieldTypeDescription
id integer
number integer
attachments array of object
attachments[].name string
attachments[].filename string
attachments[].url string
Example response
json
{
    "id": 1,
    "number": 1,
    "attachments": [
        {
            "name": "string",
            "filename": "string",
            "url": "string"
        }
    ]
}

400Bad request

FieldTypeDescription
error string

401Missing or invalid credentials

FieldTypeDescription
error string
GET /tickets/{id} Bearer token or API key

Ticket detail with replies and attachments

Parameters

NameInTypeDescription
idrequiredpathinteger

Example request

curl "https://YOUR-HOST/api/v1/tickets/1" \
  -H "Authorization: Bearer $TOKEN"
import requests

response = requests.get(
    "https://YOUR-HOST/api/v1/tickets/1",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/tickets/1", {
  method: "GET",
  headers: { "Authorization": `Bearer ${TOKEN}` },
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/tickets/1");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$data = json_decode(curl_exec($ch), true);

Responses

200Ticket detail

FieldTypeDescription
id integer
attachments_count integer All attachments of the ticket including those on replies
number integer
subject string
details string
priority string
status string
status_color string
client string
assigned_to string
contact_name string
contact_email string
contact_phone string
billable boolean
created_at string
due_at string
resolved_at string
attachments array of object
attachments[].name string
attachments[].filename string
attachments[].url string
replies array of object
replies[].id integer
replies[].body string
replies[].type string
replies[].time_worked string
replies[].onsite boolean
replies[].by string
replies[].created_at string
replies[].attachments array of object
replies[].attachments[].name string
replies[].attachments[].filename string
replies[].attachments[].url string
Example response
json
{
    "id": 1,
    "attachments_count": 1,
    "number": 1,
    "subject": "string",
    "details": "string",
    "priority": "string",
    "status": "string",
    "status_color": "string",
    "client": "string",
    "assigned_to": "string",
    "contact_name": "string",
    "contact_email": "string",
    "contact_phone": "string",
    "billable": true,
    "created_at": "string",
    "due_at": "string",
    "resolved_at": "string",
    "attachments": [
        {
            "name": "string",
            "filename": "string",
            "url": "string"
        }
    ],
    "replies": [
        {
            "id": 1,
            "body": "string",
            "type": "string",
            "time_worked": "string",
            "onsite": true,
            "by": "string",
            "created_at": "string",
            "attachments": [
                null
            ]
        }
    ]
}

403Authenticated but not permitted

FieldTypeDescription
error string

404Resource not found

FieldTypeDescription
error string
POST /tickets/{id}/reply Bearer token or API key

Add a reply or internal note (JSON or multipart with files)

Parameters

NameInTypeDescription
idrequiredpathinteger

Request body (application/json, required)

FieldTypeDescription
replyrequired string
type string reply | note | client (customer/portal/website)
time_worked string HH:MM:SS
onsite integer (0 | 1)
contact_id integer

Example request

curl -X POST "https://YOUR-HOST/api/v1/tickets/1/reply" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reply":"string","type":"string","time_worked":"string","onsite":0,"contact_id":1}'
import requests

response = requests.post(
    "https://YOUR-HOST/api/v1/tickets/1/reply",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={
        "reply": "string",
        "type": "string",
        "time_worked": "string",
        "onsite": 0,
        "contact_id": 1
    },
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/tickets/1/reply", {
  method: "POST",
  headers: { "Authorization": `Bearer ${TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({
      "reply": "string",
      "type": "string",
      "time_worked": "string",
      "onsite": 0,
      "contact_id": 1
  }),
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/tickets/1/reply");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => '{"reply":"string","type":"string","time_worked":"string","onsite":0,"contact_id":1}',
]);
$data = json_decode(curl_exec($ch), true);

Responses

201Reply created

FieldTypeDescription
id integer
type string
ticket_status object
ticket_status.id integer
ticket_status.name string
attachments array of object
attachments[].name string
attachments[].filename string
attachments[].url string
Example response
json
{
    "id": 1,
    "type": "string",
    "ticket_status": {
        "id": 1,
        "name": "string"
    },
    "attachments": [
        {
            "name": "string",
            "filename": "string",
            "url": "string"
        }
    ]
}

400Bad request

FieldTypeDescription
error string

404Resource not found

FieldTypeDescription
error string
DELETE /tickets/{id}/reply/{replyId} Bearer token or API key

Delete a reply (and its attachments)

Parameters

NameInTypeDescription
idrequiredpathinteger
replyIdrequiredpathinteger

Example request

curl -X DELETE "https://YOUR-HOST/api/v1/tickets/1/reply/1" \
  -H "Authorization: Bearer $TOKEN"
import requests

response = requests.delete(
    "https://YOUR-HOST/api/v1/tickets/1/reply/1",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/tickets/1/reply/1", {
  method: "DELETE",
  headers: { "Authorization": `Bearer ${TOKEN}` },
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/tickets/1/reply/1");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "DELETE",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$data = json_decode(curl_exec($ch), true);

Responses

200Success

FieldTypeDescription
ok boolean
Example response
json
{
    "ok": true
}

400Bad request

FieldTypeDescription
error string

404Resource not found

FieldTypeDescription
error string
POST /tickets/{id}/time Bearer token or API key

Log time against a ticket (creates an internal reply)

Parameters

NameInTypeDescription
idrequiredpathinteger

Request body (application/json, required)

FieldTypeDescription
time_workedrequired string HH:MM:SS
note string

Example request

curl -X POST "https://YOUR-HOST/api/v1/tickets/1/time" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"time_worked":"01:30:00","note":"string"}'
import requests

response = requests.post(
    "https://YOUR-HOST/api/v1/tickets/1/time",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={
        "time_worked": "01:30:00",
        "note": "string"
    },
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/tickets/1/time", {
  method: "POST",
  headers: { "Authorization": `Bearer ${TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({
      "time_worked": "01:30:00",
      "note": "string"
  }),
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/tickets/1/time");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => '{"time_worked":"01:30:00","note":"string"}',
]);
$data = json_decode(curl_exec($ch), true);

Responses

201Success

FieldTypeDescription
ok boolean
Example response
json
{
    "ok": true
}

400Bad request

FieldTypeDescription
error string
POST /tickets/{id}/status Bearer token or API key

Change ticket status (setting a Closed status resolves it)

Parameters

NameInTypeDescription
idrequiredpathinteger

Request body (application/json, required)

FieldTypeDescription
status_idrequired integer

Example request

curl -X POST "https://YOUR-HOST/api/v1/tickets/1/status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status_id":1}'
import requests

response = requests.post(
    "https://YOUR-HOST/api/v1/tickets/1/status",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={
        "status_id": 1
    },
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/tickets/1/status", {
  method: "POST",
  headers: { "Authorization": `Bearer ${TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({
      "status_id": 1
  }),
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/tickets/1/status");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => '{"status_id":1}',
]);
$data = json_decode(curl_exec($ch), true);

Responses

200Success

FieldTypeDescription
ok boolean
Example response
json
{
    "ok": true
}

400Bad request

FieldTypeDescription
error string
POST /tickets/{id}/attachments Bearer token or API key

Upload one or more attachments to a ticket

Parameters

NameInTypeDescription
idrequiredpathinteger

Request body (multipart/form-data, required)

FieldTypeDescription
file string (binary)
files[] array of string (binary)

Example request

curl -X POST "https://YOUR-HOST/api/v1/tickets/1/attachments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"file":"string","files[]":["string"]}'
import requests

response = requests.post(
    "https://YOUR-HOST/api/v1/tickets/1/attachments",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={
        "file": "string",
        "files[]": [
            "string"
        ]
    },
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/tickets/1/attachments", {
  method: "POST",
  headers: { "Authorization": `Bearer ${TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({
      "file": "string",
      "files[]": [
          "string"
      ]
  }),
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/tickets/1/attachments");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => '{"file":"string","files[]":["string"]}',
]);
$data = json_decode(curl_exec($ch), true);

Responses

201Attachment(s) saved

FieldTypeDescription
name string
filename string
url string
Example response
json
{
    "name": "string",
    "filename": "string",
    "url": "string"
}

400Bad request

FieldTypeDescription
error string
GET /tickets/{id}/chat Bearer token or API key

Live-chat messages for a ticket (add ?stream=1 for an SSE feed)

Parameters

NameInTypeDescription
idrequiredpathinteger
since_idqueryinteger
streamqueryintegerWhen present, responds with a text/event-stream SSE feed instead of JSON

Example request

curl "https://YOUR-HOST/api/v1/tickets/1/chat" \
  -H "Authorization: Bearer $TOKEN"
import requests

response = requests.get(
    "https://YOUR-HOST/api/v1/tickets/1/chat",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/tickets/1/chat", {
  method: "GET",
  headers: { "Authorization": `Bearer ${TOKEN}` },
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/tickets/1/chat");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$data = json_decode(curl_exec($ch), true);

Responses

200Chat messages

FieldTypeDescription
data array of object
data[].id integer
data[].sender_type string (agent | contact)
data[].sender_id integer
data[].sender_name string
data[].message string
data[].created_at string
Example response
json
{
    "data": [
        {
            "id": 1,
            "sender_type": "agent",
            "sender_id": 1,
            "sender_name": "string",
            "message": "string",
            "created_at": "string"
        }
    ]
}

403Authenticated but not permitted

FieldTypeDescription
error string

404Resource not found

FieldTypeDescription
error string
POST /tickets/{id}/chat Bearer token or API key

Send a live-chat message

Parameters

NameInTypeDescription
idrequiredpathinteger

Request body (application/json, required)

FieldTypeDescription
messagerequired string
contact_id integer Post on behalf of one of the ticket's client's contacts

Example request

curl -X POST "https://YOUR-HOST/api/v1/tickets/1/chat" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"string","contact_id":1}'
import requests

response = requests.post(
    "https://YOUR-HOST/api/v1/tickets/1/chat",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={
        "message": "string",
        "contact_id": 1
    },
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/tickets/1/chat", {
  method: "POST",
  headers: { "Authorization": `Bearer ${TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({
      "message": "string",
      "contact_id": 1
  }),
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/tickets/1/chat");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => '{"message":"string","contact_id":1}',
]);
$data = json_decode(curl_exec($ch), true);

Responses

201Message stored

FieldTypeDescription
id integer
Example response
json
{
    "id": 1
}

400Bad request

FieldTypeDescription
error string

404Resource not found

FieldTypeDescription
error string
GET /tickets/{id}/charges Bearer token or API key

List charges on a ticket

Parameters

NameInTypeDescription
idrequiredpathinteger

Example request

curl "https://YOUR-HOST/api/v1/tickets/1/charges" \
  -H "Authorization: Bearer $TOKEN"
import requests

response = requests.get(
    "https://YOUR-HOST/api/v1/tickets/1/charges",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/tickets/1/charges", {
  method: "GET",
  headers: { "Authorization": `Bearer ${TOKEN}` },
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/tickets/1/charges");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$data = json_decode(curl_exec($ch), true);

Responses

200Charges plus running total

FieldTypeDescription
charges array of object
charges[].id integer
charges[].name string
charges[].description string
charges[].quantity number
charges[].unit_price number
charges[].total number
charges[].invoiced boolean
charges[].created_by string
charges[].created_at string
total number
Example response
json
{
    "charges": [
        {
            "id": 1,
            "name": "string",
            "description": "string",
            "quantity": 1.5,
            "unit_price": 1.5,
            "total": 1.5,
            "invoiced": true,
            "created_by": "string",
            "created_at": "string"
        }
    ],
    "total": 1.5
}

403Authenticated but not permitted

FieldTypeDescription
error string
POST /tickets/{id}/charges Bearer token or API key

Add a charge to a ticket

Parameters

NameInTypeDescription
idrequiredpathinteger

Request body (application/json, required)

FieldTypeDescription
namerequired string
description string
quantity number
unit_price number

Example request

curl -X POST "https://YOUR-HOST/api/v1/tickets/1/charges" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","description":"string","quantity":1.5,"unit_price":1.5}'
import requests

response = requests.post(
    "https://YOUR-HOST/api/v1/tickets/1/charges",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={
        "name": "string",
        "description": "string",
        "quantity": 1.5,
        "unit_price": 1.5
    },
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/tickets/1/charges", {
  method: "POST",
  headers: { "Authorization": `Bearer ${TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({
      "name": "string",
      "description": "string",
      "quantity": 1.5,
      "unit_price": 1.5
  }),
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/tickets/1/charges");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => '{"name":"string","description":"string","quantity":1.5,"unit_price":1.5}',
]);
$data = json_decode(curl_exec($ch), true);

Responses

201Charge created

FieldTypeDescription
id integer
total number
Example response
json
{
    "id": 1,
    "total": 1.5
}

400Bad request

FieldTypeDescription
error string