Tillered Arctic
ReferenceHTTP API Reference

Services API

Service management endpoints

Services API

Manage services for network routing.

GET /v1/services

List services.

Authentication

Required. Scope: services.read

Query Parameters

ParameterTypeDescription
source_peer_idstringFilter by source peer
target_peer_idstringFilter by target peer
requires_interfacebooleanFilter by interface requirement

Response

[
  {
    "id": "01HSVC...",
    "source_peer_id": "01HXYZ...",
    "target_peer_id": "01HABC...",
    "transport_type": "tcp",
    "requires_interface": true,
    "interface_ipv4_cidr": "192.168.100.10/24",
    "interface_ipv6_cidr": null,
    "fully_transparent": false,
    "bandwidth_limit_mbps": 1000,
    "route_count": 2,
    "created_at": "2024-01-15T10:30:00Z"
  }
]

Example

curl -X GET http://agent:8080/v1/services \
  -H "Authorization: Bearer $TOKEN"

# Filter by target peer
curl -X GET "http://agent:8080/v1/services?target_peer_id=01HABC..." \
  -H "Authorization: Bearer $TOKEN"

GET /v1/services/{id}

Get a specific service.

Authentication

Required. Scope: services.read

Path Parameters

ParameterDescription
idService ID

Response

{
  "id": "01HSVC...",
  "source_peer_id": "01HXYZ...",
  "target_peer_id": "01HABC...",
  "transport_type": "tcp",
  "requires_interface": true,
  "interface_ipv4_cidr": "192.168.100.10/24",
  "interface_ipv6_cidr": null,
  "fully_transparent": false,
  "bandwidth_limit_mbps": 1000,
  "routes": [
    {
      "id": 1,
      "priority": 100,
      "source_cidr": "10.0.0.0/8",
      "dest_cidr": "192.168.100.0/24"
    }
  ],
  "created_at": "2024-01-15T10:30:00Z"
}

Errors

StatusCodeDescription
404NOT_FOUNDService not found

POST /v1/services

Create a new service.

Authentication

Required. Scope: services.write

Request Body

{
  "target_peer_id": "01HABC...",
  "source_peer_id": "01HXYZ...",
  "transport_type": "tcp",
  "requires_interface": true,
  "desired_ipv4_cidr": "192.168.100.10/24",
  "desired_ipv6_cidr": "fd00::10/64",
  "fully_transparent": false,
  "bandwidth_limit_mbps": 1000
}
FieldTypeRequiredDefaultDescription
target_peer_idstringYesTarget peer ID
source_peer_idstringNolocalSource peer ID
transport_typestringNotcptcp or kcp
requires_interfacebooleanNofalseCreate MACVLAN
desired_ipv4_cidrstringNoIPv4 for interface
desired_ipv6_cidrstringNoIPv6 for interface
fully_transparentbooleanNofalseTransparent mode
bandwidth_limit_mbpsintegerNo0Bandwidth limit

Response

{
  "id": "01HSVC...",
  "source_peer_id": "01HXYZ...",
  "target_peer_id": "01HABC...",
  "transport_type": "tcp",
  "requires_interface": true,
  "created_at": "2024-01-15T10:30:00Z"
}

Errors

StatusCodeDescription
400INVALID_REQUESTMissing target_peer_id
400INVALID_TRANSPORTInvalid transport type
404NOT_FOUNDTarget peer not found
409ALREADY_EXISTSService already exists
422SERVICE_LIMIT_EXCEEDEDLicense limit reached

PUT /v1/services/{id}

Update service settings.

Authentication

Required. Scope: services.write

Path Parameters

ParameterDescription
idService ID

Request Body

{
  "requires_interface": true,
  "desired_ipv4_cidr": "192.168.100.10/24",
  "bandwidth_limit_mbps": 500
}

All fields are optional. Only provided fields are updated.

Response

Returns the updated service.

Errors

StatusCodeDescription
404NOT_FOUNDService not found

DELETE /v1/services/{id}

Delete a service.

Authentication

Required. Scope: services.write

Path Parameters

ParameterDescription
idService ID

Response

{
  "deleted": true
}

Errors

StatusCodeDescription
404NOT_FOUNDService not found

Notes

Deleting a service also deletes all associated routes.

See Also

Peers API

Peer management endpoints

Routes API

Route management endpoints

On this page

Services APIGET /v1/servicesAuthenticationQuery ParametersResponseExampleGET /v1/services/{id}AuthenticationPath ParametersResponseErrorsPOST /v1/servicesAuthenticationRequest BodyResponseErrorsPUT /v1/services/{id}AuthenticationPath ParametersRequest BodyResponseErrorsDELETE /v1/services/{id}AuthenticationPath ParametersResponseErrorsNotesSee Also