API Reference

The Ichnos backend accepts trace data, provides fleet insight, and starts focused capture on a robot when an incident needs more evidence. For the trace model, see Documentation.

Base URL: https://api.orthosrobotics.com
Access: Session cookie or HTTP Basic for protected routes
Content-Type: application/json
Errors: Non-2xx → plain-text body, no JSON envelope

Trace ingest (write path)

gRPCTraceService/Export

Standard OTLP/gRPC trace-collector service. Point any OTLP exporter here exactly like you'd point one at Jaeger or Tempo.

Config

port	int	4317 by default (`OTLP_GRPC_PORT`)
auth	—	none; network-level trust assumed

Response

200ExportTraceServiceResponse, empty on success

# collector exporter config

exporters:
  otlp/ichnos:
    endpoint: otlp.orthosrobotics.com:4317
    tls:
      insecure: false

Fleet API (read / control path)

POST/api/login

Start an operator session for a browser client. This route uses the same operator credentials as HTTP Basic authentication and returns a secure session cookie.

Body

username	string	operator user name
password	string	operator password

Related session routes

GET /api/session	public	Returns the current session state.
POST /api/logout	public	Ends the current session.

# request

curl -i -X POST \\
  -H "Content-Type: application/json" \\
  -d '{"username":"operator","password":"••••••••"}' \\
  https://api.orthosrobotics.com/api/login

# response · 200

{
  "authenticated": true
}

GET/api/robots

Every known robot, most recently seen first.

Query params

none

Response

200list of robots

# request

curl -u user:pass \
  https://api.orthosrobotics.com/api/robots

# response · 200

{
  "robots": [
    {
      "DeviceID": "robot_alpha_01",
      "FirstSeenAt": "2026-08-01T09:00:00Z",
      "LastSeenAt": "2026-08-14T00:14:51Z",
      "ForensicModeUntil": null
    }
  ]
}

GET/api/missions

Fleet-wide mission list, filterable and paginated.

Query params

robot_id	string	exact match, optional
status	string	`RUNNING` / `SUCCESS` / `FAILURE` / `CANCELED` / `PREEMPTED`
limit	int	default 50
offset	int	default 0

Response

200list of missions

400malformed limit/offset

# request

curl -u user:pass \
  "https://api.orthosrobotics.com/api/missions\
?robot_id=robot_alpha_01&status=FAILURE&limit=20"

# response · 200

{
  "missions": [
    {
      "ID": 12,
      "TraceID": "4bf92f3577b34da6a3ce929d0e0e4736",
      "SpanID": "00f067aa0ba902b7",
      "RobotID": "robot_alpha_01",
      "Name": "NavigateToGoal",
      "Behavior": "NavigateToPose",
      "Status": "FAILURE",
      "StartTime": "2026-08-14T00:12:03Z",
      "EndTime": "2026-08-14T00:14:51Z"
    }
  ]
}

GET/api/missions/{id}

One mission plus its nested diagnostic events.

Path params

int64

mission row ID

Response

200mission + diagnostic_events

404id doesn't exist

# request

curl -u user:pass \
  https://api.orthosrobotics.com/api/missions/12

# response · 200

{
  "mission": {
    "ID": 12, "Status": "FAILURE",
    "Behavior": "NavigateToPose", // ...
  },
  "diagnostic_events": [
    {
      "ID": 41,
      "HardwareID": "battery_01",
      "Component": "battery",
      "Level": 1,
      "Message": "voltage low",
      "Readings": { "voltage": "10.2" },
      "OccurredAt": "2026-08-14T00:13:10Z"
    }
  ]
}

GET/api/robots/{device_id}/faults

A robot's most recent level > 0 diagnostic events, most recent first.

Path params

device_id

string

must be a known robot

Query params

limit

int

optional, uncapped if omitted

Response

200list of faults

404device_id unknown

# request

curl -u user:pass \
  https://api.orthosrobotics.com/api/robots/robot_alpha_01/faults?limit=5

# response · 200

{
  "faults": [
    {
      "ID": 41,
      "Component": "battery",
      "Level": 1,
      "Message": "voltage low",
      // ...
    }
  ]
}

GET/api/robots/{device_id}/forensic-mode

Current forensic-mode state for a robot. This is what ichnos-agent itself polls.

Path params

device_id

string

must be a known robot

Response

200active state + expiry

404device_id unknown

# request

curl -u user:pass \
  https://api.orthosrobotics.com/api/robots/robot_alpha_01/forensic-mode

# response · 200

{
  "active": true,
  "until": "2026-08-14T00:29:00Z"
}

POST/api/robots/{device_id}/forensic-mode

Trigger forensic mode for a robot. Same request the dashboard's trigger button sends.

Path params

device_id

string

must be a known robot

Body (optional)

duration_seconds

int

defaults to 300 if omitted or 0

Response

200active state + new expiry

404device_id unknown

# request

curl -u user:pass -X POST \
  -H "Content-Type: application/json" \
  -d '{"duration_seconds": 900}' \
  https://api.orthosrobotics.com/api/robots/robot_alpha_01/forensic-mode

# response · 200

{
  "active": true,
  "until": "2026-08-14T00:29:00Z"
}

Optional scenario search

GET/api/scenarios

Search for recurring mission conditions across diagnostic and evidence signals. This endpoint is available only when the deployment enables scenario search.

Useful query params

robot_id, status, schema_hash	string	exact-match mission filters
min_clock_drift_ms	number	minimum absolute observed clock offset
diagnostic_component	string	component-name text match
min_diagnostic_level	int	minimum diagnostic severity, 0–3
limit, offset	int	pagination controls

Response

200list of matching missions

404scenario search is not enabled on this deployment

# example

curl -u user:pass \\
  "https://api.orthosrobotics.com/api/scenarios?\
min_clock_drift_ms=200&diagnostic_component=amcl&\
min_diagnostic_level=2"

Errors

Non-2xx responses are a plain-text body, not a JSON envelope — don't JSON.parse them.

400	Malformed query param or JSON body. Body is the raw Go error string.
401	Missing or invalid session and Basic Auth credentials. Protected JSON routes do not send a browser Basic-Auth challenge.
404	Unknown path, or a path param (mission `id`, robot `device_id`) that doesn't exist.
500	Server-side failure. Body is a fixed, generic message — details are server-logged only.