Agent API

Welcome to the Sema4.ai Agent API documentation. This API allows you to interact with AI agents in your workspace, manage conversations, and handle messages programmatically. With this API, you can integrate Sema4.ai's powerful AI capabilities into your own applications and workflows.

Getting started

All API requests should be made to the following URL:

https://{endpoint_url}/api/v1

Replace {endpoint_url} with your endpoint URL, that's available in Control Room.

Example:

https://ace.dev.sema4ai.work/tenants/b7c51f2e-89ad-4e62-bf13-9a8d0c7f5e1d/api/v1

Finding your Endpoint URL

To find your endpoint URL, follow these steps:

1. Log in to Control Room.
2. Navigate to the Workspace and click on the API Keys tab.
3. Click the Copy Endpoint URL button to copy the endpoint URL to your clipboard.

Authentication

To use the Sema4.ai Agent API, you need to authenticate your requests using an API key. The Agent API uses Bearer Token as the authentication framework. If using a tool like Postman to work with the API, select Bearer Token as the Auth Type in the Authorization tab.

Example:

Authorization: Bearer your_api_key_here

Finding your API key

You can create a manage API keys in Control Room.

1. Log in to Control Room.
2. Navigate to the Workspace and click on the API Keys tab.
3. Create a new API Key by providing a name and selecting permissions.

Clicking on any created API key will open a window displaying your Bearer Token.

Common examples

Let's walk through some common operations you can perform with the Sema4.ai Agent API.

List agents

To retrieve a list of all agents available to the authenticated user, you can make a GET request to the /agents endpoint.

curl --request GET \
  --url 'https://{endpoint_url}/api/v1/agents' \
  --header 'Authorization: Bearer your_api_key_here'

This request will return a list of Agent objects, each containing information such as the agent's ID, name, description, and configuration.

Create a conversation

Before sending a message to an agent, you need to create a conversation. Use the following endpoint to create a new conversation:

curl --request POST \
  --url 'https://{endpoint_url}/api/v1/agents/{agent_id}/conversations' \
  --header 'Authorization: Bearer your_api_key_here' \
  --header 'Content-Type: application/json' \
  --data '{"name": "New Conversation"}'

Replace {agent_id} with the actual agent ID. This request will create a new conversation and return a Conversation object, including the conversation ID you'll need for sending messages.

Send a message to an agent

After creating a conversation, you can send a message to an agent using the /agents/{agent_id}/conversations/{conversation_id}/messages endpoint:

curl --request POST \
  --url 'https://{endpoint_url}/api/v1/agents/{agent_id}/conversations/{conversation_id}/messages' \
  --header 'Authorization: Bearer your_api_key_here' \
  --header 'Content-Type: application/json' \
  --data '{"content": "Hello, how can you help me today?"}'

Replace {agent_id} with the actual agent ID and {conversation_id} with the conversation ID obtained from the previous step. This request will send a message to the agent and return the updated conversation state, including the agent's response.

Delete a conversation

To delete a conversation, you can send a DELETE request to the /agents/{agent_id}/conversations/{conversation_id} endpoint:

curl --request DELETE \
  --url 'https://{endpoint_url}/api/v1/agents/{agent_id}/conversations/{conversation_id}' \
  --header 'Authorization: Bearer your_api_key_here'

Replace {agent_id} with the actual agent ID and {conversation_id} with the conversation ID you want to delete. This request will delete the specified conversation and return the deleted Conversation object.

Additional examples

The Sema4.ai Agent API offers a range of other functionalities to help you manage and interact with AI agents. Here's a brief overview of these capabilities along with examples:

Get agent details

Retrieve detailed information about a specific agent.

curl --request GET \
  --url 'https://{endpoint_url}/api/v1/agents/{agent_id}' \
  --header 'Authorization: Bearer your_api_key_here'

List conversations

Get a list of all conversations for a specific agent.

curl --request GET \
  --url 'https://{endpoint_url}/api/v1/agents/{agent_id}/conversations' \
  --header 'Authorization: Bearer your_api_key_here'

Retrieve messages in a conversation

Get the message history for a specific conversation.

curl --request GET \
  --url 'https://{endpoint_url}/api/v1/agents/{agent_id}/conversations/{conversation_id}/messages' \
  --header 'Authorization: Bearer your_api_key_here'

Stream messages

Use server-sent events (SSE) to stream messages in real-time.

curl --request POST \
  --url 'https://{endpoint_url}/api/v1/agents/{agent_id}/conversations/{conversation_id}/stream' \
  --header 'Authorization: Bearer your_api_key_here' \
  --header 'Content-Type: application/json' \
  --data '{"content": "Hello, how can you help me today?"}'

Filter agents

Search for specific agents by name.

curl --request GET \
  --url 'https://{endpoint_url}/api/v1/agents?name=Sales' \
  --header 'Authorization: Bearer your_api_key_here'

Complete API reference

This section provides detailed information about all available endpoints in the Sema4.ai Agent API.

Agents

List agents

GET /agents

Lists all agents available to the authenticated user.

Parameters

Request Example

curl --request GET \
  --url 'https://{endpoint_url}/api/v1/agents' \
  --header 'Authorization: Bearer your_api_key_here'

Response

The API uses cursor-based pagination. When there are more results available, the next field will contain a token that can be used to fetch the next page of results. The has_more field indicates whether there are more results available beyond the current page.

To fetch the next page of results, include the next token as a query parameter in your next request:

curl --request GET \
  --url 'https://{endpoint_url}/api/v1/agents?next={next_token}' \
  --header 'Authorization: Bearer your_api_key_here'

Replace {next_token} with the value from the next field in the previous response.

{
    "next": "string",
    "has_more": boolean,
    "data": [
      {
        "id": "string",
        "name": "string",
        "description": "string",
        "mode": "string"
      }
    ]
}

Return Type: PaginatedResponse

Agent

Get agent

GET /agents/{agent_id}

Retrieves details of a specific agent.

Parameters

Request Example

curl --request GET \
  --url 'https://{endpoint_url}/api/v1/agents/{agent_id}' \
  --header 'Authorization: Bearer your_api_key_here'

Response

The response is a single Agent object.

{
  "id": "string",
  "name": "string",
  "description": "string",
  "mode": "string"
}

Return Type: Agent

Conversations

List conversations

GET /agents/{agent_id}/conversations

Lists all conversations for a specific agent.

Parameters

Request Example

curl --request GET \
  --url 'https://{endpoint_url}/api/v1/agents/{agent_id}/conversations' \
  --header 'Authorization: Bearer your_api_key_here'

Response

The response is an array of Conversation objects.

{
  "next": "string",
  "has_more": boolean,
  "data": [
    {
      "id": "string",
      "name": "string",
      "agent_id": "string"
    }
  ]
}

Return Type: PaginatedResponse

Conversation

Create conversation

POST /agents/{agent_id}/conversations

Creates a new conversation for a specific agent.

Parameters

Request Example

curl --request POST \
  --url 'https://{endpoint_url}/api/v1/agents/{agent_id}/conversations' \
  --header 'Authorization: Bearer your_api_key_here' \
  --header 'Content-Type: application/json' \
  --data '{"name": "New Conversation"}'

Response

The response is a single Conversation object.

{
  "id": "string",
  "name": "string",
  "agent_id": "string"
}

Return Type: Conversation

Get messages in a conversation

GET /agents/{agent_id}/conversations/{conversation_id}/messages

Retrieves messages from a specific conversation.

Parameters

Request Example

curl --request GET \
  --url 'https://{endpoint_url}/api/v1/agents/{agent_id}/conversations/{conversation_id}/messages' \
  --header 'Authorization: Bearer your_api_key_here'

Response

The response is a PaginatedResponse of ThreadMessage objects.

{
  "next": null,
  "has_more": false,
  "data": [
    {
      "content": [
        {
          "kind": "text",
          "text": "What is the hottest day?"
        }
      ],
      "role": "user"
    },
    {
      "content": [
        {
          "kind": "thought",
          "thought": "The user's question, \"What is the hottest day?\", lacks context about location, timeframe, or data source. I need clarification to give a helpful answer."
        },
        {
          "kind": "text",
          "text": "Could you clarify what location, year, or data you're referring to when you ask \"What is the hottest day?\" For example, are you asking about the hottest day ever recorded on Earth, in a specific city, or for a recent time period?"
        }
      ],
      "role": "agent"
    }
  ]
}

Return Type: PaginatedResponse

ThreadMessage

Send message

POST /agents/{agent_id}/conversations/{conversation_id}/messages

Sends a message to a specific conversation.

Parameters

Request Example

curl --request POST \
  --url 'https://{endpoint_url}/api/v1/agents/{agent_id}/conversations/{conversation_id}/messages' \
  --header 'Authorization: Bearer your_api_key_here' \
  --header 'Content-Type: application/json' \
  --data '{"content": "Hello, how can you help me today?"}'

Response

The response is a PaginatedResponse of ThreadMessage objects.

{
  "next": "string",
  "has_more": boolean,
  "data": [
    {
      "content": ThreadMessageContent,
      "role": "string",
    }
  ]
}

Return Type: PaginatedResponse

ThreadMessage

ThreadMessageContent is one of ThreadTextContent, ThreadThoughtContent, or ThreadToolUsageContent.

ThreadTextContent

ThreadThoughtContent

ThreadToolUsageContent

Stream messages

POST /agents/{agent_id}/conversations/{conversation_id}/stream

Streams messages to and from a specific conversation.

Parameters

Request Example

curl --request POST \
  --url 'https://{endpoint_url}/api/v1/agents/{agent_id}/conversations/{conversation_id}/stream' \
  --header 'Authorization: Bearer your_api_key_here' \
  --header 'Content-Type: application/json' \
  --data '{"content": "Hello, how can you help me today?"}'

Response

The response is a Server-Sent Events (SSE) stream. Each event in the stream will be a JSON object representing a message or a part of a message.

Delete conversation

DELETE /agents/{agent_id}/conversations/{conversation_id}

Deletes a specific conversation.

Parameters

Request Example

curl --request DELETE \
  --url 'https://{endpoint_url}/api/v1/agents/{agent_id}/conversations/{conversation_id}' \
  --header 'Authorization: Bearer your_api_key_here'

Response

The response is the deleted Conversation object.

{
  "id": "string",
  "name": "string",
  "agent_id": "string"
}

Return Type: Conversation

Response codes

The Sema4.ai Agent API uses standard HTTP response codes to indicate the success or failure of an API request. Here's an overview of the response codes you might encounter:

Success codes

• 200 OK: The request was successful. The response body will contain the requested data.
• 201 Created: The request was successful and a new resource was created. This is typically the response for POST requests that create new conversations or messages.
• 204 No Content: The request was successful, but there is no content to send back. This is often the response for successful DELETE requests.

Client error codes

• 400 Bad Request: The request was invalid or cannot be served. This occurs when the request payload is malformed or missing required parameters.
• 401 Unauthorized: Authentication failed or user doesn't have permissions for the requested operation.
• 403 Forbidden: The request is understood, but it has been refused or access is not allowed.
• 404 Not Found: The requested resource could not be found. This is often returned when an invalid agent ID or conversation ID is provided.
• 422 Unprocessable Entity: The request was well-formed but was unable to be followed due to semantic errors. This often occurs when the request payload doesn't meet the expected format or content.

Server error codes

• 500 Internal Server Error: A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.
• 503 Service Unavailable: The server is currently unavailable (because it is overloaded or down for maintenance). Generally, this is a temporary state.

Error handling

The API uses standard HTTP status codes to indicate the success or failure of requests. In case of errors, additional information may be provided in the response body.

Common error codes

• 400 Bad Request: The request was invalid or cannot be served.
• 401 Unauthorized: The request requires authentication.
• 403 Forbidden: The server understood the request but refuses to authorize it.
• 404 Not Found: The requested resource could not be found.
• 422 Unprocessable Entity: The request was well-formed but was unable to be followed due to semantic errors.
• 500 Internal Server Error: The server encountered an unexpected condition that prevented it from fulfilling the request.

Error response format

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {
      "field": "string",
      "issue": "string"
    }
  }
}