API Reference

Complete reference for the routes.ai REST API

Base URL

https://api.routes.ai

Authentication

All API requests require authentication using an API key in the Authorization header:

Authorization: Bearer sk_prod_your_api_key_here
Get your API key

Endpoints

POST/v1/solve

Submit a routing problem for optimization

Request Body

{
  "nodes": [
    {
      "id": "depot",
      "lat": 37.7749,
      "lng": -122.4194
    },
    {
      "id": "stop_1", 
      "lat": 37.7849,
      "lng": -122.4094,
      "demand": 10,
      "time_window": [480, 1020]
    }
  ],
  "vehicles": [
    {
      "id": "truck_1",
      "capacity": 100,
      "start": "depot",
      "end": "depot"
    }
  ],
  "objective": "minimize_distance"
}

Response

{
  "job_id": "job_abc123",
  "status": "queued",
  "estimated_completion_time": "2024-01-15T10:30:00Z",
  "credits_consumed": 0,
  "estimated_credits": 5
}
GET/v1/solve/{job_id}

Get the solution for a completed job

Response

{
  "job_id": "job_abc123",
  "status": "completed",
  "solution": {
    "routes": [
      {
        "vehicle_id": "truck_1",
        "stops": ["depot", "stop_1", "depot"],
        "total_distance": 2.1,
        "total_time": 15.5
      }
    ],
    "total_distance": 2.1,
    "total_time": 15.5,
    "credits_consumed": 5
  }
}
POST/v1/estimate

Get cost estimates without consuming credits

Response

{
  "estimated_credits": 5,
  "estimated_runtime_seconds": 30,
  "problem_size": "small"
}
GET/v1/usage

Get current usage and billing information

Response

{
  "current_usage": {
    "credits_used": 150,
    "credits_remaining": 850,
    "billing_cycle_start": "2024-01-01T00:00:00Z",
    "billing_cycle_end": "2024-02-01T00:00:00Z"
  },
  "subscription": {
    "plan": "pro",
    "status": "active"
  }
}

Error Handling

The API uses conventional HTTP response codes to indicate success or failure:

200OK - Request succeeded
400Bad Request - Invalid parameters
401Unauthorized - Invalid API key
429Too Many Requests - Rate limit exceeded
500Internal Server Error

Rate Limits

API rate limits are enforced per API key:

  • • Free tier: 10 requests per minute
  • • Pro tier: 100 requests per minute
  • • Enterprise: Custom limits