Use the REST reference and make a first request

1Copy the deployed API address

Open Admin → API Docs or API Keys → View API docs to reach the Public API page. Copy Base URL from Base URL & Auth. If the console says External API address not configured, ask the deployment administrator for the approved gateway; examples and OpenAPI download stay unavailable until it is configured. The browser’s console sign-in does not authenticate these external endpoints.

Enlarge

2Authenticate and inspect the key identity

Use the copied base address and send either Authorization: Bearer <key> or X-API-Key: <key>. Call GET /v1/health first. Confirm ok, tenant_id, scopes, and key_name correspond to the organization and key you intended. The documented rate limit is 600 requests per minute per key; avoid rapid retry loops.

curl --fail \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "YOUR_BASE_URL/v1/health"

3Look up a device and use its returned ID

Expand GET /v1/endpoints/lookup. Supply one identifier: email, hostname, agent_id, or serial. Hostname lookup is exact and case-insensitive. An email may resolve to multiple devices, so inspect all matches and choose the intended endpoint rather than assuming the first is correct. Use the returned endpoint UUID in the device detail, DEX, events, and telemetry routes.

curl --fail \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "YOUR_BASE_URL/v1/endpoints/lookup?email=alex%40example.com"

4Choose the read route and its filters

Use Filter routes... to find an operation and expand its entry. Read the required scope, parameters, and response before copying an example. The list and history routes are bounded; a returned list is not automatically a complete fleet export.

5Download OpenAPI and implement the receiving workflow

Use Download the OpenAPI specification and run its authenticated request with your key. The supplied request writes rapport-openapi.json for your client tooling. The ITSM quickstart shows device lookup, alert enrichment, and an external ticket back-link. Your ITSM automation must still write the returned hostname/score or alert information into its own record.

curl --fail \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "YOUR_BASE_URL/v1/openapi.json" -o rapport-openapi.json

6Back-link an external incident

With incident_create scope and read/write tenant consent, send POST /v1/incidents with a required title, the external ticket ID in source_ref, and the intended alert_id or endpoint identity. Optional fields include description, severity, and metadata. If using user_email, the endpoint must resolve uniquely. Inspect the response’s recorded, endpoint_id, alert_id, and source_ref, then check the alert correlation. This records the external reference; your ITSM application creates its own ticket.

{
  "alert_id": "ALERT_UUID",
  "source_ref": "INC0012345",
  "title": "Investigate repeated application crashes"
}

7Dispatch a command and inspect each job

With command_dispatch scope and write consent, send POST /v1/commands with explicit endpoint_ids, the supported command_type, command-specific payload, and a readable name. The request accepts 1–200 owned endpoint UUIDs; timeout_sec defaults to 600. requires_approval can request a gate but cannot bypass mandatory policy or machine-request approval. Save the returned batch_id and job_ids, then poll GET /v1/commands/{job_id} for each job.

What you should see: Read final status, exit code, stdout, and stderr, then verify the intended device effect. A queued/dispatched job is not a completed device change.

8Synchronize CI identifiers

Use GET /v1/ci/endpoints with ci_read to read up to 1,000 tenant endpoints in CMDB shape, including endpoint ID, hostname, serial, assigned owner email, and external CI ID. After your application creates or updates its provider CI, send POST /v1/ci/sync-acks with ci_write and write consent. Supply 1–200 acks containing endpoint_id, ci_id, and optional synced_at. Verify the returned updated count and the endpoint’s recorded CI reference.

{
  "acks": [
    { "endpoint_id": "ENDPOINT_UUID", "ci_id": "CI0001234" }
  ]
}