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

# Context Sources

> Manage live data integrations that supply real-time context to your Genies during conversations.

Context sources connect your Genies to external data — via a REST API, an MCP server, or a static text document. When a source is attached to a Genie, its capabilities are discovered automatically and made available during conversations.

Supported `source_type` values: `api`, `mcp`, `text_document`.

Workspace members share access to their owner's context sources.

***

## Actions

### `get`

Returns a single context source by ID.

**Parameters**

| Field       | Type    | Required | Description                                |
| ----------- | ------- | -------- | ------------------------------------------ |
| `id`        | string  | Yes      | Context source UUID (passed as request ID) |
| `adminMode` | boolean | No       | Admin only — bypass ownership filter       |

**Response**

```json theme={null}
{
  "success": true,
  "data": {
    "id": "source-uuid",
    "source_type": "api",
    "config": { },
    "capabilities": [ ],
    "last_capabilities_fetch": "2024-01-01T00:00:00Z"
  }
}
```

***

### `list`

Returns all context sources for the authenticated user, optionally filtered to sources attached to a specific Genie.

**Parameters**

| Field       | Type    | Required | Description                                |
| ----------- | ------- | -------- | ------------------------------------------ |
| `agentId`   | string  | No       | Only return sources attached to this Genie |
| `adminMode` | boolean | No       | Admin only                                 |

**Response**

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "source-uuid",
      "source_type": "mcp",
      "config": { },
      "capabilities": [ ],
      "agents": [ { "agent_id": "agent-uuid" } ]
    }
  ]
}
```

***

### `create`

Creates a new context source and immediately fetches its capabilities from the remote endpoint.

For `mcp` sources, `credential_value` is required for capability discovery. The credential is stored encrypted in the vault automatically.

**Parameters**

| Field              | Type   | Required | Description                                                    |
| ------------------ | ------ | -------- | -------------------------------------------------------------- |
| `source_type`      | string | Yes      | `"api"`, `"mcp"`, or `"text_document"`                         |
| `config`           | object | Yes      | Source-specific configuration (URL, headers, etc.)             |
| `credential_value` | string | No       | API key or bearer token — stored encrypted. Required for `mcp` |

**Response**

```json theme={null}
{
  "success": true,
  "data": { /* context_sources row */ }
}
```

***

### `attach`

Attaches an existing context source to a Genie.

**Parameters**

| Field      | Type   | Required | Description         |
| ---------- | ------ | -------- | ------------------- |
| `agentId`  | string | Yes      | Genie UUID          |
| `sourceId` | string | Yes      | Context source UUID |

**Response**

```json theme={null}
{
  "success": true,
  "data": { /* context_sources row */ }
}
```

***

### `upsert`

Creates or updates a context source and attaches it to a Genie in a single operation. Capabilities are fetched at write time.

**Parameters**

| Field              | Type   | Required | Description                                          |
| ------------------ | ------ | -------- | ---------------------------------------------------- |
| `agentId`          | string | Yes      | Genie UUID to attach to                              |
| `source_type`      | string | Yes      | `"api"`, `"mcp"`, or `"text_document"`               |
| `config`           | object | Yes      | Source configuration                                 |
| `sourceId`         | string | No       | UUID of an existing source to update; omit to create |
| `credential_value` | string | No       | API key or bearer token. Required for `mcp`          |

**Response**

```json theme={null}
{
  "success": true,
  "data": {
    "id": "source-uuid",
    "source_type": "api",
    "capabilities": [ ]
  }
}
```

***

### `update`

Updates mutable fields on a context source. Currently supports toggling `is_active`.

**Parameters**

| Field       | Type    | Required | Description                  |
| ----------- | ------- | -------- | ---------------------------- |
| `id`        | string  | Yes      | Context source UUID          |
| `is_active` | boolean | Yes      | Enable or disable the source |

**Response**

```json theme={null}
{ "success": true }
```

***

### `delete`

Detaches a context source from a Genie (removes the `agent_context_source` association). The source itself is not deleted.

**Parameters**

| Field      | Type   | Required | Description                                                               |
| ---------- | ------ | -------- | ------------------------------------------------------------------------- |
| `agentId`  | string | Yes      | Genie UUID                                                                |
| `sourceId` | string | No       | Specific source UUID to detach. Omit to detach all sources from the Genie |

**Response**

```json theme={null}
{ "success": true }
```

***

### `delete-source`

Permanently deletes a context source and its associated credential from the vault. Irreversible.

**Parameters**

| Field      | Type   | Required | Description         |
| ---------- | ------ | -------- | ------------------- |
| `sourceId` | string | Yes      | Context source UUID |

**Response**

```json theme={null}
{ "success": true }
```

***

### `refresh-capabilities`

Re-fetches and updates the capability list for the context source attached to a Genie. Useful after the remote API changes.

**Parameters**

| Field     | Type   | Required | Description                                 |
| --------- | ------ | -------- | ------------------------------------------- |
| `agentId` | string | Yes      | Genie UUID whose attached source to refresh |

**Response**

```json theme={null}
{
  "success": true,
  "data": {
    "capabilities": [ /* updated capability list */ ]
  }
}
```

***

## Error codes

| Code               | Meaning                                                    |
| ------------------ | ---------------------------------------------------------- |
| `VALIDATION_ERROR` | Missing or invalid parameter, or unsupported `source_type` |
| `NOT_FOUND`        | Source or agent-source association not found               |
| `UNAUTHORIZED`     | You do not have access to this Genie                       |
| `INTERNAL_ERROR`   | Unexpected server error                                    |