Tillered Arctic
Reference

API Overview

Introduction to the Arctic HTTP API

HTTP API Overview

Arctic agents expose an HTTP API for management and integration.

Base URL

The API is served on port 8080 by default:

http://AGENT_IP:8080

Authentication

Most endpoints require OAuth2 authentication. See Authentication for details.

Public endpoints (no auth required):

  • /livez - Liveness check
  • /readyz - Readiness check
  • /.well-known/openid-configuration - OIDC discovery
  • /.well-known/jwks.json - JSON Web Key Set
  • /v1/cluster/identity - Peer identity

API Versioning

All API endpoints are prefixed with /v1/.

Content Type

Request and response bodies use JSON:

Content-Type: application/json

Endpoints

Health

MethodEndpointDescription
GET/livezLiveness probe
GET/readyzReadiness probe

Bootstrap & License

MethodEndpointDescription
POST/v1/bootstrapInitialize agent
GET/v1/licenseGet license info
PUT/v1/licenseUpdate license

Peers

MethodEndpointDescription
GET/v1/peersList peers
GET/v1/peers/\{id\}Get peer
POST/v1/peersAdd peer
PUT/v1/peers/\{id\}Update peer
DELETE/v1/peers/\{id\}Delete peer
DELETE/v1/peers/selfRemove self

Services

MethodEndpointDescription
GET/v1/servicesList services
GET/v1/services/\{id\}Get service
POST/v1/servicesCreate service
PUT/v1/services/\{id\}Update service
DELETE/v1/services/\{id\}Delete service

Routes

MethodEndpointDescription
GET/v1/services/\{id\}/routesList routes
POST/v1/services/\{id\}/routesAdd routes
PUT/v1/services/\{id\}/routes/\{route_id\}Update route
DELETE/v1/services/\{id\}/routes/\{route_id\}Delete route

Credentials

MethodEndpointDescription
GET/v1/credentialsList credentials
POST/v1/credentialsCreate credential
DELETE/v1/credentials/\{client_id\}Revoke credential

Cluster

MethodEndpointDescription
GET/v1/cluster/identityGet identity
POST/v1/cluster/initInitialize cluster
POST/v1/cluster/syncTrigger sync
POST/v1/cluster/credentials/rotateRotate credential

Error Responses

Errors return appropriate HTTP status codes with a JSON body:

{
  "error": "peer not found",
  "code": "NOT_FOUND"
}

See Error Codes for details.

Rate Limiting

The API does not implement rate limiting. Consider implementing rate limiting at the load balancer level for production deployments.

Exit Codes

Arctic CLI exit codes and their meanings

Authentication

OAuth2 authentication for the Arctic API

On this page

HTTP API OverviewBase URLAuthenticationAPI VersioningContent TypeEndpointsHealthBootstrap & LicensePeersServicesRoutesCredentialsClusterError ResponsesRate Limiting