docs/api.md

# User Service API

This document describes the HTTP surface of the user-service FastAPI app. The service powers provider discovery, chat orchestration, agent lifecycle management, demo generation, and deployment management. All routes are relative to the service root (e.g., `http://localhost:8000`).

## Authentication and headers
The auth provider is selected by `APP_ENV` (and the per-provider config under `auth/`). Three modes:
- **Dev (default):** session-cookie auth via the `dev_stub` provider. The browser-side login flow is `GET /auth/login/dev_stub` → backend picker → callback sets the `gofannon_sid` httpOnly cookie. API calls then carry the cookie automatically.
- **Real OAuth deployments:** the same session model with Google/Microsoft/GitHub/ASF/etc. providers in place of `dev_stub`. Same cookie carries the session.
- **Firebase deployments:** send `Authorization: Bearer <ID token>`; the token is verified with Firebase and the decoded user is attached to `request.state.user`.

Most routes rely on dependency injection for authorization (`get_current_user`); admin-only routes require `require_admin_access`.

## Error handling
- Standard FastAPI error responses are returned with a JSON body shaped as `{"detail": <message>}` when validation or downstream services fail.
- Background tasks (e.g., chat processing) store status and errors in the database; clients should poll for completion.

## Endpoint summary
- **Service metadata:** `GET /`, `GET /health`
- **Logging:** `POST /log/client`
- **Provider catalog:** `GET /providers`, `/providers/{provider}`, `/providers/{provider}/models`, `/providers/{provider}/models/{model}`
- **User profile & usage:** `GET /users/me`, `PUT /users/me/monthly-allowance`, `PUT /users/me/allowance-reset-date`, `PUT /users/me/spend-remaining`, `POST /users/me/usage`, `POST /users/me/reset-allowance`
- **Admin users:** `GET /admin/users`, `PUT /admin/users/{user_id}`
- **Chat:** `POST /chat`, `GET /chat/{ticket_id}`
- **Session configuration:** `POST /sessions/{session_id}/config`, `GET /sessions/{session_id}/config`, `DELETE /sessions/{session_id}`
- **Agents:** CRUD at `/agents` plus `POST /agents/generate-code`, `POST /agents/run-code`
- **Deployments:** `POST /agents/{agent_id}/deploy`, `DELETE /agents/{agent_id}/undeploy`, `GET /agents/{agent_id}/deployment`, `GET /deployments`, `POST /rest/{friendly_name}`
- **MCP connectors:** `POST /mcp/tools`
- **Specs:** `POST /specs/fetch`
- **Demos:** `POST /demos/generate-code`, CRUD at `/demos`

## Endpoint details

### Service metadata
- `GET /` → Simple heartbeat payload with service name.
- `GET /health` → `{ "status": "healthy", "service": "user-service" }` for readiness probes.

### Logging
- `POST /log/client`
  - Body: `{ "eventType": string, "message": string, "level": "INFO"|"WARN"|..., "metadata": object? }`
  - Behavior: Enriches metadata with `client_host` and `user_agent`, then writes to observability service. Returns `{ "status": "logged" }`.

### Provider catalog
- `GET /providers` → Map of provider configurations keyed by provider slug.
- `GET /providers/{provider}` → Provider config, 404 if missing.
- `GET /providers/{provider}/models` → List of model slugs for the provider.
- `GET /providers/{provider}/models/{model}` → Model configuration, 404 if provider or model missing.

### User profile & usage
- `GET /users/me` → Current user profile (`User` schema with `basicInfo`, `billingInfo`, `usageInfo`).
- `PUT /users/me/monthly-allowance`
  - Body: `{ "monthlyAllowance": number }`
  - Effect: Updates allowance limit.
- `PUT /users/me/allowance-reset-date`
  - Body: `{ "allowanceResetDate": number }`
  - Effect: Updates reset timestamp.
- `PUT /users/me/spend-remaining`
  - Body: `{ "spendRemaining": number }`
  - Effect: Updates remaining spend.
- `POST /users/me/usage`
  - Body: `{ "responseCost": number, "metadata"?: object }`
  - Effect: Appends usage entry and updates spend remaining.
- `POST /users/me/reset-allowance` → Resets usage tracking for the current user.

### Admin users
- `GET /admin/users` → Lists all users (admin-only dependency).
- `PUT /admin/users/{user_id}`
  - Body: any combination of `monthlyAllowance`, `allowanceResetDate`, `spendRemaining`.
  - Effect: Updates targeted user's usage info (admin-only).

### Chat
- `POST /chat`
  - Body: `ChatRequest` containing `messages` (role `user|assistant|system`), `provider`, `model`, optional `parameters`, and `builtInTools`.
  - Effect: Queues background chat processing and returns `{ "ticket_id": <uuid>, "status": "pending" }`.
- `GET /chat/{ticket_id}` → `ChatResponse` with `status`, `result`, and `error` once processing completes.

### Session configuration
- `POST /sessions/{session_id}/config`
  - Body: `ProviderConfig` (`provider`, `model`, `parameters`).
  - Effect: Creates or updates session document and returns confirmation.
- `GET /sessions/{session_id}/config` → Stored `provider_config` for the session.
- `DELETE /sessions/{session_id}` → Deletes session and returns `{ "message": "Session deleted" }`.

### Agents
- `POST /agents`
  - Body: `CreateAgentRequest` (name, description, code, optional `friendlyName`, tool metadata, schemas, invokable models, composer metadata).
  - Effect: Persists agent and returns saved `Agent` with `_id` and `_rev`.
- `GET /agents` → List of all agents.
- `GET /agents/{agent_id}` → Single agent document.
- `PUT /agents/{agent_id}`
  - Body: `UpdateAgentRequest` (partial updates across the same fields as creation).
  - Effect: Merges with existing document, preserves creation metadata, returns updated agent.
- `DELETE /agents/{agent_id}` → Deletes agent, 204 on success.
- `POST /agents/generate-code`
  - Body: `GenerateCodeRequest` (description, `tools`, input/output schemas, composer `modelConfig`, optional swagger specs and invokable models).
  - Effect: Returns generated agent code and metadata.
- `POST /agents/run-code`
  - Body: `RunCodeRequest` (`code`, `inputDict`, `tools`, optional `gofannonAgents`).
  - Effect: Executes code in sandbox; response contains `result` or raises with logged failure details.

### Deployments
- `POST /agents/{agent_id}/deploy` → Registers agent for REST exposure; 201 with deployment info.
- `DELETE /agents/{agent_id}/undeploy` → Removes deployment; 204 on success.
- `GET /agents/{agent_id}/deployment` → Deployment metadata for the agent, or 404 if not deployed.
- `GET /deployments` → List of deployed APIs (`DeployedApi` objects).
- `POST /rest/{friendly_name}` → Runs a deployed agent by its public name using the JSON body as `input_dict`.

### Specs
- `POST /specs/fetch`
  - Body: `{ "url": string }`
  - Effect: Fetches and returns OpenAPI/Swagger spec content from a remote URL.

### MCP connectors
- `POST /mcp/tools`
  - Body: `{ "mcp_url": string, "auth_token"?: string }`
  - Effect: Connects to a remote MCP server and returns `{ "mcp_url": ..., "tools": [...] }`.

### Demo apps
- `POST /demos/generate-code`
  - Body: `GenerateDemoCodeRequest` (user prompt, selected deployed APIs, composer `modelConfig`, optional `builtInTools`).
  - Effect: Returns generated `html`, `css`, `js`, and optional `thoughts`.
- `POST /demos`
  - Body: `CreateDemoAppRequest` (name, description, selected APIs, composer config, prompt, generated code, optional composer thoughts).
  - Effect: Saves a demo app and returns the stored `DemoApp`.
- `GET /demos` → List of saved demo apps.
- `GET /demos/{demo_id}` → Single demo app.
- `PUT /demos/{demo_id}` → Replace demo app content using the same schema as creation.
- `DELETE /demos/{demo_id}` → Deletes demo app, 204 on success.