Skip to content

API reference / RivetIT

Contracts

GET /contracts Bearer token or API key

List contracts (paged, filterable). Billing-adjacent client data - requires module_client.

Parameters

NameInTypeDescription
searchquerystring
pagequeryinteger
limitqueryinteger
statusquerystringRaw contract_status value (e.g. Active, Expired, Cancelled) - manually set, not auto-derived from dates
client_idqueryinteger
expiringqueryinteger (0 | 1)Only contracts already past renewal_date or due within 45 days

Example request

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

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

Responses

200Paged contract list

FieldTypeDescription
data array of object
data[].id integer
data[].name string
data[].type string
data[].status string Raw contract_status value - manually set, may disagree with renewal_date; see is_expired/is_due_soon
data[].client string
data[].value number
data[].renewal_frequency string
data[].start_date string
data[].end_date string
data[].renewal_date string
data[].is_expired boolean
data[].is_due_soon boolean renewal_date is today or within the next 45 days
data[].has_sla boolean
data[].has_allowance boolean
total integer
page integer
limit integer
Example response
json
{
    "data": [
        {
            "id": 1,
            "name": "string",
            "type": "string",
            "status": "string",
            "client": "string",
            "value": 1.5,
            "renewal_frequency": "string",
            "start_date": "string",
            "end_date": "string",
            "renewal_date": "string",
            "is_expired": true,
            "is_due_soon": true,
            "has_sla": true,
            "has_allowance": true
        }
    ],
    "total": 1,
    "page": 1,
    "limit": 1
}
GET /contracts/{id} Bearer token or API key

Contract detail with SLA, current-month hours-allowance usage, and documents

Parameters

NameInTypeDescription
idrequiredpathinteger
monthqueryintegerAllowance month, 1-12, defaults to current month
yearqueryintegerAllowance year, defaults to current year

Example request

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

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

Responses

200Contract detail

FieldTypeDescription
id integer
name string
type string
status string
client string
value number
renewal_frequency string
start_date string
end_date string
renewal_date string
is_expired boolean
is_due_soon boolean
details string
sla object
sla.high object
sla.high.response_time integer Hours; null when not configured
sla.high.resolution_time integer Hours; null when not configured
sla.medium object
sla.medium.response_time integer Hours; null when not configured
sla.medium.resolution_time integer Hours; null when not configured
sla.low object
sla.low.response_time integer Hours; null when not configured
sla.low.resolution_time integer Hours; null when not configured
allowance object Same shape as the month/year/remote/onsite fields of AllowanceUsage, for this one contract
allowance.month integer
allowance.year integer
allowance.remote object Included vs. used hours for one delivery method (remote or onsite) over the requested month. When this allowance isn't configured (no active contract sets it), included/remaining/pct are null and used is 0 - treat null 'included' as "feature inactive" and don't render this period.
allowance.remote.included number Hours included, or null if this allowance is not configured
allowance.remote.used number Hours used so far this month (flat per-ticket rate, not actual worked time); 0 when included is null
allowance.remote.remaining number included - used; negative when over allowance; null when included is null
allowance.remote.pct number used / included as a percentage, capped at 100; null when included is null
allowance.onsite object Included vs. used hours for one delivery method (remote or onsite) over the requested month. When this allowance isn't configured (no active contract sets it), included/remaining/pct are null and used is 0 - treat null 'included' as "feature inactive" and don't render this period.
allowance.onsite.included number Hours included, or null if this allowance is not configured
allowance.onsite.used number Hours used so far this month (flat per-ticket rate, not actual worked time); 0 when included is null
allowance.onsite.remaining number included - used; negative when over allowance; null when included is null
allowance.onsite.pct number used / included as a percentage, capped at 100; null when included is null
documents array of object
documents[].id integer
documents[].name string
documents[].mime_type string
documents[].size integer
documents[].uploaded_at string
documents[].url string
created_at string
updated_at string
Example response
json
{
    "id": 1,
    "name": "string",
    "type": "string",
    "status": "string",
    "client": "string",
    "value": 1.5,
    "renewal_frequency": "string",
    "start_date": "string",
    "end_date": "string",
    "renewal_date": "string",
    "is_expired": true,
    "is_due_soon": true,
    "details": "string",
    "sla": {
        "high": {
            "response_time": 1,
            "resolution_time": 1
        },
        "medium": {
            "response_time": 1,
            "resolution_time": 1
        },
        "low": {
            "response_time": 1,
            "resolution_time": 1
        }
    },
    "allowance": {
        "month": 1,
        "year": 1,
        "remote": {
            "included": 1.5,
            "used": 1.5,
            "remaining": 1.5,
            "pct": 1.5
        },
        "onsite": {
            "included": 1.5,
            "used": 1.5,
            "remaining": 1.5,
            "pct": 1.5
        }
    },
    "documents": [
        {
            "id": 1,
            "name": "string",
            "mime_type": "string",
            "size": 1,
            "uploaded_at": "string",
            "url": "string"
        }
    ],
    "created_at": "string",
    "updated_at": "string"
}

403Authenticated but not permitted

FieldTypeDescription
error string

404Resource not found

FieldTypeDescription
error string