Sema4.ai API

https://sema4.ai/docs/v2/api
Admin
Sema4.ai API provides programmatic access to agents, conversations, work items, and data...
Tokens:40,559
Snippets:606
Trust Score:8.4
Update:3 months ago
Show doc for...
Tokens:
Raw
### Cursor-based Pagination Request Example

Source: https://sema4.ai/docs/v2/api

Example of a curl request demonstrating cursor-based pagination for agents. It includes the limit and next token for fetching subsequent pages.

```bash
curl 'https://{your-deployment-host}/tenants/{tenant-id}/api/v2/agents?limit=50&next={next_token}' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

--------------------------------

### List Work Items Response Structure

Source: https://sema4.ai/docs/v2/api/work-items

Example response structure for listing work items. The `next_offset` field is used for pagination.

```json
{ "records": [ /* WorkItem objects */ ], "next_offset": 50 }
```

--------------------------------

### Get Workspace Settings

Source: https://sema4.ai/docs/v2/api/settings

Retrieves the entire workspace settings object, providing a view of all current advanced configurations.

```APIDOC
## GET /settings

### Description
Returns the full settings object.

### Method
GET

### Endpoint
/settings

### Response
#### Success Response (200)
- **MAX_WORK_ITEM_PAYLOAD_SIZE_IN_KB** (integer) - Maximum work item JSON payload size, in KB.
- **MAX_WORK_ITEM_FILE_ATTACHMENT_SIZE_IN_MB** (integer) - Maximum work item file attachment size, in MB.
- **MAX_AGENT_FILE_ATTACHMENT_SIZE_IN_MB** (integer) - Maximum agent and thread file attachment size, in MB.
- **MAX_AGENTS** (integer) - Maximum number of agents in this workspace.
- **MAX_PARALLEL_WORK_ITEMS_IN_PROCESS** (integer) - Maximum number of work items processed in parallel.
- **MAX_MCP_SERVERS_IN_AGENT** (integer) - Maximum number of configured MCP servers in the workspace.
- **AGENT_THREAD_RETENTION_PERIOD** (integer) - Retention period for agent threads, in days.
- **POSTGRES_POOL_MAX_SIZE** (integer) - Maximum PostgreSQL connection pool size.
- **MAX_CACHE_SIZE_IN_BYTES** (integer) - Maximum cache size, in bytes.
- **WORK_ITEM_TIMEOUT_SECONDS** (integer) - Execution timeout for a single work item, in seconds.
- **MAX_SCHEDULES_PER_AGENT** (integer) - Maximum number of scheduled work items per agent.
- **DATA_FRAME_MATERIALIZATION_ROW_LIMIT** (integer) - Maximum number of rows to materialize from computed DataFrames.
- **DATA_FRAMES_AS_SDM** (boolean) - Enable dynamic SDM generation from materialized DataFrames.
- **HIDE_WELCOME_PAGE** (boolean) - Hide the Welcome page from the sidebar for all users.
- **MCP_GALLERY_BASE_URL** (string) - Sema4.ai MCP Gallery URL. Empty hides Sema4.ai-provided servers from the gallery.
- **MICROSOFT_OAUTH_CLIENT_ID** (string) - Client ID of the Microsoft Entra app for managed-credentials Microsoft MCP installs. Empty disables managed mode.

### Request Example
```bash
curl 'https://{your-deployment-host}/tenants/{tenant-id}/api/v2/settings' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```
```

--------------------------------

### Get Default LLMs

Source: https://sema4.ai/docs/v2/api/llms

Retrieves the tenant-wide default LLM pointers.

```APIDOC
## Get Defaults
GET /llms/defaults

### Description
Retrieves the current tenant-wide default LLM pointers. These pointers determine which LLM configuration is used as the global default and for SQL generation.

### Response
```json
{ "default_llm_id": "string", "sqlgen_llm_id": "string" }
```
A `null` value for either pointer indicates that no default is currently set for that category.
```

--------------------------------

### Get LLM

Source: https://sema4.ai/docs/v2/api/llms

Retrieves a specific LLM configuration by its ID.

```APIDOC
## Get LLM
GET /llms/{llm_id}

### Description
Retrieves a single LLM configuration specified by its ID. If no configuration with the given ID exists, a `404` error is returned.
```

--------------------------------

### Get Branding

Source: https://sema4.ai/docs/v2/api/branding

Retrieves the current workspace branding configuration. This endpoint is available to any authenticated user.

```APIDOC
## GET /branding

### Description
Returns the current `PublicBranding` object, which includes workspace name, logos, and primary color.

### Method
GET

### Endpoint
`/tenants/{tenant-id}/api/v2/branding`

### Parameters
#### Query Parameters
None

#### Headers
- **Authorization** (string) - Required - `Bearer YOUR_API_KEY`

### Request Example
```bash
curl 'https://{your-deployment-host}/tenants/{tenant-id}/api/v2/branding' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

### Response
#### Success Response (200)
- **workspace_name** (string) - Workspace display name override.
- **logo_data_url** (string) - Light-mode logo as a `data:image/png;base64` URL.
- **logo_dark_data_url** (string) - Dark-mode logo as a `data:image/png;base64` URL.
- **primary_color** (string) - Primary brand color as `#RRGGBB`.

#### Response Example
```json
{
  "workspace_name": "Example Workspace",
  "logo_data_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA",
  "logo_dark_data_url": "",
  "primary_color": "#3498DB"
}
```
```

--------------------------------

### Get Workspace Settings

Source: https://sema4.ai/docs/v2/api/settings

Retrieves the full workspace settings object. This is useful for auditing or understanding the current configuration.

```bash
curl 'https://{your-deployment-host}/tenants/{tenant-id}/api/v2/settings' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

--------------------------------

### List Semantic Views Response

Source: https://sema4.ai/docs/v2/api/data-connections

This is an example of the response structure when listing semantic views from a data connection. Note that this feature is currently only supported for Snowflake connections.

```json
{
  "semantic_views": [
    { "name": "string", "database": "string", "schema": "string", "created_on": "string", "description": "string" }
  ]
}
```

--------------------------------

### Get configuration

Source: https://sema4.ai/docs/v2/api/document-intelligence

Returns the Document Intelligence configuration for API consumers. This endpoint reports `not_available` on most deployments as the feature is coming soon.

```APIDOC
## GET /document-intelligence

### Description
Returns the Document Intelligence configuration for API consumers.

### Method
GET

### Endpoint
/document-intelligence

### Response
#### Success Response (200)
- **status** (string) - `configured`, `not_configured`, `not_available`, or `error`.
- **error** (object) - Error detail when `status` is `error`; otherwise null.
- **configuration** (object) - The configuration payload, including the list of `integrations`.

### Response Example
```json
{
  "status": "not_available",
  "error": null,
  "configuration": { "integrations": [] }
}
```
```

--------------------------------

### Get current workspace branding

Source: https://sema4.ai/docs/v2/api/branding

Retrieve the current branding configuration for the workspace. This endpoint is available to any authenticated user.

```curl
curl 'https://{your-deployment-host}/tenants/{tenant-id}/api/v2/branding' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

--------------------------------

### Create an MCP Server

Source: https://sema4.ai/docs/v2/api/mcp-servers

Use this snippet to register a new MCP server. Provide connection details such as URL and headers for remote servers, or command and arguments for local servers. Ensure you include the correct API key in the Authorization header.

```bash
curl -X POST 'https://{your-deployment-host}/tenants/{tenant-id}/api/v2/mcp-servers' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Weather",
    "transport": "streamable-http",
    "url": "https://mcp.example.com/weather"
  }'
```

--------------------------------

### Get agent

Source: https://sema4.ai/docs/v2/api/agents

Retrieves a single agent by its ID.

```APIDOC
## Get agent
`GET /agents/{agent_id}`

### Description
Retrieves a single agent by its ID.

### Method
GET

### Endpoint
/agents/{agent_id}

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - The ID of the agent to retrieve.

### Response
#### Success Response (200)
Returns a single `PublicAgent`.
```

--------------------------------

### Base URL Structure

Source: https://sema4.ai/docs/v2/api

The API is served per-tenant. You need to construct the base URL using your deployment host and tenant ID. All paths in this reference are relative to this base URL.

```APIDOC
## Base URL
The API is served per-tenant, under your deployment host:
```
https://{your-deployment-host}/tenants/{tenant-id}/api/v2
```

Replace `{your-deployment-host}` with your deployment's hostname and `{tenant-id}` with your tenant. You can copy your exact base URL from the application — open **Configuration > API Keys** and it's shown next to the key. Every path in this reference is relative to that base — for example, `GET /agents` is `https://{your-deployment-host}/tenants/{tenant-id}/api/v2/agents`.
Every `v1` endpoint is also reachable under `v2` via the same handler. New endpoints (data connections, conversation files and data frames, and the richer Work Item surface) exist **only** under `v2`. The Agent MCP endpoint is the exception — it stays under the `v1` prefix.
```

--------------------------------

### Create an MCP server

Source: https://sema4.ai/docs/v2/api/mcp-servers

Registers a new MCP server in the workspace. You can configure it for remote or local execution by providing the appropriate connection details.

```APIDOC
## POST /mcp-servers

### Description
Registers a new MCP server. Provide the connection details for the server's transport — `url`/`headers` for a remote server, or `command`/`args`/`env`/`cwd` for a local one.

### Method
POST

### Endpoint
/mcp-servers

### Parameters
#### Request Body
- **name** (string) - Yes - Display name.
- **transport** (string) - No - Transport type.
- **url** (string) - No - Endpoint URL (remote).
- **headers** (object) - No - Request headers (remote).
- **command** (string) - No - Executable (local `stdio`).
- **args** (array) - No - Command arguments.
- **env** (object) - No - Command environment variables.
- **cwd** (string) - No - Command working directory.
- **force_serial_tool_calls** (boolean) - No - Serialize this server's tool calls.
- **type / icon / organization_type** (string) - No - Display and categorization metadata.
- **oauth_client_config** (object) - No - OAuth client config for servers that act on a user's behalf.

### Request Example
```json
{
  "name": "Weather",
  "transport": "streamable-http",
  "url": "https://mcp.example.com/weather"
}
```

### Response
#### Success Response (200)
Returns the created `PublicMcpServer`.
```

--------------------------------

### Get messages

Source: https://sema4.ai/docs/v2/api/conversations

Retrieves a paginated list of messages for a specific conversation.

```APIDOC
## GET /agents/{aid}/conversations/{cid}/messages

### Description
Returns the conversation's messages as a `PaginatedResponse`.

### Method
GET

### Endpoint
/agents/{aid}/conversations/{cid}/messages

### Parameters
#### Path Parameters
- **aid** (string) - Yes - Agent ID.
- **cid** (string) - Yes - Conversation ID.
```

--------------------------------

### Create an LLM Configuration

Source: https://sema4.ai/docs/v2/api/llms

Use this endpoint to add a new LLM configuration to your workspace. Provide the model provider details and any necessary credentials. An unknown provider kind will result in a `400` error, and invalid or missing credentials will return a `422` error.

```curl
curl -X POST 'https://{your-deployment-host}/tenants/{tenant-id}/api/v2/llms' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Production OpenAI",
    "kind": "openai",
    "models": { "openai": ["gpt-4-1"] },
    "configuration": { "openai_api_key": "sk-..." }
  }'
```

--------------------------------

### Get an SDM

Source: https://sema4.ai/docs/v2/api/semantic-data-models

Retrieves a specific Semantic Data Model (SDM) by its ID.

```APIDOC
## GET /semantic-data-models/{semantic_data_model_id}

### Description
Returns a single `PublicSdm`.

### Method
GET

### Endpoint
/semantic-data-models/{semantic_data_model_id}

### Parameters
#### Path Parameters
- **semantic_data_model_id** (string) - Required - The ID of the SDM to retrieve.
```

--------------------------------

### Create Agent using cURL

Source: https://sema4.ai/docs/v2/api/agents

Use this snippet to create a new agent via the API. Ensure you replace placeholders with your actual deployment host, tenant ID, and API key. The request body defines the agent's name, description, and runbook.

```curl
curl -X POST 'https://{your-deployment-host}/tenants/{tenant-id}/api/v2/agents' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Invoice Roast",
    "description": "Forensic expense analyst.",
    "runbook_text": "## Objective\nExtract and check receipts."
  }'
```

--------------------------------

### Import Agent from Zip Package

Source: https://sema4.ai/docs/v2/api/agents

Use this endpoint to create a new agent from a previously exported zip package. The zip file should be sent as multipart/form-data with a 'file' field.

```shell
curl -X POST 'https://{your-deployment-host}/tenants/{tenant-id}/api/v2/agents/import' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'file=@agent-package.zip'
```

--------------------------------

### Get a data connection

Source: https://sema4.ai/docs/v2/api/data-connections

Retrieves details for a specific data connection using its ID.

```APIDOC
## GET /data-connections/{connection_id}

### Description
Returns a single `PublicDataConnection`.

### Method
GET

### Endpoint
/data-connections/{connection_id}

### Parameters
#### Path Parameters
- **connection_id** (string) - Yes - Connection ID.
```

--------------------------------

### Create LLM

Source: https://sema4.ai/docs/v2/api/llms

Creates a new LLM configuration.

```APIDOC
## Create LLM
POST /llms

### Description
Creates a new LLM configuration for the workspace. Invalid or missing credentials for the chosen provider kind will result in a `422` error.

### Request Body
- **name** (string) - Required - Display name for the LLM configuration.
- **kind** (string) - Required - The provider kind (e.g., `openai`, `azure`, `bedrock`). An unknown kind will return a `400` error.
- **description** (string) - Optional - A description for the LLM configuration.
- **models** (object) - Optional - A mapping of provider to a list of model names (e.g., `{ "openai": ["gpt-4-1"] }`). Must not be empty if provided.
- **configuration** (object) - Optional - Provider-specific configuration, including credentials. Empty string values are ignored.

### Request Example
```json
{
  "name": "Production OpenAI",
  "kind": "openai",
  "models": { "openai": ["gpt-4-1"] },
  "configuration": { "openai_api_key": "sk-..." }
}
```

### Response
Returns the created `PublicLlm` object.
```

--------------------------------

### Get a Specific Semantic Data Model

Source: https://sema4.ai/docs/v2/api/semantic-data-models

Retrieves a single Semantic Data Model (SDM) by its ID.

```HTTP
GET /semantic-data-models/{semantic_data_model_id}
```

--------------------------------

### Create agent

Source: https://sema4.ai/docs/v2/api/agents

Creates a new agent owned by the authenticated key. Requires agent name and optionally accepts description, runbook text, and architecture details.

```APIDOC
## Create agent
`POST /agents`

### Description
Creates a new agent owned by the authenticated key.

### Method
POST

### Endpoint
/agents

### Parameters
#### Request Body
- **name** (string) - Required - Agent name.
- **description** (string) - Optional - What the agent does.
- **runbook_text** (string) - Optional - The agent's runbook, as Markdown text.
- **architecture_name** (string) - Optional - Architecture to use (defaults applied).
- **architecture_version** (string) - Optional - Architecture version.

### Request Example
```json
{
  "name": "Invoice Roast",
  "description": "Forensic expense analyst.",
  "runbook_text": "## Objective\nExtract and check receipts."
}
```

### Response
#### Success Response (200)
Returns the created `PublicAgent`.
```

--------------------------------

### Pagination - Cursor-based

Source: https://sema4.ai/docs/v2/api

For resources like agents, conversations, and messages, use cursor-based pagination. Provide a `limit` and use the `next` token from the response (when `has_more` is true) to fetch subsequent pages.

```APIDOC
## Pagination
The API uses two pagination styles depending on the resource:
  * **Cursor-based** (agents, conversations, messages). Pass `limit`, and when `has_more` is `true`, pass the `next` token to fetch the following page.
```
{ "next": "string", "has_more": true, "data": [ /* ... */ ] }
```

```
curl 'https://{your-deployment-host}/tenants/{tenant-id}/api/v2/agents?limit=50&next={next_token}' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```
```

--------------------------------

### Get a work item

Source: https://sema4.ai/docs/v2/api/work-items

Retrieves a specific work item by its ID. Optionally includes the item's results.

```APIDOC
## GET /work-items/{work_item_id}

### Description
Retrieves a specific work item by its ID. Optionally includes the item's results.

### Method
GET

### Endpoint
/work-items/{work_item_id}

### Parameters
#### Path Parameters
- **work_item_id** (string) - Required - Work item ID.
#### Query Parameters
- **results** (boolean) - Optional - Include the item's results.

### Response
#### Success Response (200)
- Returns a Work Item.
```

--------------------------------

### Create a data connection

Source: https://sema4.ai/docs/v2/api/data-connections

Creates a new data connection. The platform verifies the connection before saving. Returns the created `PublicDataConnection`.

```APIDOC
## POST /data-connections

### Description
Creates a connection. The body is typed by `engine`, with an engine-specific `configuration`. The platform **verifies the connection before saving** — if it can't connect, you get `400` and nothing is written. Returns the created `PublicDataConnection`.

### Method
POST

### Endpoint
/data-connections

### Parameters
#### Request Body
- **name** (string) - Yes - Connection name.
- **description** (string) - No - What the connection is for.
- **engine** (string) - Yes - Source type — selects the `configuration` shape.
- **configuration** (object) - Yes - Engine-specific settings (e.g. Postgres: `host`, `port`, `database`, `user`, `password`, `schema`, `sslmode`).
- **tags** (array) - No - Tags.

### Request Example
```json
{
  "name": "Invoices DB",
  "description": "AP invoices",
  "engine": "postgres",
  "configuration": {
    "host": "db.internal", "port": 5432, "database": "invoices",
    "user": "readonly", "password": "…", "schema": "public", "sslmode": "require"
  }
}
```
```

--------------------------------

### List data connections

Source: https://sema4.ai/docs/v2/api/data-connections

Retrieves a paginated list of all data connections configured in the workspace.

```APIDOC
## GET /data-connections

### Description
Returns a `PaginatedResponse` of connections.

### Method
GET

### Endpoint
/data-connections
```

--------------------------------

### Import Agent

Source: https://sema4.ai/docs/v2/api/agents

Creates a new agent from a previously exported zip package.

```APIDOC
## POST /agents/import

### Description
Creates a new agent from a zip file containing the agent's configuration and associated data.

### Method
POST

### Endpoint
/agents/import

### Parameters
#### Request Body
- **file** (file) - Required - A multipart/form-data field containing the agent zip package.

### Request Example
```curl
curl -X POST 'https://{your-deployment-host}/tenants/{tenant-id}/api/v2/agents/import' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'file=@agent-package.zip'
```

### Response
#### Success Response (200)
- **PublicAgent** (object) - The newly created agent details.
```

--------------------------------

### Get lifecycle state

Source: https://sema4.ai/docs/v2/api/agents

Retrieves the current lifecycle state of an agent, including its live version ID and whether a draft exists.

```APIDOC
### Get lifecycle state
`GET /agents/{agent_id}/state`

### Description
Gets the current lifecycle state of an agent.

### Method
GET

### Endpoint
`/agents/{agent_id}/state`

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - The ID of the agent to get the state for.

### Response
#### Success Response (200)
- **state** (string) - `draft` or `live` (lowercase).
- **live_version_id** (string) - ID of the published live version, if any.
- **has_draft** (boolean) - Whether an editable draft exists.

### Response Example
```json
{
  "state": "draft",
  "live_version_id": "string",
  "has_draft": true
}
```
```

--------------------------------

### Pagination - Offset-based

Source: https://sema4.ai/docs/v2/api

For resources like Work Items, use offset-based pagination. Provide `limit` and `offset`. The response will include `records` and a `next_offset` for fetching the next page.

```APIDOC
  * **Offset-based** (Work Items). Pass `limit` and `offset`; the response returns `records` and a `next_offset` to use for the next page.
```

--------------------------------

### Publish agent

Source: https://sema4.ai/docs/v2/api/agents

Snapshots the current draft as a new version and makes it the live version. This action requires the agent to be in a draft state. It allows for mapping test resources to production equivalents.

```APIDOC
### Publish
`POST /agents/{agent_id}/publish`

### Description
Snapshots the current draft as a new version, flips the agent to `live`, and points `live_version_id` at it. Requires `draft` state.

### Method
POST

### Endpoint
`/agents/{agent_id}/publish`

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - The ID of the agent to publish.

#### Request Body
- **description** (string) - Optional - Change description for this publish.
- **connection_mappings** (object<string>) - Optional - Map test data-connection IDs → prod data-connection IDs.
- **mcp_server_mappings** (object<string>) - Optional - Map test MCP server IDs → prod MCP server IDs.

### Note
The mappings let you swap the draft's test resources for production equivalents at publish time. Returns the `PublicAgent`.
```

--------------------------------

### Get Agent Lifecycle State

Source: https://sema4.ai/docs/v2/api/agents

Retrieves the current state of an agent, including whether it is in draft or live mode, and if a draft exists.

```json
{ "state": "draft", "live_version_id": "string", "has_draft": true }
```

--------------------------------

### Get an MCP server

Source: https://sema4.ai/docs/v2/api/mcp-servers

Retrieves the details of a specific MCP server by its ID. This is useful for inspecting the configuration of a single tool provider.

```APIDOC
## GET /mcp-servers/{mcp_server_id}

### Description
Returns a single `PublicMcpServer`.

### Method
GET

### Endpoint
/mcp-servers/{mcp_server_id}

### Parameters
#### Path Parameters
- **mcp_server_id** (string) - Required - The ID of the MCP server to retrieve.
```

--------------------------------

### Get a data frame

Source: https://sema4.ai/docs/v2/api/conversations

Retrieves the contents of a specific data frame within a conversation, with options for slicing, column selection, and ordering.

```APIDOC
## GET /agents/{aid}/conversations/{cid}/data-frames/{data_frame_name}

### Description
Retrieves a data frame's contents, with optional slicing, column selection, and ordering.

### Method
GET

### Endpoint
/agents/{aid}/conversations/{cid}/data-frames/{data_frame_name}

### Parameters
#### Path Parameters
- **aid** (string) - Yes - Agent ID.
- **cid** (string) - Yes - Conversation ID.
- **data_frame_name** (string) - Yes - Name of the data frame.

#### Query Parameters
- **offset** (integer) - No - Row offset to start from.
- **limit** (integer) - No - Maximum number of rows to return.
- **column_names** (string) - No - Comma-separated columns to include.
- **order_by** (string) - No - Column to order by.
- **output_format** (string) - No - Format of the returned rows.
```

--------------------------------

### Scaffold from tables

Source: https://sema4.ai/docs/v2/api/semantic-data-models

Inspects physical tables in a data connection and persists a draft SDM generated from them.

```APIDOC
## POST /semantic-data-models/scaffold-from-tables

### Description
Inspects physical tables in a data connection and persists a draft SDM generated from them. This is a fast way to bootstrap a model.

### Method
POST

### Endpoint
/semantic-data-models/scaffold-from-tables

### Parameters
#### Request Body
- **data_connection_id** (string) - Required - Connection to inspect.
- **tables** (array) - Required - Physical table names to scaffold from (non-empty).
- **name** (string) - Required - Name for the resulting SDM (unique within the account).
- **description** (string) - Optional - Optional description.
```

--------------------------------

### Get Document Intelligence Configuration

Source: https://sema4.ai/docs/v2/api/document-intelligence

Retrieves the Document Intelligence configuration for API consumers. The response indicates the status, potential errors, and configured integrations.

```json
{
  "status": "not_available",
  "error": null,
  "configuration": { "integrations": [] }
}
```

--------------------------------

### API Base URL Structure

Source: https://sema4.ai/docs/v2/api

Construct the base URL for API requests by replacing placeholders with your deployment host and tenant ID. This URL is specific to each tenant.

```text
https://{your-deployment-host}/tenants/{tenant-id}/api/v2
```

--------------------------------

### Send JSON-RPC Messages via cURL

Source: https://sema4.ai/docs/v2/api/mcp

Example using cURL to send a JSON-RPC message to the agent's MCP server. Ensure to set the correct Authorization, Content-Type, and Accept headers.

```curl
curl -X POST 'https://{your-deployment-host}/tenants/{tenant-id}/api/v1/agent-mcp/{aid}/mcp/' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'
```

--------------------------------

### List files

Source: https://sema4.ai/docs/v2/api/conversations

Retrieves a list of files associated with a specific conversation.

```APIDOC
## GET /agents/{aid}/conversations/{cid}/files

### Description
Retrieves a list of files associated with a specific conversation.

### Method
GET

### Endpoint
/agents/{aid}/conversations/{cid}/files

### Parameters
#### Path Parameters
- **aid** (string) - Yes - Agent ID.
- **cid** (string) - Yes - Conversation ID.
```

--------------------------------

### Create an SDM

Source: https://sema4.ai/docs/v2/api/semantic-data-models

Creates a new Semantic Data Model (SDM) from a provided model body.

```APIDOC
## POST /semantic-data-models

### Description
Creates an SDM from a model body. The `semantic_model` must define at least one of `tables` or `schemas` and cannot be empty.

### Method
POST

### Endpoint
/semantic-data-models

### Parameters
#### Request Body
- **semantic_model** (object) - Required - The semantic data model definition.
- **thread_id** (string) - Optional - Thread to associate for post-create messaging.
- **version_id** (string) - Optional - Agent version ID for version-scoped name uniqueness.
```

--------------------------------

### List LLMs

Source: https://sema4.ai/docs/v2/api/llms

Retrieves a list of all configured LLMs in the workspace. The response is not paginated.

```APIDOC
## List LLMs
GET /llms

### Description
Returns a list of all LLM configurations available in the workspace. The response is a `PaginatedResponse` with the `data` field containing the list of LLMs. The list is not paged, meaning `next` will be `null` and `has_more` will be `false`.
```

--------------------------------

### Create PostgreSQL Data Connection

Source: https://sema4.ai/docs/v2/api/data-connections

Use this to create a new PostgreSQL data connection. The platform verifies the connection before saving; a `400` error is returned if it fails.

```curl
curl -X POST 'https://{your-deployment-host}/tenants/{tenant-id}/api/v2/data-connections' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Invoices DB",
    "description": "AP invoices",
    "engine": "postgres",
    "configuration": {
      "host": "db.internal", "port": 5432, "database": "invoices",
      "user": "readonly", "password": "…", "schema": "public", "sslmode": "require"
    }
  }'
```

--------------------------------

### Scaffold a Semantic Data Model from Tables

Source: https://sema4.ai/docs/v2/api/semantic-data-models

Generates and persists a draft Semantic Data Model (SDM) by inspecting physical tables in a specified data connection. This is a quick way to bootstrap a model.

```HTTP
POST /semantic-data-models/scaffold-from-tables
```

--------------------------------

### Create a Work Item

Source: https://sema4.ai/docs/v2/api/work-items

Queues a new work item for an agent. Use this endpoint to submit tasks for processing.

```curl
curl -X POST 'https://{your-deployment-host}/tenants/{tenant-id}/api/v2/work-items' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ \
    "agent_id": "AGENT_ID", \
    "work_item_name": "Invoice 4815", \
    "payload": { "invoice_number": "4815", "amount": 1620.00 } \
  }'
```
Tokens:
Raw