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

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). 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), 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) 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) 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) 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) 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) 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) 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) 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), 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

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

Response:

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

2. Retrieve a Specific Session

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

3. Search Messages

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

Response:

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

4. Export as Markdown

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

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

Response:

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

6. Retrieve OpenAPI Specification

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

7. Subscribe to Real-Time Events

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

8. Health Check

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.
• Core Resources: Sessions and messages support full CRUD operations, with search powered by SQLite FTS5 in search.go.
• Data Portability: Export endpoints in export.go support Markdown and JSON formats; import functionality resides in 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) support operational monitoring and API discovery.
• Architecture: Huma router in 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.

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 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 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 and maintains persistent connections for live data feeds.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}