Skip to main content

Robot Jobs API

Manage autonomous robot charging jobs and task assignments.

Overview​

The Robot Jobs API enables you to create, track, and manage jobs for autonomous charging robots. When a charging job is created, the robot locates the target EVSE, initiates an OCPI session with the CPO, and monitors the session until completion.

Base URL: https://api.rollyy.com/v1/robot-jobs

Authentication​

All endpoints require API key authentication.

curl -H "X-API-Key: your_api_key_here" \
  https://api.rollyy.com/v1/robot-jobs

Endpoints​

Create Robot Job​

Create a new charging job for a robot.

Endpoint: POST /v1/robot-jobs

Request Body:

{
  "robot_id": "robot-001",
  "job_type": "charging",
  "place_id": "place-123",
  "vehicle_id": "vehicle-456"
}

Parameters:

  • robot_id (string, required): Robot identifier
  • job_type (string, required): Job type (charging, delivery, patrol)
  • place_id (string, optional): Location identifier
  • vehicle_id (string, optional): Target vehicle identifier

Response:

{
  "rollyy_id": "550e8400-e29b-41d4-a716-446655440000",
  "robot_id": "robot-001",
  "job_type": "charging",
  "place_id": "place-123",
  "vehicle_id": "vehicle-456",
  "status": "queued",
  "created_at": "2026-02-07T12:00:00Z"
}

Get Robot Job​

Retrieve details of a specific robot job, including the linked charging session.

Endpoint: GET /v1/robot-jobs/{job_id}

Response:

{
  "rollyy_id": "550e8400-e29b-41d4-a716-446655440000",
  "robot_id": "robot-001",
  "job_type": "charging",
  "status": "charging",
  "charging_session_id": "770e8400-e29b-41d4-a716-446655440002",
  "created_at": "2026-02-07T12:00:00Z",
  "completed_at": null
}

List Robot Jobs​

Endpoint: GET /v1/robot-jobs

Query Parameters:

  • robot_id (string, optional): Filter by robot ID
  • status (string, optional): Filter by status

Example:

curl -H "X-API-Key: your_api_key" \
  "https://api.rollyy.com/v1/robot-jobs?status=charging"

Get charging session for a job​

Returns the live charging session linked to a robot job.

Endpoint: GET /ocpi/2.2.1/sessions/job/{job_id}

Response:

{
  "session_id": "770e8400-e29b-41d4-a716-446655440002",
  "status": "active",
  "energy_kwh": 12.5,
  "cost": 4.38,
  "currency": "EUR",
  "duration_minutes": 22,
  "start_time": "2026-02-07T12:05:00Z",
  "end_time": null,
  "robot_job_status": "charging"
}

Job Lifecycle​

When a charging job is created, the following happens automatically:

Job created (queued)
    ↓
Robot dispatched to EVSE
    ↓
POST /ocpi/2.2.1/commands/START_SESSION → CPO
    ↓
Job status: charging | Session status: pending → active
    ↓
CPO pushes session updates (energy, cost)
    ↓
POST /ocpi/2.2.1/commands/STOP_SESSION → CPO
    ↓
CPO pushes CDR (authoritative billing record)
    ↓
Payment triggered automatically
    ↓
Job status: completed | Session status: completed

Job Status​

StatusMeaning
queuedJob created, robot not yet dispatched
in_progressRobot en route to EVSE
chargingOCPI session active
completedSession finished, CDR received
failedError — CPO rejected or robot issue