API Overview

cogmem-kos exposes a REST API via FastAPI.

Base URL

http://localhost:8000

Authentication

Authentication is not implemented in v1. All endpoints are open. Future versions will support API keys and OAuth.

Endpoints

Method	Endpoint	Description
`POST`	`/search`	Execute a search query
`GET`	`/items/{id}`	Get an item with passages
`POST`	`/items`	Create a new item
`GET`	`/entities/{id}`	Get entity page
`GET`	`/admin/health`	Health check

Common Parameters

Tenant ID

All queries require a tenant_id for multi-tenant isolation:

{
  "tenant_id": "my-tenant"
}

User ID

Optional user_id for user-level scoping:

{
  "tenant_id": "my-tenant",
  "user_id": "user-123"
}

Response Format

All responses are JSON with consistent structure:

Success

{
  "hits": [...],
  "total": 42,
  "took_ms": 23
}

Error

{
  "detail": "Error message"
}

Rate Limits

No rate limits in v1. Production deployments should add rate limiting via API gateway.

OpenAPI Spec

The OpenAPI specification is available at:

http://localhost:8000/openapi.json

Interactive docs:

http://localhost:8000/docs

Next Steps

Search

Search endpoint details

Items

Item CRUD operations

Entities

Entity page endpoint

Health

Health check endpoint

​API Overview

​Base URL

​Authentication

​Endpoints

​Common Parameters

​Tenant ID

​User ID

​Response Format

​Success

​Error

​Rate Limits

​OpenAPI Spec

​Next Steps

Search

Items

Entities

Health

API Overview

Base URL

Authentication

Endpoints

Common Parameters

Tenant ID

User ID

Response Format

Success

Error

Rate Limits

OpenAPI Spec

Next Steps