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
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