> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hill90.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get started with the Hill90 platform.

# 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](https://hill90.com). Sign in with your Keycloak credentials to access the dashboard.

## 1. Health Check

Verify the API is running (no authentication required):

```bash theme={null}
curl https://api.hill90.com/health
```

```json theme={null}
{
  "status": "healthy",
  "service": "api"
}
```

## 2. Authenticate

For all remaining calls, include your Keycloak JWT bearer token:

```bash theme={null}
export TOKEN="YOUR_JWT_TOKEN"
```

See [Authentication](/getting-started/authentication) for details on obtaining tokens.

## 3. Create an Agent

Define an agent with a unique slug, name, and optional identity documents:

```bash theme={null}
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."
  }'
```

```json theme={null}
{
  "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:

```bash theme={null}
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-..."
  }'
```

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
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):

```bash theme={null}
curl -X POST https://api.hill90.com/agents/550e8400-e29b-41d4-a716-446655440000/start \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "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:

```bash theme={null}
# 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:

```bash theme={null}
# 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"
```

```json theme={null}
{
  "total_requests": 42,
  "successful_requests": 40,
  "total_input_tokens": 15000,
  "total_output_tokens": 8000,
  "total_tokens": 23000,
  "total_cost_usd": 0.035
}
```

## Next Steps

* [Authentication](/getting-started/authentication) — Learn how to obtain and use JWT tokens
* [API Reference](/api-reference/overview) — Explore all available endpoints
* [Knowledge API](/api-reference/knowledge) — Browse agent knowledge entries
* [Architecture](/architecture/overview) — Understand the platform architecture