# How to Use the AgentsView API: Query, Search, and Export AI Agent Sessions

> Learn how to use the AgentsView API to query, search, and export AI agent sessions. This guide covers CRUD operations, full-text search with SQLite FTS5, and real-time event streaming.

- Repository: [Kenn Software/agentsview](https://github.com/kenn-io/agentsview)
- Tags: api-reference
- Published: 2026-07-01

---

**AgentsView provides a token-protected HTTP API built with Go and the Huma router that enables full CRUD operations on AI agent sessions, full-text search via SQLite FTS5, and real-time event streaming, all accessible under the `/api/v1/` base path.**

The AgentsView API is the programmatic interface for the `kenn-io/agentsview` open-source project, a Go-based server that stores AI agent interaction data in SQLite or PostgreSQL. It exposes OpenAPI-compatible endpoints that allow you to query session history, export conversation data, and subscribe to real-time updates, making it straightforward to integrate agent telemetry into external dashboards or automation pipelines.

## Authentication and Security

All API endpoints require Bearer token authentication. Set the `Authorization` header to `Bearer <TOKEN>`, where `<TOKEN>` is either the value of the `AGENTSVIEW_TOKEN` environment variable or a token generated via the `agentsview token` CLI command.

Token validation is implemented in [[`internal/server/auth.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/auth.go)](https://github.com/kenn-io/agentsview/blob/main/internal/server/auth.go). The middleware parses the header and validates against the configured secret before allowing access to any protected resource.

## Core API Endpoints

The API is organized into logical resource groups under the base path `http://localhost:<port>/api/v1/`. Route definitions are scattered across the `internal/server/` directory, with each domain handling specific concerns.

### Sessions Management

The **Sessions** endpoints provide CRUD operations for agent interaction logs. You can list, retrieve, create, delete, and update session records.

Available routes:
- `GET /sessions` – List all sessions with pagination (`limit`, `offset` parameters)
- `GET /sessions/{id}` – Retrieve a specific session by UUID
- `POST /sessions` – Create a new session
- `PATCH /sessions/{id}` – Partial update of session metadata
- `DELETE /sessions/{id}` – Remove a session and its associated data

Implementation resides in [[`internal/server/huma_routes_sessions.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/huma_routes_sessions.go)](https://github.com/kenn-io/agentsview/blob/main/internal/server/huma_routes_sessions.go), which uses the Huma router to declare type-safe handlers.

### Messages Access

Messages belonging to a session are accessible via:
- `GET /sessions/{id}/messages` – Retrieve all messages for a specific session
- `GET /messages/{msgID}` – Fetch a specific message by its identifier

These routes allow you to reconstruct conversation flows and analyze individual agent responses.

### Full-Text Search

The **Search** endpoint provides FTS5-powered full-text search across all session content using SQLite's built-in full-text search capabilities.

- `GET /search?q=<query>&limit=<n>` – Search across all messages and session metadata

The search implementation in [[`internal/server/search.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/search.go)](https://github.com/kenn-io/agentsview/blob/main/internal/server/search.go) leverages SQLite FTS5 for efficient inverted indexing, returning ranked matches with context snippets.

### Export and Import

You can extract session data for offline analysis or backup purposes:

- `GET /sessions/{id}/export?format=md|json` – Export a session as Markdown or JSON
- `POST /import` – Import a previously exported session dump

The export handlers in [[`internal/server/export.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/export.go)](https://github.com/kenn-io/agentsview/blob/main/internal/server/export.go) generate `text/markdown` or `application/json` responses based on the `Accept` header and `format` query parameter. The import logic in [[`internal/server/import.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/import.go)](https://github.com/kenn-io/agentsview/blob/main/internal/server/import.go) validates and ingests JSON session dumps.

### Insights and Analytics

Aggregate statistics are available through:
- `GET /insights` – High-level aggregated statistics
- `GET /analytics` – Detailed trend data and metrics
- `GET /activity` – Real-time activity reporting
- `GET /usage` – Session usage metrics

These endpoints are implemented in [[`internal/server/analytics.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/analytics.go)](https://github.com/kenn-io/agentsview/blob/main/internal/server/analytics.go) and provide the data necessary for monitoring agent performance and usage patterns.

### Pins and Settings

Session management utilities include:
- `POST /pins/{id}` and `DELETE /pins/{id}` – Pin or unpin sessions for quick access
- `GET /settings` and `PATCH /settings` – Read and modify user-level configuration

## Real-Time Features

### Server-Sent Events (SSE)

Subscribe to live updates via the `/events` endpoint, which streams JSON-encoded events as they occur. The server pushes event types such as `session.created`, `message.added`, and `search.completed` to connected clients.

The SSE implementation in [[`internal/server/events.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/events.go)](https://github.com/kenn-io/agentsview/blob/main/internal/server/events.go) manages client connections and broadcasts database changes in real-time.

## Health and Observability

The API exposes standard Kubernetes-compatible health checks:
- `GET /healthz` – Liveness probe (returns 200 OK when the server is running)
- `GET /readyz` – Readiness probe (indicates the database connection is established)

These endpoints are defined in [[`internal/server/health.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/health.go)](https://github.com/kenn-io/agentsview/blob/main/internal/server/health.go) and are essential for container orchestration and load balancer health checks.

For machine-readable API documentation, access `GET /openapi.json`. The OpenAPI specification is generated dynamically by [[`internal/server/openapi.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/openapi.go)](https://github.com/kenn-io/agentsview/blob/main/internal/server/openapi.go) and can be consumed by Swagger UI or Redoc for interactive exploration.

## Architecture and Implementation Details

The server uses **Huma** (`github.com/danielgtaylor/huma`) as its HTTP router and framework. Route registration occurs in [[`internal/server/server.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/server.go)](https://github.com/kenn-io/agentsview/blob/main/internal/server/server.go), which initializes the router with `huma.NewRouter` and mounts all sub-routers under the `/api/v1/` prefix.

Database access is abstracted in the `internal/db/` package, with SQLite FTS5 handling the full-text search capabilities. All error responses follow the RFC 7807 "Problem Details" format, containing `type`, `title`, `status`, and `detail` fields for consistent client-side error handling.

## Practical Code Examples

### 1. List All Sessions

```bash
curl -s -H "Authorization: Bearer <TOKEN>" \
     "http://localhost:<PORT>/api/v1/sessions?limit=20"

```

Response:

```json
{
  "sessions": [
    {
      "id": "c8f8a1e2-3d4b-4f5a-9b8c-2d5e6f7a8b9c",
      "agent": "autogpt",
      "title": "Research project",
      "created_at": "2024-10-01T12:34:56Z"
    }
  ]
}

```

### 2. Retrieve a Specific Session

```bash
curl -s -H "Authorization: Bearer <TOKEN>" \
     "http://localhost:<PORT>/api/v1/sessions/c8f8a1e2-3d4b-4f5a-9b8c-2d5e6f7a8b9c"

```

### 3. Search Messages

```bash
curl -s -H "Authorization: Bearer <TOKEN>" \
     "http://localhost:<PORT>/api/v1/search?q=budget%20forecast&limit=5"

```

Response:

```json
{
  "matches": [
    {
      "session_id": "c8f8a1e2-3d4b-4f5a-9b8c-2d5e6f7a8b9c",
      "message_id": "m1",
      "snippet": "The projected budget for Q4 is ..."
    }
  ]
}

```

### 4. Export as Markdown

```bash
curl -s -H "Authorization: Bearer <TOKEN>" \
     -H "Accept: text/markdown" \
     "http://localhost:<PORT>/api/v1/sessions/c8f8a1e2-3d4b-4f5a-9b8c-2d5e6f7a8b9c/export?format=md" \
     -o session.md

```

### 5. Import a Session

```bash
curl -s -X POST -H "Authorization: Bearer <TOKEN>" \
     -H "Content-Type: application/json" \
     --data @session.json \
     "http://localhost:<PORT>/api/v1/import"

```

Response:

```json
{
  "status": "imported",
  "session_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
}

```

### 6. Retrieve OpenAPI Specification

```bash
curl -s "http://localhost:<PORT>/api/v1/openapi.json" | jq .

```

### 7. Subscribe to Real-Time Events

```bash
curl -N -H "Authorization: Bearer <TOKEN>" \
     "http://localhost:<PORT>/api/v1/events"

```

### 8. Health Check

```bash
curl -s "http://localhost:<PORT>/api/v1/healthz"

```

## Summary

- **Authentication**: Bearer token strategy via `Authorization` header, configured through `AGENTSVIEW_TOKEN` or CLI-generated tokens in [`auth.go`](https://github.com/kenn-io/agentsview/blob/main/auth.go).
- **Core Resources**: Sessions and messages support full CRUD operations, with search powered by SQLite FTS5 in [`search.go`](https://github.com/kenn-io/agentsview/blob/main/search.go).
- **Data Portability**: Export endpoints in [`export.go`](https://github.com/kenn-io/agentsview/blob/main/export.go) support Markdown and JSON formats; import functionality resides in [`import.go`](https://github.com/kenn-io/agentsview/blob/main/import.go).
- **Real-Time Features**: SSE stream at `/events` provides live updates for session and message changes.
- **Observability**: Health checks (`healthz`, `readyz`) and OpenAPI generation ([`openapi.go`](https://github.com/kenn-io/agentsview/blob/main/openapi.go)) support operational monitoring and API discovery.
- **Architecture**: Huma router in [`server.go`](https://github.com/kenn-io/agentsview/blob/main/server.go) provides type-safe OpenAPI-compatible routing with RFC 7807 error responses.

## Frequently Asked Questions

### What authentication method does the AgentsView API use?

The API employs a simple Bearer token scheme. You must include an `Authorization: Bearer <TOKEN>` header with every request, where the token matches either the `AGENTSVIEW_TOKEN` environment variable or a token generated by the `agentsview token` CLI command. The validation logic is centralized in [`internal/server/auth.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/auth.go).

### How does the full-text search functionality work?

Search utilizes SQLite FTS5 (Full-Text Search version 5) to index session content and messages. The `GET /search` endpoint accepts a `q` parameter for query strings and returns ranked results with context snippets. This implementation is located in [`internal/server/search.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/search.go) and supports efficient querying even across large conversation histories.

### Can I export session data in formats other than JSON?

Yes. The export endpoint supports both JSON and Markdown formats. Specify the desired format using the `format` query parameter (`md` or `json`) or the `Accept` header (`text/markdown` or `application/json`). The export handlers in [`internal/server/export.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/export.go) format the conversation data appropriately for each content type.

### How do I subscribe to real-time session updates?

Connect to the `/events` endpoint using a client that supports Server-Sent Events (SSE), such as `curl -N` or JavaScript's `EventSource`. The server streams JSON-encoded events including `session.created`, `message.added`, and `search.completed` as they occur. This functionality is implemented in [`internal/server/events.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/events.go) and maintains persistent connections for live data feeds.