API Reference

GNETiX exposes a REST API for all portal functionality. The API is served by the FastAPI backend and follows standard REST conventions.

Authentication

All endpoints except those marked as Public require a valid JWT Bearer token in the Authorization header:

curl -H "Authorization: Bearer <access_token>" \
     https://api.gnetix.ai/api/users

Tokens are obtained via the /api/auth/login endpoint and are valid for 15 minutes. Use /api/auth/refresh with a refresh token (valid for 7 days) to obtain new access tokens without re-authenticating.

Cross-Org Access

MSP admins and superusers can operate on behalf of another organization by including the X-Org-Id header:

curl -H "Authorization: Bearer <token>" \
     -H "X-Org-Id: <target-org-uuid>" \
     https://api.gnetix.ai/api/users

Without this header, requests are scoped to the authenticated user's own organization.

Auth

Method	Path	Description	Auth
`POST`	`/api/auth/register`	Register a new account	Public
`POST`	`/api/auth/login`	Log in and receive tokens	Public
`POST`	`/api/auth/refresh`	Refresh an access token	Public
`GET`	`/api/auth/me`	Get current user profile	Required
`POST`	`/api/auth/logout`	Invalidate current session	Required
`POST`	`/api/auth/forgot-password`	Request a password reset email	Public
`POST`	`/api/auth/reset-password`	Reset password with token	Public

Organizations

Method	Path	Description	Auth
`GET`	`/api/org`	Get current user's org	Required
`PUT`	`/api/org`	Update current org settings	Required
`GET`	`/api/orgs`	List all orgs (superuser/MSP)	Required
`POST`	`/api/orgs`	Create a new organization	Required
`GET`	`/api/orgs/slug/{slug}`	Get org by slug	Required
`GET`	`/api/orgs/{org_id}`	Get org by ID	Required
`PUT`	`/api/orgs/{org_id}`	Update org by ID	Required
`DELETE`	`/api/orgs/{org_id}`	Delete an organization	Required

Duo Configuration

Method	Path	Description	Auth
`GET`	`/api/org/duo`	Get Duo MFA config for current org	Required
`PUT`	`/api/org/duo`	Set Duo MFA config	Required
`DELETE`	`/api/org/duo`	Remove Duo MFA config	Required

Users

Method	Path	Description	Auth
`GET`	`/api/users`	List users in current org	Required
`GET`	`/api/users/{user_id}`	Get user by ID	Required
`POST`	`/api/users`	Create a new user	Required
`PATCH`	`/api/users/{user_id}`	Update user profile	Required
`DELETE`	`/api/users/{user_id}`	Delete a user	Required
`POST`	`/api/users/{user_id}/admin-reset-password`	Admin-initiated password reset	Required
`PUT`	`/api/users/{user_id}/password`	Change user password (self-service)	Required

Agents

Method	Path	Description	Auth
`GET`	`/api/agents`	List agents in current org	Required
`POST`	`/api/agents/token`	Generate agent call-home token	Required
`POST`	`/api/register`	Register an agent (agent call-home)	Agent Token
`PATCH`	`/api/agents/{agent_id}`	Update agent settings	Required
`DELETE`	`/api/agents/{agent_id}`	Delete an agent	Required
`POST`	`/api/agents/{agent_id}/push`	Push a command to an agent	Required
`GET`	`/api/agents/{agent_id}/mcp/capabilities`	Get agent MCP capabilities	Required
`POST`	`/api/agents/{agent_id}/mcp/call-tool`	Call a tool via agent relay	Required
`POST`	`/api/agents/{agent_id}/mcp/read-resource`	Read a resource via agent	Required
`POST`	`/api/agents/{agent_id}/mcp/get-prompt`	Get a prompt via agent	Required
`POST`	`/api/agents/{agent_id}/chat`	Send a chat message to agent	Required

MCP Servers

Method	Path	Description	Auth
`GET`	`/api/mcp-servers`	List MCP servers	Required
`POST`	`/api/mcp-servers`	Register an MCP server	Required
`GET`	`/api/mcp-servers/{server_id}`	Get server details	Required
`PATCH`	`/api/mcp-servers/{server_id}`	Update server settings	Required
`DELETE`	`/api/mcp-servers/{server_id}`	Delete a server	Required
`POST`	`/api/mcp-servers/{server_id}/generate-oauth-credentials`	Generate OAuth client credentials	Required
`GET`	`/api/mcp-servers/{server_id}/tools`	List tools on server (live)	Required
`GET`	`/api/mcp-servers/{server_id}/capabilities`	Get server capabilities (live)	Required
`POST`	`/api/mcp-servers/{server_id}/sync-tools`	Sync tools to catalog	Required
`GET`	`/api/mcp-servers/{server_id}/catalog`	List cataloged tools	Required
`POST`	`/api/mcp-servers/{server_id}/call-tool`	Call a tool on the server	Required
`POST`	`/api/mcp-servers/{server_id}/read-resource`	Read a resource	Required
`POST`	`/api/mcp-servers/{server_id}/get-prompt`	Get a prompt	Required

Agent-Server Assignments

Method	Path	Description	Auth
`GET`	`/api/agents/{agent_id}/mcp-servers`	List servers assigned to agent	Required
`PUT`	`/api/agents/{agent_id}/mcp-servers`	Set servers assigned to agent	Required

Config

Messaging Providers

Method	Path	Description	Auth
`GET`	`/api/config/messaging/{provider}`	Get provider config (webex/slack/teams)	Required
`PUT`	`/api/config/messaging/{provider}`	Set provider config	Required
`DELETE`	`/api/config/messaging/{provider}`	Remove provider config	Required

Director / LLM

Method	Path	Description	Auth
`GET`	`/api/config/director`	Get Director configuration	Required
`PUT`	`/api/config/director/system-prompt`	Update system prompt	Required
`PUT`	`/api/config/director/extended-thinking`	Toggle extended thinking	Required
`GET`	`/api/config/llm-providers`	List configured LLM providers	Required
`POST`	`/api/config/llm-providers`	Add an LLM provider	Required
`PUT`	`/api/config/llm-providers/{provider_id}/activate`	Activate a provider	Required
`DELETE`	`/api/config/llm-providers/{provider_id}`	Remove a provider	Required
`PUT`	`/api/config/llm-providers/budget`	Set LLM budget limits	Required
`POST`	`/api/config/director/chat`	Send a test chat message	Required
`POST`	`/api/config/director/chat/stream`	Stream a test chat response	Required

Speech

Method	Path	Description	Auth
`POST`	`/api/config/tts`	Text-to-speech synthesis	Required
`POST`	`/api/config/stt`	Speech-to-text transcription	Required

Webhooks

Method	Path	Description	Auth
`GET`	`/api/webhooks`	List webhook endpoints	Required
`POST`	`/api/webhooks`	Create a webhook endpoint	Required
`PATCH`	`/api/webhooks/{webhook_id}`	Update a webhook	Required
`DELETE`	`/api/webhooks/{webhook_id}`	Delete a webhook	Required
`POST`	`/api/webhooks/{webhook_id}/rotate-secret`	Rotate signing secret	Required
`GET`	`/api/webhooks/{webhook_id}/events`	List webhook events	Required
`GET`	`/api/webhooks/{webhook_id}/events/stream`	SSE stream of events	Required
`GET`	`/api/webhooks/stats`	Get webhook statistics	Required

Webhook ingest endpoints (where external systems POST events) use a separate URL path with HMAC authentication, not JWT.

Pipeline / Traces

Method	Path	Description	Auth
`GET`	`/api/traces/recent`	List recent traces	Required
`GET`	`/api/traces/{trace_id}`	Get a specific trace	Required
`GET`	`/api/traces/stream`	SSE stream of trace events	Required

Voice

Method	Path	Description	Auth
`POST`	`/api/voice/chat`	Send a voice chat message	Required
`POST`	`/api/voice/call`	Initiate an outbound voice call	Required

Additional Endpoints

Health

Method	Path	Description	Auth
`GET`	`/health`	Health check with migration version	Public

Activity

Method	Path	Description	Auth
`GET`	`/api/activity/*`	Activity feed endpoints	Required

Usage

Method	Path	Description	Auth
`GET`	`/api/usage/*`	LLM usage and cost tracking	Required

Method	Path	Description	Auth
`GET/POST/PATCH/DELETE`	`/api/tags/*`	Tag management	Required
`GET/POST/PATCH/DELETE`	`/api/tag-groups/*`	Tag group management	Required

Souls (Agent Personas)

Method	Path	Description	Auth
`GET/POST/PATCH/DELETE`	`/api/souls/*`	Agent persona management	Required

Guardrails

Method	Path	Description	Auth
`GET/POST/PATCH/DELETE`	`/api/guardrails/*`	Content guardrail rules	Required

Audit Logs

Method	Path	Description	Auth
`GET`	`/api/audit-logs/*`	Audit log queries	Required

Tool Logs

Method	Path	Description	Auth
`GET`	`/api/tool-logs/*`	Tool invocation audit logs	Required

MSP

Method	Path	Description	Auth
`GET/PUT`	`/api/msp/*`	MSP relationship management	Required

User Phones

Method	Path	Description	Auth
`GET/POST/PATCH/DELETE`	`/api/user-phones/*`	User phone number management	Required