Skip to main content

​
Quickstart

This guide walks through the core Hill90 workflow: creating an agent, configuring model access, and querying agent knowledge and usage.

​
Prerequisites

  • A modern web browser
  • An account on the Hill90 platform (contact the administrator)
  • For API access: a tool like curl, Postman, or any HTTP client

​
Accessing the Platform

The Hill90 UI is available at hill90.com. Sign in with your Keycloak credentials to access the dashboard.

​
1. Health Check

Verify the API is running (no authentication required): 
curl https://api.hill90.com/health

{
  "status": "healthy",
  "service": "api"
}

​
2. Authenticate

For all remaining calls, include your Keycloak JWT bearer token: 
export TOKEN="YOUR_JWT_TOKEN"
See Authentication for details on obtaining tokens.

​
3. Create an Agent

Define an agent with a unique slug, name, and optional identity documents: 
curl -X POST https://api.hill90.com/agents \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "my-first-agent",
    "name": "My First Agent",
    "description": "A test agent",
    "soul_md": "You are a helpful research assistant.",
    "rules_md": "Always cite your sources."
  }'

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_id": "my-first-agent",
  "name": "My First Agent",
  "status": "stopped",
  ...
}

​
4. Create a Provider Connection

Register your LLM provider API key. The key is encrypted at rest and never returned in responses: 
curl -X POST https://api.hill90.com/provider-connections \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My OpenAI Key",
    "provider": "openai",
    "api_key": "sk-..."
  }'

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "name": "My OpenAI Key",
  "provider": "openai",
  "is_valid": null,
  ...
}

​
5. Create a User Model

Define a model that references your provider connection: 
curl -X POST https://api.hill90.com/user-models \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-gpt4o",
    "connection_id": "660e8400-e29b-41d4-a716-446655440001",
    "litellm_model": "openai/gpt-4o"
  }'

​
6. Assign Models to Your Agent

Update the agent with direct model assignment: 
curl -X PUT https://api.hill90.com/agents/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model_names": ["my-gpt4o"]
  }'

​
7. Start the Agent

Start the agent container (requires admin role): 
curl -X POST https://api.hill90.com/agents/550e8400-e29b-41d4-a716-446655440000/start \
  -H "Authorization: Bearer $TOKEN"

{
  "status": "running",
  "container_id": "abc123..."
}
The agent is now running in a sandboxed container with access to LLM inference (via assigned models) and persistent knowledge storage.

​
8. Browse Agent Knowledge

After the agent runs, browse what it has learned: 
# List agents with knowledge entries
curl -H "Authorization: Bearer $TOKEN" \
  https://api.hill90.com/knowledge/agents

# List entries for a specific agent
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.hill90.com/knowledge/entries?agent_id=my-first-agent"

# Search across knowledge
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.hill90.com/knowledge/search?q=research+findings"

​
9. Query Usage

Check how much the agent has consumed: 
# Summary of today's usage
curl -H "Authorization: Bearer $TOKEN" \
  https://api.hill90.com/usage

# Usage grouped by model
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.hill90.com/usage?group_by=model"

{
  "total_requests": 42,
  "successful_requests": 40,
  "total_input_tokens": 15000,
  "total_output_tokens": 8000,
  "total_tokens": 23000,
  "total_cost_usd": 0.035
}

​
Next Steps