# Evie (In-App Agent)

Evie is the conversational AI assistant embedded in the TrustPager CRM sidebar. These endpoints are separate from the standard /api/v1 gateway and use OAuth tokens minted specifically for the in-app agent.

**Base URL:** `https://api.trustpager.com/functions/v1/api/v1`

## Endpoints

### POST /evie-grant

Mint an Evie OAuth token for the authenticated user. The caller must supply a Supabase JWT (portal session token) as the Bearer credential. The endpoint verifies workspace membership and returns a tp_oauth_* token scoped to the intersection of the client max-scopes and the user role scopes. Idempotent: re-calling revokes any prior Evie token for the same (user, company) pair and issues a fresh one. Store the returned access_token in sessionStorage; include it as Bearer on all /agent-chat calls.

**Scopes:** _none_ — [full detail](./evie/post-evie-grant.md)

### POST /agent-chat

Run a single Evie conversation turn and stream the result via Server-Sent Events (SSE). The caller supplies a tp_oauth_* token (from /evie-grant) as the Bearer credential. Evie uses the token scopes to determine which CRM tools she can call, dispatches tool calls in-process (no HTTP round-trip per tool), and streams text + tool-call events back in real time. The thread is created automatically on the first message; supply thread_id on subsequent messages to continue a conversation. Model: TrustPager AI Standard (fast) by default; prefix your message with /think for TrustPager AI Advanced.

**Scopes:** _none_ — [full detail](./evie/post-agent-chat.md)

### POST /agent-chat-compact

Compact a long Evie conversation thread into a new thread seeded with a summary of the original. Call this when a thread grows too long for efficient context handling. The original thread is marked as compacted (superseded_by_thread_id is set); the returned new_thread_id is ready for continued conversation. A mechanical compaction pass runs first (free); if the thread is still too long after that, a lightweight AI summarisation pass runs (small credit cost). The new thread starts with one assistant message summarising the conversation so far.

**Scopes:** _none_ — [full detail](./evie/post-agent-chat-compact.md)

### GET /api/v1/_meta/tools

Return the list of CRM tools available to the authenticated API key holder. Each tool entry includes: name (snake_case), description, input_schema (JSON Schema), preferred_model (haiku|sonnet), api_path, required_scopes, is_write, and portal_path. Tools are filtered by the caller scopes - a tp_live_* key with only contacts:read will see only read-scoped contact tools. Used internally by Evie to populate her tool catalog at chat-open; also useful for building your own agent on top of the TrustPager API.

**Scopes:** _none_ — [full detail](./evie/get-api-v1-meta-tools.md)