chap-core

Service Registration (v2 API)

!!! warning “Experimental Feature” This feature is a work in progress and considered experimental. The API may change in future releases without prior notice.

The v2 API provides service registration endpoints that enable ML models built with chapkit and servicekit to register themselves with Chap for automatic discovery. A registered service gets a model template in Chap, but no configurations: the reviewed configurations of a model come from its marketplace entry through chap-admin install.

Overview

Services register with the Chap orchestrator and must send periodic keepalive pings to maintain their registration. Services that fail to ping within the TTL window are automatically expired.

Key features:

• Update on re-register - Re-registering a service updates its data (latest wins)
• Slug-based IDs - Services provide their own unique identifier (start with lowercase letter, then lowercase letters, numbers, and hyphens)
• TTL-based expiry - Services must ping periodically to stay registered (default: 30 seconds)
• Redis/Valkey backend - Service data stored with automatic expiration

Endpoints

Method	Path	Auth	Description
POST	/v2/services/$register	Required	Register a service
PUT	/v2/services/{id}/$ping	Required	Keepalive ping
GET	/v2/services	Public	List all services
GET	/v2/services/{id}	Public	Get single service
DELETE	/v2/services/{id}	Required	Deregister service

Authentication

Protected endpoints require an API key in the X-Service-Key header.

Server Configuration

Set the SERVICEKIT_REGISTRATION_KEY environment variable on the Chap server:

export SERVICEKIT_REGISTRATION_KEY="your-secret-key"

Client Usage

Include the key in requests to protected endpoints:

import httpx

headers = {"X-Service-Key": "your-secret-key"}

response = httpx.post(
    "http://chap:8000/v2/services/$register",
    json=payload,
    headers=headers,
)

Error Responses

When SERVICEKIT_REGISTRATION_KEY is configured on the server:

Scenario	Response
Missing header	401 Unauthorized
Invalid key	401 Unauthorized

If the environment variable is not set, authentication is skipped and registration proceeds without requiring a key.

!!! note “Changed in 2.2.0” A missing X-Service-Key header previously returned 422 Unprocessable Entity. It now returns 401 Unauthorized, consistent with an invalid key.

If the server also sets CHAP_API_TOKEN, the whole API is protected, including these endpoints. Because servicekit can only send X-Service-Key, the API token is accepted in that header too on /v2/services paths: set SERVICEKIT_REGISTRATION_KEY on the service to either the registration key or the API token. See API Authentication.

Registration Payload

The registration payload contains the service URL and MLServiceInfo metadata:

{
    "url": "http://my-model:8080",
    "info": {
        "id": "my-model",
        "display_name": "My ML Model",
        "version": "1.0.0",
        "description": "A predictive model for disease forecasting",
        "model_metadata": {
            "author": "Your Name",
            "organization": "Your Org"
        },
        "period_type": "monthly",
        "min_prediction_periods": 1,
        "max_prediction_periods": 12
    }
}

Registration Response

{
    "id": "my-model",
    "status": "registered",
    "service_url": "http://my-model:8080",
    "message": "Service registered successfully",
    "ttl_seconds": 30,
    "ping_url": "/v2/services/my-model/$ping"
}

Keepalive Mechanism

Services must send periodic pings to maintain their registration:

response = httpx.put(
    "http://chap:8000/v2/services/my-model/$ping",
    headers={"X-Service-Key": "your-secret-key"},
)

The ping resets the TTL timer. If a service fails to ping within the TTL window (default 30 seconds), it is automatically removed from the registry.

A ping only refreshes the expiry. It never changes the registered URL or service info, so a service that moves must call $register again. A ping for a service that has expired or been deregistered returns 404 and does not recreate the registration; the service must re-register.

Integration with Servicekit

Servicekit handles registration and keepalive automatically once the service builder enables it with .with_registration(). The Chap URL and the key are read from environment variables unless passed to .with_registration():

export SERVICEKIT_ORCHESTRATOR_URL="http://chap:8000/v2/services/\$register"
export SERVICEKIT_REGISTRATION_KEY="your-secret-key"

See the servicekit documentation for more details.

Integration with Chapkit

Chapkit extends servicekit with ML-specific functionality. A chapkit service is built with MLServiceBuilder and enables registration with .with_registration(); the Chap URL is read from SERVICEKIT_ORCHESTRATOR_URL, as shown in Running Your Own Model.

See the chapkit deployment guide for the service code.

This site is open source. Improve this page.