You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Complete reference matrix of all API endpoints across Jan Server services.
Overview
This document provides a comprehensive matrix of all available API endpoints, their HTTP methods, authentication requirements, and descriptions. Use this to understand complete API coverage across all services.
Legend
Symbol
Meaning
✅
Fully Implemented & Documented
⚠️
Implemented but Limited Documentation
🔒
Requires Authentication
❌
No Authentication Required
LLM API Endpoints
Base URL:http://localhost:8080 (or http://localhost:8000/v1 via Kong)
Authentication
Endpoint
Method
Auth
Status
Description
/auth/guest-login
POST
❌
✅
Request guest token without credentials
/auth/register
POST
❌
✅
Register a new user
/auth/login
GET
❌
✅
Initiate Keycloak OAuth login flow
/auth/callback
GET
❌
✅
OAuth callback handler
/auth/logout
GET/POST
🔒
✅
Logout current session
/auth/refresh-token
POST
❌
✅
Refresh access token
/auth/validate
POST
❌
✅
Validate a Keycloak access token
/auth/revoke
POST
❌
✅
Revoke a Keycloak refresh token
/auth/upgrade
POST
🔒
✅
Upgrade guest account to permanent
/auth/me
GET
🔒
✅
Get current user profile
/auth/api-keys
GET
🔒
✅
List user's API keys
/auth/api-keys
POST
🔒
✅
Create new API key
/auth/api-keys/{id}
DELETE
🔒
✅
Revoke API key
/auth/system-key
POST
🔒
✅
Get or create the internal system key
Chat Completions
Endpoint
Method
Auth
Status
Description
/v1/chat/completions
POST
🔒
✅
Send message, get AI response (streaming supported)
Base URL:http://localhost:8082 (service paths shown below are under /v1).
Via Kong the /responses route uses strip_path, so a service path like /v1/responses
is reached at http://localhost:8000/responses/v1/responses. The /v1/artifacts and
/v1/agents routes are not stripped and are reached at their path directly.
Response Execution
Endpoint
Method
Auth
Status
Description
/v1/responses
POST
🔒
✅
Create response (multi-step tool orchestration)
/v1/responses/{response_id}
GET
🔒
✅
Get response details and execution status
/v1/responses/{response_id}/full
GET
🔒
✅
Get response with full execution detail
/v1/responses/{response_id}
DELETE
🔒
✅
Delete response
/v1/responses/{response_id}/cancel
POST
🔒
✅
Cancel an in-progress response
/v1/responses/{response_id}/retry
POST
🔒
✅
Retry a failed response
/v1/responses/{response_id}/input_items
GET
🔒
✅
List input items for a response
Webhooks are not a CRUD API. To receive a callback when a background response
completes, pass metadata.webhook_url in the create-response request.
Plan (nested under a response)
Endpoint
Method
Auth
Status
Description
/v1/responses/{response_id}/plan
GET
🔒
✅
Get the execution plan
/v1/responses/{response_id}/plan/details
GET
🔒
✅
Get plan with step details
/v1/responses/{response_id}/plan/progress
GET
🔒
✅
Get plan progress
/v1/responses/{response_id}/plan/cancel
POST
🔒
✅
Cancel plan execution
/v1/responses/{response_id}/plan/input
POST
🔒
✅
Submit user input to a waiting plan
/v1/responses/{response_id}/plan/tasks
GET
🔒
✅
List plan tasks
Artifacts
Endpoint
Method
Auth
Status
Description
/v1/artifacts
GET
🔒
✅
List artifacts for the current user
/v1/artifacts/{artifact_id}
GET
🔒
✅
Get artifact
/v1/artifacts/{artifact_id}/versions
GET
🔒
✅
List artifact versions
/v1/artifacts/{artifact_id}/download
GET
🔒
✅
Download artifact content
/v1/artifacts/{artifact_id}
DELETE
🔒
✅
Delete artifact
/v1/responses/{response_id}/artifacts
GET
🔒
✅
List artifacts for a response
/v1/responses/{response_id}/artifacts/latest
GET
🔒
✅
Get the latest artifact for response
Agent Discovery
Endpoint
Method
Auth
Status
Description
/v1/agents
GET
🔒
✅
List available agents
/v1/agents/capabilities
GET
🔒
✅
List agent capabilities
/v1/agents/{type}
GET
🔒
✅
Get agent by type
/v1/agents/{type}/schema
GET
🔒
✅
Get agent input schema
Health & Status
Endpoint
Method
Auth
Status
Description
/healthz
GET
❌
✅
Service health check
Media API Endpoints
Base URL:http://localhost:8285 (via Kong: /media for management, /api/media for public serving)
Media Operations
Endpoint
Method
Auth
Status
Description
/v1/media
POST
🔒
✅
Ingest a data URL or remote URL; returns the jan_* ID
/v1/media/upload
POST
🔒
✅
Multipart file upload; returns the jan_* ID
/v1/media/{id}
GET
🔒
✅
Stream media bytes (or a direct URL if proxying is disabled)
/v1/media/{id}/metadata
GET
🔒
✅
Get media metadata (id, url, content_type, filename, size)
/api/media/{id}
GET
❌
✅
Public read-only serving via Kong (used in img src)
/v1/files, /v1/files/upload, /v1/files/{id}, and /v1/files/{id}/metadata are
registered as aliases of the /v1/media* routes above.
There is no presigned-upload, resolve, or bulk-delete endpoint.
Health & Status
Endpoint
Method
Auth
Status
Description
/healthz
GET
❌
✅
Service health check
MCP Tools API Endpoints
Base URL:http://localhost:8091
Tool Operations
All tools are exposed through a single JSON-RPC 2.0 endpoint. The method (tools/list,
tools/call, initialize, ping, etc.) is selected via the request body, not the URL path.
Endpoint
Method
Auth
Status
Description
/v1/mcp
POST
🔒
✅
JSON-RPC 2.0 endpoint for all MCP methods (tools/list, tools/call)
Via Kong this is reached at POST /mcp. Search uses a provider fallback chain:
Serper -> Exa -> Tavily -> SearXNG.
Admin Tools (managed in LLM API)
MCP tool admin configuration lives in the LLM API, not the MCP Tools service.
Endpoint
Method
Auth
Status
Description
/v1/admin/mcp-tools
GET
🔒
✅
List MCP tools with admin config
/v1/admin/mcp-tools/{id}
GET
🔒
✅
Get tool admin configuration
/v1/admin/mcp-tools/{id}
PATCH
🔒
✅
Update tool enable/disable status
Health & Status
Endpoint
Method
Auth
Status
Description
/healthz
GET
❌
✅
Service health check
Template API
template-api is a scaffold/reference service used as the starting point for new
microservices (jan-cli dev scaffold). It is not part of the running platform
and is not routed through Kong, so its endpoints are intentionally omitted from this inventory.
Summary Statistics
By Service
Service
Status
LLM API
✅ Comprehensive (auth, chat, conversations, …)
Response API
✅ Responses, plan, artifacts, agent discovery
Media API
✅ Ingest, upload, fetch, metadata
MCP Tools
✅ Single JSON-RPC endpoint
Template API
Scaffold only (not routed)
API Versioning
All endpoints use path-based versioning:
/v1/ ← Current production version
/v2/ ← Future version (not yet available)
Breaking changes only occur in major version increments.
Rate limits are enforced by the Kong gateway in all environments (global limit plus
per-route overrides). See the rate-limit table in the
API Reference and the source of truth,
integrations/kong/kong.yml.