Skip to content

API reference / RivetMSP

RivetMSP API

v1.0.0 110 endpoints OpenAPI 3

Companion REST API for RivetMSP, consumed by the RivetMSP mobile app and integrations (ITPanel Pro, RMM scripts). This spec documents the live endpoints served by /api/v1/index.php and its per-resource handlers.

Authentication: send a bearer token issued by POST /auth (Authorization: Bearer <token>) OR a legacy instance API key (X-Api-Key: <key>). The legacy key resolves to the first active admin and is intentionally denied on /credentials and /me. The /auth, /branding, /openapi and /docs endpoints are public (no token required).

Response conventions:

  • Paged list endpoints return { "data": [ ... ], "total": <int> } (some also add page/limit).
  • Some list endpoints return a bare JSON array (noted per-endpoint).
  • Creates return { "id": <int> } (sometimes with extra fields).
  • Simple mutations return { "ok": true }.
  • Errors return { "error": "<message>" } with the matching HTTP status.

Base URL and authentication

Requests go to https://YOUR-HOST/api/v1, where YOUR-HOST is your own install.

Quick start

  1. 1Get a token

    Password login — returns a bearer token, or requires_2fa. Keep the token and send it as a bearer token on every call.

    curl -X POST "https://YOUR-HOST/api/v1/auth" \
      -H "Content-Type: application/json" \
      -d '{"username":"string","password":"string"}'
    import requests
    
    response = requests.post(
        "https://YOUR-HOST/api/v1/auth",
        json={
            "username": "string",
            "password": "string"
        },
    )
    print(response.json())
    const response = await fetch("https://YOUR-HOST/api/v1/auth", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
          "username": "string",
          "password": "string"
      }),
    });
    const data = await response.json();
    $ch = curl_init("https://YOUR-HOST/api/v1/auth");
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CUSTOMREQUEST => "POST",
        CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
        CURLOPT_POSTFIELDS => '{"username":"string","password":"string"}',
    ]);
    $data = json_decode(curl_exec($ch), true);
    Example response
    json
    {
        "token": "string",
        "user": {
            "id": 1,
            "name": "string",
            "email": "string",
            "type": 1
        }
    }
  2. 2Make your first request

    List tickets. Replace TOKEN with the token from step 1.

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

Find an endpoint

Resources