Routes API
Route management endpoints
Routes API
Manage CIDR-based routing rules for services.
GET /v1/services/{service_id}/routes
List routes for a service.
Authentication
Required. Scope: services.read
Path Parameters
| Parameter | Description |
|---|---|
service_id | Service ID |
Response
[
{
"id": 1,
"service_id": "01HSVC...",
"priority": 100,
"source_cidr": "10.0.0.0/8",
"dest_cidr": "192.168.100.0/24"
}
]Errors
| Status | Code | Description |
|---|---|---|
| 404 | NOT_FOUND | Service not found |
POST /v1/services/{service_id}/routes
Add routes to a service.
Authentication
Required. Scope: services.write
Path Parameters
| Parameter | Description |
|---|---|
service_id | Service ID |
Request Body
{
"routes": [
{
"priority": 100,
"source_cidr": "10.0.0.0/8",
"dest_cidr": "192.168.100.0/24"
},
{
"priority": 200,
"source_cidr": "10.1.0.0/16",
"dest_cidr": "192.168.200.0/24"
}
]
}| Field | Type | Required | Description |
|---|---|---|---|
routes | array | Yes | Array of route objects |
Route object fields:
| Field | Type | Required | Description |
|---|---|---|---|
priority | integer | Yes | Route priority |
source_cidr | string | No | Source CIDR |
dest_cidr | string | No | Destination CIDR |
At least one of source_cidr or dest_cidr must be provided.
Response
{
"route_ids": [1, 2],
"count": 2
}Errors
| Status | Code | Description |
|---|---|---|
| 400 | INVALID_REQUEST | Missing routes array |
| 400 | INVALID_CIDR | Invalid CIDR notation |
| 404 | NOT_FOUND | Service not found |
Example
curl -X POST http://agent:8080/v1/services/01HSVC.../routes \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"routes": [{
"priority": 100,
"source_cidr": "10.0.0.0/8",
"dest_cidr": "192.168.100.0/24"
}]
}'PUT /v1/services/{service_id}/routes/{route_id}
Update a route.
Authentication
Required. Scope: services.write
Path Parameters
| Parameter | Description |
|---|---|
service_id | Service ID |
route_id | Route ID (numeric) |
Request Body
{
"priority": 200,
"source_cidr": "10.1.0.0/16",
"dest_cidr": "192.168.200.0/24"
}All fields are optional. Only provided fields are updated.
Response
{
"id": 1,
"service_id": "01HSVC...",
"priority": 200,
"source_cidr": "10.1.0.0/16",
"dest_cidr": "192.168.200.0/24"
}Errors
| Status | Code | Description |
|---|---|---|
| 400 | INVALID_CIDR | Invalid CIDR notation |
| 404 | NOT_FOUND | Route or service not found |
DELETE /v1/services/{service_id}/routes/{route_id}
Delete a route.
Authentication
Required. Scope: services.write
Path Parameters
| Parameter | Description |
|---|---|
service_id | Service ID |
route_id | Route ID (numeric) |
Response
{
"deleted": true
}Errors
| Status | Code | Description |
|---|---|---|
| 404 | NOT_FOUND | Route or service not found |