API Reference
The Hill90 API provides endpoints for agent management, model access configuration, agent knowledge, user profiles, and platform health checks.Base URL
Authentication
Most endpoints require a valid JWT bearer token issued by Keycloak. Include it in theAuthorization header:
Endpoint Groups
Health
| Endpoint | Auth | Description |
|---|---|---|
GET /health | None | Service health check |
User
| Endpoint | Auth | Description |
|---|---|---|
GET /me | Bearer | Get current user JWT claims |
GET /profile | Bearer | Get user profile |
PATCH /profile | Bearer | Update display name |
POST /profile/avatar | Bearer | Upload avatar image |
GET /profile/avatar | Bearer | Get avatar image |
DELETE /profile/avatar | Bearer | Delete avatar |
POST /profile/password | Bearer | Change password (not yet implemented) |
Agents
| Endpoint | Auth | Description |
|---|---|---|
GET /agents | Bearer | List agents |
POST /agents | Bearer | Create agent |
GET /agents/{id} | Bearer | Get agent detail |
PUT /agents/{id} | Bearer | Update agent |
DELETE /agents/{id} | Bearer (admin) | Delete agent |
POST /agents/{id}/start | Bearer (admin) | Start agent container |
POST /agents/{id}/stop | Bearer (admin) | Stop agent container |
GET /agents/{id}/status | Bearer | Get agent status |
GET /agents/{id}/logs | Bearer (admin) | Get agent logs (JSON or SSE stream) |
Knowledge
Browse and search agent knowledge entries. Agents write knowledge; humans browse it here.| Endpoint | Auth | Description |
|---|---|---|
GET /knowledge/agents | Bearer | List agents with knowledge stats |
GET /knowledge/entries | Bearer | List entries for an agent |
GET /knowledge/entries/{agentId}/{path} | Bearer | Read a specific entry |
GET /knowledge/search | Bearer | Full-text search across entries |
Provider Connections
Manage your own API key connections to LLM providers. Keys are encrypted at rest and never returned in responses.| Endpoint | Auth | Description |
|---|---|---|
GET /provider-connections | Bearer | List your provider connections |
POST /provider-connections | Bearer | Create a provider connection |
PUT /provider-connections/{id} | Bearer | Update a provider connection |
DELETE /provider-connections/{id} | Bearer | Delete a provider connection |
POST /provider-connections/{id}/validate | Bearer | Test if a provider key is valid |
User Models
Define models that reference your provider connections. Model names must not conflict with platform models.| Endpoint | Auth | Description |
|---|---|---|
GET /user-models | Bearer | List your models |
POST /user-models | Bearer | Create a user model |
PUT /user-models/{id} | Bearer | Update a user model |
DELETE /user-models/{id} | Bearer | Delete a user model |
Model Policies
Control which models an agent can access, with optional rate limits and token budgets. Users can create and manage their own policies; admins can also create platform-wide policies.| Endpoint | Auth | Description |
|---|---|---|
GET /model-policies | Bearer | List policies (own + platform) |
POST /model-policies | Bearer | Create a model policy |
GET /model-policies/{id} | Bearer | Get policy detail |
PUT /model-policies/{id} | Bearer | Update a policy |
DELETE /model-policies/{id} | Bearer | Delete a policy |
Usage
Query model usage statistics with filtering and grouping options. Users see their own usage; admins see all.| Endpoint | Auth | Description |
|---|---|---|
GET /usage | Bearer | Query usage (filter by agent, model, date; group by agent, model, day) |
Model Naming & Resolution
When an agent makes an inference request, the model name goes through a resolution chain:- Requested model — the model name in the HTTP request body (
body.model). May be an alias or a direct model name. - Resolved model — after alias resolution. If the requested name is an alias defined in the agent’s model policy, it resolves to the target model name. Otherwise, the requested name passes through unchanged. Alias resolution is single-pass (no recursion).
- Provider model ID — after BYOK resolution. If the resolved model matches a user model backed by a provider connection, the provider-prefixed model ID (e.g.,
openai/gpt-4o-mini) is sent to the provider. This is the actual model identifier used for inference.
model_name— the resolved model name (step 2)requested_model— the original request name (step 1, may equalmodel_nameif no alias was used)provider_model_id— the provider-side identifier (step 3, null for denial paths and pre-BYOK errors)
model_aliases (a JSON object mapping alias to real model name). Alias targets must be in the policy’s allowed_models list.