Quickstart

This guide walks you from "no account" to a successful API call. It takes about five minutes.

1. Get an API key

API keys live in the planner dashboard. Open your Routal account at planner.routal.com and go to Settings → Developers → API Keys, or jump straight to:

planner.routal.com/h/settings/developers/api-keys

Click Create key, give it a descriptive label (e.g. staging-integration), and copy the value. The key starts with api_key_. Treat it like a password — it grants the same access as the user who created it.

If you don't have a Routal account yet, start a trial.

2. Make your first request

A good first endpoint is GET /v2/vehicles — it returns the vehicles in your fleet for a given project. project_id is required.

curl -G 'https://api.routal.com/v2/vehicles' \
  --data-urlencode 'private_key=YOUR_KEY' \
  --data-urlencode 'project_id=YOUR_PROJECT_ID'

Replace YOUR_KEY with the value you copied above, and YOUR_PROJECT_ID with the 24-char hex ID of the project (visible in the URL of your project in the dashboard).

Expected response

The response uses the standard paginated envelope. The fields below come from the real VehicleData schema in the spec.

{
  "total": 4,
  "limit": 20,
  "offset": 0,
  "pages": 1,
  "page": 1,
  "docs": [
    {
      "id": "4f75d991ac359f8c4c79d762",
      "organization_id": "4f75d991ac359f8c4c79d762",
      "project_id": "4f75d991ac359f8c4c79d762",
      "external_id": "the_external_id",
      "label": "Van 01",
      "plate": "2596KHO",
      "vehicle_model": "Transit",
      "brand": "Ford",
      "color": "#089747",
      "enabled": true,
      "default_provides": ["frozen"],
      "created_at": "2026-05-21T10:00:00.000Z"
    }
  ]
}

A vehicle has many more fields (capacity defaults, time windows, etc.) — see the API Reference → Vehicle page for the full schema.

If it didn't work

See Errors for the full machine-code reference.

3. Create your first plan

A Plan groups stops, vehicles, and routes for a delivery window. POST /v2/plan creates one. project_id is required as a query parameter.

curl -X POST 'https://api.routal.com/v2/plan?private_key=YOUR_KEY&project_id=YOUR_PROJECT_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "label": "Hello Routal",
    "execution_date": "2026-05-22"
  }'

The response carries the plan's id plus aggregate counts. From there you can add stops, attach routes, and call POST /v2/plan/{id}/optimize to compute optimal assignments.

{
  "id": "4f75d991ac359f8c4c79d762",
  "organization_id": "4f75d991ac359f8c4c79d762",
  "project_id": "4f75d991ac359f8c4c79d762",
  "label": "Hello Routal",
  "status": "planning",
  "execution_date": "2026-05-22",
  "completed_stops": 0,
  "canceled_stops": 0,
  "pending_stops": 0,
  "incomplete_stops": 0,
  "total_stops": 0,
  "total_routes": 0,
  "created_at": "2026-05-21T10:05:00.000Z"
}

What next?

• Walk through a complete scenario in the Recipes section — each opens with a TL;DR card so you can self-identify in seconds.
• Browse the API Reference for every endpoint, parameter, and schema.
• Read Authentication — key rotation, security best practices, what API keys can and can't do today.
• Subscribe to Webhooks so your systems react to plan and stop lifecycle events in real time.
• Understand the Lifecycle of plans, routes, and stops before building state-aware logic.
• Working with an AI coding assistant? Drop the LLM context block into your editor's rules file.

Have feedback? Email developers@routal.com or reach us on the chat in the planner dashboard.