Context Sources

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

{
  "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

{
  "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 automatically.

string

required

Display name for the context source.

string

required

Source type: "api", "mcp", or "text_document". Also accepted as source_type.

object

required

Source-specific configuration (endpoint URL, headers, etc.).

string

API key or bearer token — stored encrypted in the credential vault. Required for mcp sources.

Response

{
  "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

{
  "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

{
  "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

{ "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

{ "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

{ "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

{
  "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

Overview

Public (unauthenticated)

Agents

Knowledge

CRM

Marketplace

Platform

Telephony

Worker genies

Quality & Compliance

Access Control

Intelligence

Education

Voice

Integrations

Expanded Platform

Actions

`get`

`list`

`create`

`attach`

`upsert`

`update`

`delete`

`delete-source`

`refresh-capabilities`

Error codes

​Actions

​get

​list

​create

​attach

​upsert

​update

​delete

​delete-source

​refresh-capabilities

​Error codes

Actions

`get`

`list`

`create`

`attach`

`upsert`

`update`

`delete`

`delete-source`

`refresh-capabilities`

Error codes