> ## Documentation Index
> Fetch the complete documentation index at: https://docs.equa.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Endpoints

> Equanaut AI assistant chat, tool access, confirmation workflows, and onboarding

> **Source:** `equa-server/modules/agent/src/endpoints/agent-endpoints.ts`

# Agent Endpoints

<Info>
  These endpoints are only available when the Equanaut AI assistant is enabled.
  Requires the `AGENT_*` environment variables to be configured.
  Source: `endpoints.ts` line 124 -- `if (isAgentEnabled(process.env))`
</Info>

Endpoints for the **Equanaut** AI assistant — the intelligent agent that helps users manage their organizations through natural language. Includes chat, tool access, action confirmation, and an AI-powered onboarding flow.

The agent is enabled when `ANTHROPIC_API_KEY` is set (and `AGENT_ENABLED` is not `false`).

## Agent Chat and Tools

### Agent Status

```
GET /v1/agent/status
```

| Field | Value    |
| ----- | -------- |
| Auth  | Required |

Check whether the agent is enabled.

**Response:**

```json theme={null}
{
  "enabled": true,
  "version": "1.0.0"
}
```

***

### Chat with Agent

```
POST /v1/agent/chat
```

| Field      | Value                 |
| ---------- | --------------------- |
| Auth       | Required              |
| Permission | `canViewOrganization` |

Send a message to the Equanaut agent and receive a response. Supports conversation history for multi-turn interactions.

**Request:**

```json theme={null}
{
  "organization": "uuid",
  "message": "How many shareholders does this company have?",
  "conversationId": "uuid-optional",
  "history": [
    { "role": "user", "content": "Previous message" },
    { "role": "assistant", "content": "Previous response" }
  ]
}
```

**Response:**

```json theme={null}
{
  "response": "Your company has 12 shareholders across 3 security types.",
  "conversationId": "uuid",
  "toolCalls": [],
  "pendingConfirmations": []
}
```

***

### Confirm Agent Action

```
POST /v1/agent/confirm
```

| Field | Value    |
| ----- | -------- |
| Auth  | Required |

Confirm or reject a pending write operation initiated by the agent. Write operations require user confirmation by default (`AGENT_CONFIRM_WRITE_OPERATIONS`).

**Request:**

```json theme={null}
{
  "stepId": "uuid",
  "confirmed": true
}
```

***

### Get Organization Context

```
GET /v1/organization/:organization/agent/context
```

| Field      | Value                 |
| ---------- | --------------------- |
| Auth       | Required              |
| Permission | `canViewOrganization` |

Get the agent's context for an organization (available data, capabilities, etc.).

***

### Get Available Tools

```
GET /v1/organization/:organization/agent/tools
```

| Field      | Value                 |
| ---------- | --------------------- |
| Auth       | Required              |
| Permission | `canViewOrganization` |

List the tools available to the agent for this organization.

***

## Onboarding (Authenticated)

These endpoints require an active user session.

### Link User to Onboarding

```
POST /v1/agent/onboarding/link
```

| Field | Value    |
| ----- | -------- |
| Auth  | Required |

Link the authenticated user to a pre-existing onboarding context (created during sign-up).

**Request:**

```json theme={null}
{
  "onboardingId": "uuid"
}
```

***

### Run Onboarding Setup

```
POST /v1/agent/onboarding/setup
```

| Field | Value    |
| ----- | -------- |
| Auth  | Required |

Execute the onboarding setup — the agent creates the organization, cap table structure, members, and other entities based on the onboarding context.

**Request:**

```json theme={null}
{
  "onboardingId": "uuid"
}
```

***

### Get First Login Context

```
GET /v1/agent/onboarding/first-login
```

| Field | Value    |
| ----- | -------- |
| Auth  | Required |

Check if this is the user's first login and retrieve onboarding context including a welcome message.

**Response:**

```json theme={null}
{
  "isFirstLogin": true,
  "onboardingId": "uuid",
  "setupResult": { ... },
  "welcomeMessage": "Welcome! I've set up your organization..."
}
```

***

### Complete Onboarding

```
POST /v1/agent/onboarding/complete
```

| Field | Value    |
| ----- | -------- |
| Auth  | Required |

Mark the onboarding as complete.

***

### Analyze Onboarding

```
POST /v1/agent/onboarding/analyze
```

| Field | Value    |
| ----- | -------- |
| Auth  | Required |

Trigger AI analysis of the onboarding context to extract entities, structure, and generate clarifying questions.

***

### Build Organization

```
POST /v1/agent/onboarding/build
```

| Field | Value    |
| ----- | -------- |
| Auth  | Required |

Build the organization structure based on analyzed onboarding data.

***

### Submit Clarification

```
POST /v1/agent/onboarding/clarify
```

| Field | Value    |
| ----- | -------- |
| Auth  | Required |

Submit an answer to a clarifying question generated during onboarding analysis.

**Request:**

```json theme={null}
{
  "onboardingId": "uuid",
  "questionId": "uuid",
  "answer": "Yes, we have 3 co-founders"
}
```

***

### Submit Correction

```
POST /v1/agent/onboarding/correct
```

| Field | Value    |
| ----- | -------- |
| Auth  | Required |

Submit a correction to an item in the onboarding showcase.

**Request:**

```json theme={null}
{
  "onboardingId": "uuid",
  "itemId": "uuid",
  "fieldPath": "name",
  "newValue": "Corrected Company Name"
}
```

***

## Onboarding (Public)

These endpoints do not require authentication and are used during the sign-up flow before the user has an account.

### Create Onboarding Context

```
POST /v1/agent/onboarding/create
```

| Field | Value |
| ----- | ----- |
| Auth  | None  |

Create a new onboarding context with the user's email and initial prompt describing their company.

**Request:**

```json theme={null}
{
  "email": "founder@startup.com",
  "initialPrompt": "I'm starting a Delaware C-Corp with two co-founders..."
}
```

***

### Get Onboarding Context

```
GET /v1/agent/onboarding/:id
```

| Field | Value |
| ----- | ----- |
| Auth  | None  |

Retrieve an onboarding context by ID.

***

### Get Analysis Status

```
GET /v1/agent/onboarding/analysis-status/:id
```

| Field | Value |
| ----- | ----- |
| Auth  | None  |

Check the status of onboarding analysis.

**Response:**

```json theme={null}
{
  "id": "uuid",
  "status": "analyzed",
  "analysisComplete": true,
  "hasQuestions": true
}
```

***

### Get Clarifying Questions

```
GET /v1/agent/onboarding/questions/:id
```

| Field | Value |
| ----- | ----- |
| Auth  | None  |

Get the list of clarifying questions generated by the AI analysis.

***

### Get Showcase Data

```
GET /v1/agent/onboarding/showcase/:id
```

| Field | Value |
| ----- | ----- |
| Auth  | None  |

Get the showcase data — a preview of the organization structure that will be built from the onboarding context.