CAIP Agents API Reference

Overview

The CAIP Agents API provides a comprehensive REST API for managing AI agents, conversation threads, messages, and vector search capabilities. This API enables you to create, configure, and interact with AI agents powered by various language models, as well as manage embeddings and perform semantic/keyword search for RAG applications.

Base URL: https://agents.api.caip.bmw.cloud
Version: 1.1

Authentication

All endpoints require an API key via the Authorization header:

Authorization: Bearer <your-api-key>

Error Handling

The API uses standard HTTP status codes and returns errors in the following format:

{
  "error": true,
  "message": "Error message describing what went wrong",
  "code": "ERROR_CODE"
}

Common HTTP Status Codes

Status Code	Description
`200`	OK - Request succeeded
`201`	Created - Resource created successfully
`204`	No Content - Request succeeded, no content returned
`400`	Bad Request - Invalid input data
`401`	Unauthorized - Authentication required or failed
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource not found
`422`	Unprocessable Entity - Validation error
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Server error occurred

Models
Agents
Threads
Messages
Vector Stores
Embeddings
Vector Search
Keyword Search
Hybrid Search
Search Evaluation

Models

List Available Models

Retrieve a list of all available AI models that can be used with agents.

Endpoint: GET /v1/models

Authentication: Required

Response:

[
  {
    "modelId": "507f1f77bcf86cd799439011",
    "name": "gpt-4",
    "provider": "openai"
  },
  {
    "modelId": "507f1f77bcf86cd799439012",
    "name": "gpt-4-turbo",
    "provider": "openai"
  },
  {
    "modelId": "507f1f77bcf86cd799439013",
    "name": "claude-3-opus",
    "provider": "anthropic"
  }
]

Example Request:

curl -X 'GET' \
  'https://agents.api.caip.bmw.cloud/v1/models' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response Codes:

200: Models retrieved successfully
500: Failed to retrieve models

Agents

Agents are AI assistants configured with specific instructions, models, and parameters to perform tasks.

Create Agent

Create a new AI agent with specified configuration.

Endpoint: POST /v1/spaces/{spaceId}/agent

Authentication: Required

Path Parameters:

Parameter	Type	Required	Description
`spaceId`	string	Yes	Unique identifier for the space

Query Parameters:

Parameter	Type	Required	Description
`model`	string	Yes	AI model to use (e.g., "gpt-4", "claude-3-opus")

Request Body:

{
  "name": "Customer Support Agent",
  "instructions": "You are a helpful customer support agent. Be concise and professional.",
  "description": "AI assistant for customer support inquiries",
  "outputFormat": "text",
  "createdBy": {
    "qxId": "QX11111",
    "name": "John Doe"
  },
  "defaultParameters": {
    "temperature": 0.7,
    "max_tokens": 1024,
    "top_p": 1.0,
    "frequency_penalty": 0.0,
    "presence_penalty": 0.0
  },
  "metadata": {
    "type": "conversational",
    "category": "support"
  }
}

Response:

{
  "agentId": "507f1f77bcf86cd799439011",
  "spaceId": "space_12345"
}

Example Request:

curl -X 'POST' \
  'https://agents.api.caip.bmw.cloud/v1/spaces/space_12345/agent?model=gpt-4' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Customer Support Agent",
    "instructions": "You are a helpful customer support agent.",
    "description": "AI assistant for customer support",
    "outputFormat": "text",
    "createdBy": {
      "qxId": "QX11111",
      "name": "John Doe"
    }
  }'

Response Codes:

201: Agent created successfully
400: Invalid input data or model
404: Space not found
500: Failed to create agent

Fields:

Field	Type	Required	Description
`name`	string	Yes	Name of the agent
`instructions`	string	Yes	Behavioral instructions for the agent
`description`	string	Yes	Description of the agent's purpose
`outputFormat`	string	Yes	Output format (e.g., "text")
`createdBy`	object	Yes	User who created the agent (`qxId`, `name`)
`defaultParameters`	object	No	Default LLM parameters (temperature, max_tokens, top_p, frequency_penalty, presence_penalty)
`metadata`	object	No	Additional metadata key-value pairs

Get Agent

Retrieve a specific agent by its ID.

Endpoint: GET /v1/spaces/{spaceId}/agent/{agentId}

Authentication: Required

Path Parameters:

Parameter	Type	Required	Description
`spaceId`	string	Yes	Unique identifier for the space
`agentId`	string	Yes	Unique agent identifier

Response:

{
  "agentId": "507f1f77bcf86cd799439011",
  "name": "Customer Support Agent",
  "spaceId": "space_12345",
  "instructions": "You are a helpful customer support agent.",
  "description": "AI assistant for customer support",
  "model": "gpt-4",
  "provider": "openai",
  "outputFormat": "text",
  "createdAt": "2025-10-09T08:30:00+00:00",
  "updatedAt": "2025-10-09T12:30:00+00:00",
  "createdBy": {
    "qxId": "QX11111",
    "name": "John Doe"
  },
  "defaultParameters": {
    "temperature": 0.7,
    "max_tokens": 1024
  }
}

Example Request:

curl -X 'GET' \
  'https://agents.api.caip.bmw.cloud/v1/spaces/space_12345/agent/507f1f77bcf86cd799439011' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response Codes:

200: Agent retrieved successfully
404: Agent or space not found

List Agents

List all agents in a specific space. You can retrieve agents using GET (with optional pagination/search query parameters) or filter by metadata using the QUERY HTTP method with a JSON body.

Method	Endpoint
`GET`	`/v1/spaces/{spaceId}/agent`
`QUERY`	`/v1/spaces/{spaceId}/agent`

warning

The QUERY method is not visible in the Swagger API Docs UI since it does not fully support this newly standardized method natively yet. However, it can be used via API calling tools such as Postman or curl with -X QUERY.

Authentication: Required

Path Parameters:

Parameter	Type	Required	Description
`spaceId`	string	Yes	Unique identifier for the space

GET — List with optional pagination & search

Example Request:

curl -X 'GET' \
  'https://agents.api.caip.bmw.cloud/v1/spaces/space_12345/agent' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response:

[
  {
    "agentId": "507f1f77bcf86cd799439011",
    "name": "Customer Support Agent",
    "spaceId": "space_12345",
    "instructions": "You are a helpful customer support agent.",
    "description": "AI assistant for customer support",
    "model": "gpt-4",
    "provider": "openai",
    "outputFormat": "text",
    "createdAt": "2025-10-09T08:30:00+00:00",
    "updatedAt": "2025-10-09T12:30:00+00:00",
    "createdBy": {
      "qxId": "QX11111",
      "name": "John Doe"
    }
  }
]

QUERY — Filter by metadata

Send a JSON body with a metadata object to filter agents by metadata key-value pairs. A scalar value matches exactly, an array value matches any of the listed values. The body is optional: omitting it returns all agents.

Example Request:

curl -X 'QUERY' \
  'https://agents.api.caip.bmw.cloud/v1/spaces/space_12345/agent' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "metadata": {
      "type": "conversational",
      "category": ["support", "billing"]
    }
  }'

Response:

{
  "data": [
    {
      "agentId": "507f1f77bcf86cd799439011",
      "name": "Customer Support Agent",
      "spaceId": "space_12345",
      "model": "gpt-4",
      "provider": "openai",
      "metadata": {
        "type": "conversational",
        "category": "support"
      },
      "createdAt": "2025-10-09T08:30:00+00:00",
      "updatedAt": "2025-10-09T12:30:00+00:00"
    }
  ],
  "pagination": {
    "totalRecords": 1,
    "currentPage": 1,
    "totalPages": 1,
    "nextPage": null,
    "prevPage": null
  }
}

Request Body Fields (QUERY only):

Field	Type	Required	Description
`metadata`	object	No	Key-value pairs to filter by. A scalar value matches exactly, an array value matches any of the listed values

Response Codes:

200: Agents retrieved successfully
500: Failed to retrieve agents

Update Agent

Update an existing agent's configuration. All fields are optional — only include the fields you want to change.

Endpoint: PATCH /v1/spaces/{spaceId}/agent/{agentId}

Authentication: Required

Path Parameters:

Parameter	Type	Required	Description
`spaceId`	string	Yes	Unique identifier for the space
`agentId`	string	Yes	Unique agent identifier

Request Body:

{
  "name": "Updated Agent Name",
  "instructions": "Updated instructions for the agent.",
  "description": "Updated description",
  "model": "gpt-4-turbo",
  "outputFormat": "text",
  "updatedBy": {
    "qxId": "QX11111",
    "name": "John Doe"
  },
  "defaultParameters": {
    "temperature": 0.5,
    "max_tokens": 2048
  },
  "metadata": {
    "type": "conversational",
    "category": "support"
  }
}

Response:

{
  "agentId": "507f1f77bcf86cd799439011",
  "name": "Updated Agent Name",
  "spaceId": "space_12345",
  "instructions": "Updated instructions for the agent.",
  "description": "Updated description",
  "model": "gpt-4-turbo",
  "provider": "openai",
  "outputFormat": "text",
  "createdAt": "2025-10-09T08:30:00+00:00",
  "updatedAt": "2025-10-09T14:00:00+00:00"
}

Example Request:

curl -X 'PATCH' \
  'https://agents.api.caip.bmw.cloud/v1/spaces/space_12345/agent/507f1f77bcf86cd799439011' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Updated Agent Name",
    "updatedBy": {
      "qxId": "QX11111",
      "name": "John Doe"
    }
  }'

Response Codes:

200: Agent updated successfully
404: Agent or space not found
500: Failed to update agent

Delete Agent

Delete an agent permanently. This also deletes all associated threads and messages.

Endpoint: DELETE /v1/spaces/{spaceId}/agent/{agentId}

Authentication: Required

Path Parameters:

Parameter	Type	Required	Description
`spaceId`	string	Yes	Unique identifier for the space
`agentId`	string	Yes	Unique agent identifier

Example Request:

curl -X 'DELETE' \
  'https://agents.api.caip.bmw.cloud/v1/spaces/space_12345/agent/507f1f77bcf86cd799439011' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response Codes:

204: Agent deleted successfully
404: Agent or space not found
500: Failed to delete agent

Threads

Threads represent conversation sessions with an agent.

Create Thread

Create a new conversation thread for a specific agent.

Endpoint: POST /v1/spaces/{spaceId}/agent/{agentId}/thread

Authentication: Required

Path Parameters:

Parameter	Type	Required	Description
`spaceId`	string	Yes	Unique identifier for the space
`agentId`	string	Yes	Unique agent identifier

Request Body:

{
  "title": "Billing Issue",
  "status": "open",
  "metadata": {
    "priority": "high",
    "category": "support"
  }
}

Response:

{
  "threadId": "507f1f77bcf86cd799439033",
  "title": "Billing Issue",
  "spaceId": "space_12345",
  "agentId": "507f1f77bcf86cd799439011",
  "status": "open",
  "metadata": {
    "priority": "high",
    "category": "support"
  },
  "createdAt": "2025-10-09T09:15:00+00:00",
  "updatedAt": "2025-10-09T09:15:00+00:00",
  "lastMessageAt": null
}

Example Request:

curl -X 'POST' \
  'https://agents.api.caip.bmw.cloud/v1/spaces/space_12345/agent/507f1f77bcf86cd799439011/thread' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Billing Issue",
    "status": "open"
  }'

Response Codes:

201: Thread created successfully
400: Invalid input data
404: Agent or space not found
500: Failed to create thread

Fields:

Field	Type	Required	Description
`title`	string	No	Title of the thread
`status`	string	No	Thread status: `open` (default), `archived`, `completed`
`metadata`	object	No	Additional metadata key-value pairs

Get Thread

Retrieve a specific conversation thread by its ID.

Endpoint: GET /v1/spaces/{spaceId}/agent/{agentId}/thread/{threadId}

Authentication: Required

Path Parameters:

Parameter	Type	Required	Description
`spaceId`	string	Yes	Unique identifier for the space
`agentId`	string	Yes	Unique agent identifier
`threadId`	string	Yes	Unique thread identifier

Response:

{
  "threadId": "507f1f77bcf86cd799439033",
  "title": "Billing Issue",
  "spaceId": "space_12345",
  "agentId": "507f1f77bcf86cd799439011",
  "status": "open",
  "metadata": {
    "priority": "high",
    "category": "support"
  },
  "createdAt": "2025-10-09T09:15:00+00:00",
  "updatedAt": "2025-10-09T09:15:00+00:00",
  "lastMessageAt": "2025-10-09T10:15:00+00:00"
}

Example Request:

curl -X 'GET' \
  'https://agents.api.caip.bmw.cloud/v1/spaces/space_12345/agent/507f1f77bcf86cd799439011/thread/507f1f77bcf86cd799439033' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response Codes:

200: Thread retrieved successfully
404: Thread, agent, or space not found

List Threads

List all conversation threads for an agent. You can optionally filter by status using GET query parameters, or filter by metadata using the QUERY HTTP method with a JSON body.

Method	Endpoint
`GET`	`/v1/spaces/{spaceId}/agent/{agentId}/thread`
`QUERY`	`/v1/spaces/{spaceId}/agent/{agentId}/thread`

warning

Authentication: Required

Path Parameters:

Parameter	Type	Required	Description
`spaceId`	string	Yes	Unique identifier for the space
`agentId`	string	Yes	Unique agent identifier

GET — Filter by status

Query Parameter	Type	Required	Description
`status`	string	No	Filter by status: `open`, `archived`, `completed`

Example Request:

curl -X 'GET' \
  'https://agents.api.caip.bmw.cloud/v1/spaces/space_12345/agent/507f1f77bcf86cd799439011/thread?status=open' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response:

[
  {
    "threadId": "507f1f77bcf86cd799439033",
    "title": "Billing Issue",
    "spaceId": "space_12345",
    "agentId": "507f1f77bcf86cd799439011",
    "status": "open",
    "createdAt": "2025-10-09T09:15:00+00:00",
    "updatedAt": "2025-10-09T09:15:00+00:00",
    "lastMessageAt": "2025-10-09T10:15:00+00:00"
  }
]

QUERY — Filter by metadata

Send a JSON body with a metadata object to filter threads by metadata key-value pairs. A scalar value matches exactly, an array value matches any of the listed values. The body is optional: omitting it returns all threads.

Example Request:

curl -X 'QUERY' \
  'https://agents.api.caip.bmw.cloud/v1/spaces/space_12345/agent/507f1f77bcf86cd799439011/thread' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "metadata": {
      "priority": "high",
      "category": ["support", "billing"]
    }
  }'

Response:

[
  {
    "threadId": "507f1f77bcf86cd799439033",
    "title": "Billing Issue",
    "spaceId": "space_12345",
    "agentId": "507f1f77bcf86cd799439011",
    "status": "open",
    "metadata": {
      "priority": "high",
      "category": "support"
    },
    "createdAt": "2025-10-09T09:15:00+00:00",
    "updatedAt": "2025-10-09T09:15:00+00:00",
    "lastMessageAt": "2025-10-09T10:15:00+00:00"
  }
]

Request Body Fields (QUERY only):

Field	Type	Required	Description
`metadata`	object	No	Key-value pairs to filter by. A scalar value matches exactly; an array value matches any of the listed values

Response Codes:

200: Threads retrieved successfully
404: Agent or space not found
500: Failed to query threads

Update Thread

Update an existing conversation thread. All fields are optional.

Endpoint: PATCH /v1/spaces/{spaceId}/agent/{agentId}/thread/{threadId}

Authentication: Required

Path Parameters:

Parameter	Type	Required	Description
`spaceId`	string	Yes	Unique identifier for the space
`agentId`	string	Yes	Unique agent identifier
`threadId`	string	Yes	Unique thread identifier

Request Body:

{
  "title": "Billing Issue - Resolved",
  "status": "completed",
  "metadata": {
    "priority": "low",
    "category": "support"
  }
}

Response:

{
  "threadId": "507f1f77bcf86cd799439033",
  "title": "Billing Issue - Resolved",
  "spaceId": "space_12345",
  "agentId": "507f1f77bcf86cd799439011",
  "status": "completed",
  "createdAt": "2025-10-09T09:15:00+00:00",
  "updatedAt": "2025-10-09T15:00:00+00:00",
  "lastMessageAt": "2025-10-09T10:15:00+00:00"
}

Example Request:

curl -X 'PATCH' \
  'https://agents.api.caip.bmw.cloud/v1/spaces/space_12345/agent/507f1f77bcf86cd799439011/thread/507f1f77bcf86cd799439033' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Billing Issue - Resolved",
    "status": "completed"
  }'

Response Codes:

200: Thread updated successfully
404: Thread, agent, or space not found
500: Failed to update thread

Delete Thread

Delete a conversation thread permanently.

Endpoint: DELETE /v1/spaces/{spaceId}/agent/{agentId}/thread/{threadId}

Authentication: Required

Path Parameters:

Parameter	Type	Required	Description
`spaceId`	string	Yes	Unique identifier for the space
`agentId`	string	Yes	Unique agent identifier
`threadId`	string	Yes	Unique thread identifier

Example Request:

curl -X 'DELETE' \
  'https://agents.api.caip.bmw.cloud/v1/spaces/space_12345/agent/507f1f77bcf86cd799439011/thread/507f1f77bcf86cd799439033' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response Codes:

204: Thread deleted successfully
404: Thread, agent, or space not found
500: Failed to delete thread

Messages

Messages are individual communications within a thread.

Create Message

Create a new message in a thread.

Endpoint: POST /v1/spaces/{spaceId}/agent/{agentId}/thread/{threadId}/message

Authentication: Required

Path Parameters:

Parameter	Type	Required	Description
`spaceId`	string	Yes	Unique identifier for the space
`agentId`	string	Yes	Unique agent identifier
`threadId`	string	Yes	Unique thread identifier

Request Body:

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "Hello, I need help with my billing issue."
    }
  ],
  "metadata": {
    "source": "chat"
  },
  "model": "gpt-4",
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 25,
    "total_tokens": 35
  }
}

Response:

{
  "messageId": "507f1f77bcf86cd799439044",
  "spaceId": "space_12345",
  "threadId": "507f1f77bcf86cd799439033",
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "Hello, I need help with my billing issue."
    }
  ],
  "metadata": {
    "source": "chat"
  },
  "model": "gpt-4",
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 25,
    "total_tokens": 35
  },
  "createdAt": "2025-10-09T10:15:00+00:00"
}

Example Request:

curl -X 'POST' \
  'https://agents.api.caip.bmw.cloud/v1/spaces/space_12345/agent/507f1f77bcf86cd799439011/thread/507f1f77bcf86cd799439033/message' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": "Hello, I need help with my billing issue."
      }
    ]
  }'

Response Codes:

201: Message created successfully
400: Invalid input data
404: Thread, agent, or space not found
500: Failed to create message

Fields:

Field	Type	Required	Description
`role`	string	Yes	Message role: `user`, `assistant`, `system`, `tool`
`content`	array	Yes	List of content objects, each with `type` (e.g., "text") and `text`
`metadata`	object	No	Additional metadata key-value pairs
`model`	string	No	Model used to generate the message
`usage`	object	No	Token usage: `prompt_tokens`, `completion_tokens`, `total_tokens`

Get Message

Get a specific message by ID.

Endpoint: GET /v1/spaces/{spaceId}/agent/{agentId}/thread/{threadId}/message/{messageId}

Authentication: Required

Path Parameters:

Parameter	Type	Required	Description
`spaceId`	string	Yes	Unique identifier for the space
`agentId`	string	Yes	Unique agent identifier
`threadId`	string	Yes	Unique thread identifier
`messageId`	string	Yes	Unique message identifier

Response:

{
  "messageId": "507f1f77bcf86cd799439044",
  "spaceId": "space_12345",
  "threadId": "507f1f77bcf86cd799439033",
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "Hello, I need help with my billing issue."
    }
  ],
  "createdAt": "2025-10-09T10:15:00+00:00"
}

Example Request:

curl -X 'GET' \
  'https://agents.api.caip.bmw.cloud/v1/spaces/space_12345/agent/507f1f77bcf86cd799439011/thread/507f1f77bcf86cd799439033/message/507f1f77bcf86cd799439044' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response Codes:

200: Message retrieved successfully
404: Message, thread, agent, or space not found

List Messages

List all messages in a thread. You can optionally filter by role using GET query parameters, or filter by metadata using the QUERY HTTP method with a JSON body.

Method	Endpoint
`GET`	`/v1/spaces/{spaceId}/agent/{agentId}/thread/{threadId}/message`
`QUERY`	`/v1/spaces/{spaceId}/agent/{agentId}/thread/{threadId}/message`

warning

Authentication: Required

Path Parameters:

Parameter	Type	Required	Description
`spaceId`	string	Yes	Unique identifier for the space
`agentId`	string	Yes	Unique agent identifier
`threadId`	string	Yes	Unique thread identifier

GET — Filter by role

Query Parameter	Type	Required	Description
`role`	string	No	Filter by role: `user`, `assistant`, `system`, `tool`

Example Request:

curl -X 'GET' \
  'https://agents.api.caip.bmw.cloud/v1/spaces/space_12345/agent/507f1f77bcf86cd799439011/thread/507f1f77bcf86cd799439033/message?role=user' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response:

[
  {
    "messageId": "507f1f77bcf86cd799439044",
    "spaceId": "space_12345",
    "threadId": "507f1f77bcf86cd799439033",
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": "Hello, I need help with my billing issue."
      }
    ],
    "createdAt": "2025-10-09T10:15:00+00:00"
  }
]

QUERY — Filter by metadata

Send a JSON body with a metadata object to filter messages by metadata key-value pairs. A scalar value matches exactly, an array value matches any of the listed values. The body is optional: omitting it returns all messages.

Example Request:

curl -X 'QUERY' \
  'https://agents.api.caip.bmw.cloud/v1/spaces/space_12345/agent/507f1f77bcf86cd799439011/thread/507f1f77bcf86cd799439033/message' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "metadata": {
      "source": "chat",
      "category": ["production", "support"]
    }
  }'

Response:

[
  {
    "messageId": "507f1f77bcf86cd799439044",
    "spaceId": "space_12345",
    "threadId": "507f1f77bcf86cd799439033",
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": "Hello, I need help with my billing issue."
      }
    ],
    "metadata": {
      "source": "chat",
      "category": "production"
    },
    "createdAt": "2025-10-09T10:15:00+00:00"
  }
]

Request Body Fields (QUERY only):

Field	Type	Required	Description
`metadata`	object	No	Key-value pairs to filter by. A scalar value matches exactly; an array value matches any of the listed values

Response Codes:

200: Messages retrieved successfully
404: Thread, agent, or space not found
500: Failed to query messages

Update Message

Update a specific message by ID. All fields are optional.

Endpoint: PATCH /v1/spaces/{spaceId}/agent/{agentId}/thread/{threadId}/message/{messageId}

Authentication: Required

Path Parameters:

Parameter	Type	Required	Description
`spaceId`	string	Yes	Unique identifier for the space
`agentId`	string	Yes	Unique agent identifier
`threadId`	string	Yes	Unique thread identifier
`messageId`	string	Yes	Unique message identifier

Request Body:

{
  "content": [
    {
      "type": "text",
      "text": "Updated message content."
    }
  ],
  "metadata": {
    "priority": "high"
  }
}

Response:

{
  "messageId": "507f1f77bcf86cd799439044",
  "spaceId": "space_12345",
  "threadId": "507f1f77bcf86cd799439033",
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "Updated message content."
    }
  ],
  "metadata": {
    "priority": "high"
  },
  "createdAt": "2025-10-09T10:15:00+00:00"
}

Example Request:

curl -X 'PATCH' \
  'https://agents.api.caip.bmw.cloud/v1/spaces/space_12345/agent/507f1f77bcf86cd799439011/thread/507f1f77bcf86cd799439033/message/507f1f77bcf86cd799439044' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "content": [
      {
        "type": "text",
        "text": "Updated message content."
      }
    ]
  }'

Response Codes:

200: Message updated successfully
404: Message, thread, agent, or space not found
500: Failed to update message

Delete Message

Delete a specific message by ID.

Endpoint: DELETE /v1/spaces/{spaceId}/agent/{agentId}/thread/{threadId}/message/{messageId}

Authentication: Required

Path Parameters:

Parameter	Type	Required	Description
`spaceId`	string	Yes	Unique identifier for the space
`agentId`	string	Yes	Unique agent identifier
`threadId`	string	Yes	Unique thread identifier
`messageId`	string	Yes	Unique message identifier

Example Request:

curl -X 'DELETE' \
  'https://agents.api.caip.bmw.cloud/v1/spaces/space_12345/agent/507f1f77bcf86cd799439011/thread/507f1f77bcf86cd799439033/message/507f1f77bcf86cd799439044' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response Codes:

204: Message deleted successfully
404: Message, thread, agent, or space not found
500: Failed to delete message

Vector Stores

Vector stores are collections of embeddings used for semantic search and RAG applications.

Create Vector Store

Create a new vector store for storing embeddings.

Endpoint: POST /v1/spaces/{spaceId}/vector-stores

Authentication: Required

Path Parameters:

Parameter	Type	Required	Description
`spaceId`	string	Yes	Unique identifier for the space

Request Body:

{
  "name": "Product Documentation",
  "description": "Embeddings for product documentation and FAQs",
  "embeddingModel": "text-embedding-3-small",
  "embeddingDimension": 1536,
  "chunkSize": 1000,
  "chunkOverlap": 200,
  "createdBy": {
    "qxId": "QX11111",
    "name": "John Doe"
  },
  "metadata": {
    "category": "documentation",
    "version": "1.0"
  }
}

Response:

{
  "vectorStoreId": "699eb4fb78db14c7c97a9a1e",
  "spaceId": "space_12345",
  "name": "Product Documentation",
  "description": "Embeddings for product documentation and FAQs",
  "embeddingModel": "text-embedding-3-small",
  "embeddingDimension": 1536,
  "chunkSize": 1000,
  "chunkOverlap": 200,
  "fileCounts": {
    "total": 0,
    "in_progress": 0,
    "completed": 0,
    "failed": 0
  },
  "embeddingCount": 0,
  "createdAt": "2025-10-09T10:00:00+00:00",
  "updatedAt": "2025-10-09T10:00:00+00:00",
  "createdBy": {
    "qxId": "QX11111",
    "name": "John Doe"
  }
}

Example Request:

curl -X 'POST' \
  'https://agents.api.caip.bmw.cloud/v1/spaces/space_12345/vector-stores' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Product Documentation",
    "description": "Embeddings for product documentation",
    "embeddingModel": "text-embedding-3-small",
    "embeddingDimension": 1536,
    "chunkSize": 1000,
    "chunkOverlap": 200
  }'

Response Codes:

201: Vector store created successfully
400: Invalid input data
404: Space not found
500: Failed to create vector store

Fields:

Field	Type	Required	Description
`name`	string	Yes	Name of the vector store (1-256 characters)
`description`	string	No	Description of the vector store's purpose (max 1024 characters)
`embeddingModel`	string	No	Embedding model name (default: `text-embedding-3-small`)
`embeddingDimension`	integer	No	Embedding vector dimensions (default: 1536)
`chunkSize`	integer	No	Size of text chunks in characters, 100-4096 (default: 1000)
`chunkOverlap`	integer	No	Overlap between chunks in characters, 0-1000 (default: 200)
`createdBy`	object	No	User creating the store (`qxId`, `name`)
`metadata`	object	No	Additional metadata key-value pairs

Supported Embedding Models:

text-embedding-3-small (OpenAI - supports variable dimensions: 1536 by default)
text-embedding-3-large (OpenAI - supports variable dimensions: 3072 by default)
titan-text-embeddings-v2 (AWS Bedrock - 1024 dimensions)

Supported Embedding Dimensions:

1024 - Compatible with titan-text-embeddings-v2
1536 - Compatible with text-embedding-3-small (default)
3072 - Compatible with text-embedding-3-large

Important Notes:

The embeddingModel and embeddingDimension fields are validated against the supported values above
Ensure that the chosen dimension is compatible with your embedding model
chunkSize and chunkOverlap only affect future embeddings; existing embeddings are not re-chunked
Attempting to create a vector store with unsupported models or dimensions will result in a 400 Bad Request error

Get Vector Store

Retrieve a specific vector store by its ID.

Endpoint: GET /v1/spaces/{spaceId}/vector-stores/{vectorStoreId}

Authentication: Required

Path Parameters:

Parameter	Type	Required	Description
`spaceId`	string	Yes	Unique identifier for the space
`vectorStoreId`	string	Yes	Unique vector store identifier

Response:

{
  "vectorStoreId": "699eb4fb78db14c7c97a9a1e",
  "spaceId": "space_12345",
  "name": "Product Documentation",
  "description": "Embeddings for product documentation and FAQs",
  "embeddingModel": "text-embedding-3-small",
  "embeddingDimension": 1536,
  "chunkSize": 1000,
  "chunkOverlap": 200,
  "fileCounts": {
    "total": 5,
    "in_progress": 0,
    "completed": 5,
    "failed": 0
  },
  "embeddingCount": 150,
  "createdAt": "2025-10-09T10:00:00+00:00",
  "updatedAt": "2025-10-09T14:30:00+00:00",
  "metadata": {
    "category": "documentation",
    "version": "1.0"
  }
}

Example Request:

curl -X 'GET' \
  'https://agents.api.caip.bmw.cloud/v1/spaces/space_12345/vector-stores/699eb4fb78db14c7c97a9a1e' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response Codes:

200: Vector store retrieved successfully
404: Vector store or space not found

List Vector Stores

List all vector stores in a specific space.

Endpoint: GET /v1/spaces/{spaceId}/vector-stores

Authentication: Required

Path Parameters:

Parameter	Type	Required	Description
`spaceId`	string	Yes	Unique identifier for the space

Response:

[
  {
    "vectorStoreId": "699eb4fb78db14c7c97a9a1e",
    "spaceId": "space_12345",
    "name": "Product Documentation",
    "description": "Embeddings for product documentation and FAQs",
    "embeddingModel": "text-embedding-3-small",
    "embeddingDimension": 1536,
    "chunkSize": 1000,
    "chunkOverlap": 200,
    "embeddingCount": 150,
    "createdAt": "2025-10-09T10:00:00+00:00",
    "updatedAt": "2025-10-09T14:30:00+00:00"
  }
]

Example Request:

curl -X 'GET' \
  'https://agents.api.caip.bmw.cloud/v1/spaces/space_12345/vector-stores' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response Codes:

200: Vector stores retrieved successfully
404: Space not found
500: Failed to retrieve vector stores

Update Vector Store

Update an existing vector store. All fields are optional. Note: changing chunkSize or chunkOverlap only affects future embeddings.

Endpoint: PUT /v1/spaces/{spaceId}/vector-stores/{vectorStoreId}

Authentication: Required

Path Parameters:

Parameter	Type	Required	Description
`spaceId`	string	Yes	Unique identifier for the space
`vectorStoreId`	string	Yes	Unique vector store identifier

Request Body:

{
  "name": "Updated Documentation Store",
  "description": "Updated description for the vector store",
  "chunkSize": 1500,
  "chunkOverlap": 300,
  "updatedBy": {
    "qxId": "QX11111",
    "name": "John Doe"
  },
  "metadata": {
    "category": "documentation",
    "version": "2.0"
  }
}

Response:

{
  "vectorStoreId": "699eb4fb78db14c7c97a9a1e",
  "spaceId": "space_12345",
  "name": "Updated Documentation Store",
  "description": "Updated description for the vector store",
  "embeddingModel": "text-embedding-3-small",
  "embeddingDimension": 1536,
  "chunkSize": 1500,
  "chunkOverlap": 300,
  "embeddingCount": 150,
  "createdAt": "2025-10-09T10:00:00+00:00",
  "updatedAt": "2025-10-09T16:00:00+00:00"
}

Example Request:

curl -X 'PUT' \
  'https://agents.api.caip.bmw.cloud/v1/spaces/space_12345/vector-stores/699eb4fb78db14c7c97a9a1e' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Updated Documentation Store",
    "updatedBy": {
      "qxId": "QX11111",
      "name": "John Doe"
    }
  }'

Response Codes:

200: Vector store updated successfully
400: Invalid input data
404: Vector store or space not found
500: Failed to update vector store

Delete Vector Store

Delete a vector store permanently. Warning: This action is irreversible and will delete all associated embeddings.

Endpoint: DELETE /v1/spaces/{spaceId}/vector-stores/{vectorStoreId}

Authentication: Required

Path Parameters:

Parameter	Type	Required	Description
`spaceId`	string	Yes	Unique identifier for the space
`vectorStoreId`	string	Yes	Unique vector store identifier

Response:

{
  "vectorStoreId": "699eb4fb78db14c7c97a9a1e",
  "deleted": true
}

Example Request:

curl -X 'DELETE' \
  'https://agents.api.caip.bmw.cloud/v1/spaces/space_12345/vector-stores/699eb4fb78db14c7c97a9a1e' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response Codes:

200: Vector store deleted successfully
404: Vector store or space not found
500: Failed to delete vector store

Embeddings

Embeddings are vector representations of text chunks stored in vector stores for semantic search.

Create Embeddings (Batch)

Create multiple embeddings in a vector store.

Endpoint: POST /v1/spaces/{spaceId}/vector-stores/{vectorStoreId}/embeddings

Authentication: Required

Path Parameters:

Parameter	Type	Required	Description
`spaceId`	string	Yes	Unique identifier for the space
`vectorStoreId`	string	Yes	Unique vector store identifier

Request Body:

{
  "embeddings": [
    [0.0123, -0.0456, 0.0789],
    [0.0234, -0.0567, 0.0891]
  ],
  "chunks": [
    "To reset your password, navigate to Settings > Account > Security.",
    "Password requirements: minimum 12 characters with uppercase, lowercase, and numbers."
  ],
  "documentIds": [
    "user_guide_2024",
    "user_guide_2024"
  ],
  "sequences": [1, 2],
  "metadata": [
    {
      "page": 5,
      "category": "security",
      "section": "account_management"
    },
    {
      "page": 5,
      "category": "security",
      "section": "password_policy"
    }
  ]
}

Response:

[
  {
    "embeddingId": "678901abc234def5678901",
    "vectorStoreId": "699eb4fb78db14c7c97a9a1e",
    "chunk": "To reset your password, navigate to Settings > Account > Security.",
    "documentId": "user_guide_2024",
    "sequence": 1,
    "metadata": {
      "page": 5,
      "category": "security"
    },
    "createdAt": "2025-10-09T11:00:00+00:00"
  },
  {
    "embeddingId": "678901abc234def5678902",
    "vectorStoreId": "699eb4fb78db14c7c97a9a1e",
    "chunk": "Password requirements: minimum 12 characters with uppercase, lowercase, and numbers.",
    "documentId": "user_guide_2024",
    "sequence": 2,
    "metadata": {
      "page": 5,
      "category": "security"
    },
    "createdAt": "2025-10-09T11:00:00+00:00"
  }
]

Example Request:

curl -X 'POST' \
  'https://agents.api.caip.bmw.cloud/v1/spaces/space_12345/vector-stores/699eb4fb78db14c7c97a9a1e/embeddings' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "embeddings": [[0.0123, -0.0456, 0.0789]],
    "chunks": ["Password reset instructions..."],
    "documentIds": ["user_guide_2024"],
    "sequences": [1],
    "metadata": [{"page": 5, "category": "security"}]
  }'

Response Codes:

201: Embeddings created successfully
400: Invalid input data or dimension mismatch
404: Vector store or space not found
500: Failed to create embeddings

Fields:

Field	Type	Required	Description
`embeddings`	array[array[float]]	Yes	List of embedding vectors. Each must match the vector store's `embeddingDimension` (1024, 1536, or 3072). All vectors in one batch must have the same dimension.
`chunks`	array[string]	No	Corresponding source text for each embedding
`documentIds`	array[string]	No	Document identifier for each embedding (groups chunks from the same source)
`sequences`	array[integer]	No	Sequential position of each chunk within its document (0-indexed)
`metadata`	array[object]	No	Per-embedding metadata objects for filtering and context

Important Notes:

Each embedding vector length must exactly match the vector store's embeddingDimension
All arrays (embeddings, chunks, documentIds, sequences, metadata) must have the same length
Supported dimensions: 1024, 1536, and 3072
Mismatched dimensions will result in a 400 Bad Request error
Generate embeddings using your embedding model before calling this API

List Embeddings

List all embeddings in a vector store.

Endpoint: GET /v1/spaces/{spaceId}/vector-stores/{vectorStoreId}/embeddings

Authentication: Required

Path Parameters:

Parameter	Type	Required	Description
`spaceId`	string	Yes	Unique identifier for the space
`vectorStoreId`	string	Yes	Unique vector store identifier

Response:

[
  {
    "embeddingId": "678901abc234def5678901",
    "vectorStoreId": "699eb4fb78db14c7c97a9a1e",
    "chunk": "To reset your password...",
    "documentId": "user_guide_2024",
    "sequence": 1,
    "metadata": {
      "page": 5,
      "category": "security"
    },
    "createdAt": "2025-10-09T11:00:00+00:00"
  }
]

Example Request:

curl -X 'GET' \
  'https://agents.api.caip.bmw.cloud/v1/spaces/space_12345/vector-stores/699eb4fb78db14c7c97a9a1e/embeddings' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response Codes:

200: Embeddings retrieved successfully
404: Vector store or space not found
500: Failed to retrieve embeddings

Delete Embeddings

Delete embeddings by IDs or delete all embeddings in a vector store. Warning: Deletion is permanent and cannot be undone.

Endpoint: DELETE /v1/spaces/{spaceId}/vector-stores/{vectorStoreId}/embeddings

Authentication: Required

Path Parameters:

Parameter	Type	Required	Description
`spaceId`	string	Yes	Unique identifier for the space
`vectorStoreId`	string	Yes	Unique vector store identifier

Request Body:

{
  "embeddingIds": ["678901abc234def5678901", "678901abc234def5678902"],
  "deleteAll": false
}

Response:

{
  "deleted": 2,
  "vectorStoreId": "699eb4fb78db14c7c97a9a1e"
}

Example Request:

curl -X 'DELETE' \
  'https://agents.api.caip.bmw.cloud/v1/spaces/space_12345/vector-stores/699eb4fb78db14c7c97a9a1e/embeddings' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "embeddingIds": ["678901abc234def5678901", "678901abc234def5678902"],
    "deleteAll": false
  }'

Response Codes:

200: Embeddings deleted successfully
400: Invalid request (must provide embeddingIds or deleteAll: true)
404: Vector store or space not found
500: Failed to delete embeddings

Vector Search

Perform semantic similarity search using vector embeddings. Essential for RAG applications.

Search by Vector

Find the most similar embeddings using cosine similarity.

Endpoint: POST /v1/spaces/{spaceId}/vector-stores/{vectorStoreId}/search

Authentication: Required

Path Parameters:

Parameter	Type	Required	Description
`spaceId`	string	Yes	Unique identifier for the space
`vectorStoreId`	string	Yes	Unique vector store identifier

Request Body:

{
  "queryEmbedding": [0.0123, -0.0456, 0.0789, ...],
  "limit": 10,
  "metadataFilter": {
    "category": "security",
    "page": {"$gte": 1}
  },
  "scoreThreshold": 0.75,
  "includeEmbeddings": false
}

Response:

{
  "vectorStoreId": "699eb4fb78db14c7c97a9a1e",
  "results": [
    {
      "embeddingId": "678901abc234def5678902",
      "score": 0.92,
      "chunk": "To reset your password, navigate to Settings > Account > Security.",
      "documentId": "user_guide_2024",
      "sequence": 42,
      "metadata": {
        "page": 5,
        "category": "security"
      }
    },
    {
      "embeddingId": "678901abc234def5678903",
      "score": 0.87,
      "chunk": "Password requirements: minimum 12 characters...",
      "documentId": "user_guide_2024",
      "sequence": 43,
      "metadata": {
        "page": 5,
        "category": "security"
      }
    }
  ]
}

Example Request:

curl -X 'POST' \
  'https://agents.api.caip.bmw.cloud/v1/spaces/space_12345/vector-stores/699eb4fb78db14c7c97a9a1e/search' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "queryEmbedding": [0.0123, -0.0456, 0.0789],
    "limit": 5,
    "scoreThreshold": 0.7
  }'

Response Codes:

200: Search completed successfully
400: Invalid query embedding or parameters
404: Vector store or space not found
500: Search failed

Fields:

Field	Type	Required	Description
`queryEmbedding`	array[float]	Yes	Query vector (must match vector store dimensions exactly)
`limit`	integer	No	Max results (1-100, default: 10)
`metadataFilter`	object	No	MongoDB-style metadata filters
`scoreThreshold`	float	No	Minimum similarity score (0-1, recommended: 0.7-0.8)
`includeEmbeddings`	boolean	No	Include full embedding vectors in response (default: false)

Important Notes:

The queryEmbedding must have the exact same number of dimensions as the vector store's configured embeddingDimension
Supported dimensions: 1024, 1536, 3072
Dimension mismatches will result in a 400 Bad Request error
The API automatically uses the correct vector search index based on the vector store's dimension configuration

Score Interpretation:

0.9-1.0: Very similar, highly relevant
0.8-0.9: Highly relevant
0.7-0.8: Relevant
<0.7: Less relevant

Keyword Search

Perform full-text keyword search using MongoDB Atlas Search with BM25 ranking. Supports fuzzy matching and metadata filtering.

Search by Keywords

Find embeddings matching specific keywords in the chunk text.

Endpoint: POST /v1/spaces/{spaceId}/vector-stores/{vectorStoreId}/keyword-search

Authentication: Required

Path Parameters:

Parameter	Type	Required	Description
`spaceId`	string	Yes	Unique identifier for the space
`vectorStoreId`	string	Yes	Unique vector store identifier

Request Body:

{
  "queryText": "SDK configuration",
  "limit": 10,
  "metadataFilter": {
    "category": "documentation",
    "page": 1
  },
  "fuzzy": true
}

Response:

{
  "vectorStoreId": "699eb4fb78db14c7c97a9a1e",
  "results": [
    {
      "embeddingId": "678901abc234def5678905",
      "score": 0.92,
      "chunk": "To configure the SDK, create a config.json file in your project root...",
      "documentId": "sdk_guide_2024",
      "sequence": 15,
      "metadata": {
        "category": "documentation",
        "page": 1
      }
    }
  ]
}

Example Request:

curl -X 'POST' \
  'https://agents.api.caip.bmw.cloud/v1/spaces/space_12345/vector-stores/699eb4fb78db14c7c97a9a1e/keyword-search' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "queryText": "password reset",
    "limit": 5,
    "fuzzy": true
  }'

Response Codes:

200: Search completed successfully
400: Invalid query text or metadata filter
404: Vector store or space not found
500: Search failed

Fields:

Field	Type	Required	Description
`queryText`	string	Yes	Text query to search for (1-10,000 characters)
`limit`	integer	No	Max results (1-100, default: 10)
`metadataFilter`	object	No	Optional metadata filters (string fields use 'text' operator, numbers/booleans use 'equals' operator)
`fuzzy`	boolean	No	Enable fuzzy matching for typo tolerance (default: true, maxEdits: 2)

Advanced Keyword + Filter Search

Search with multiple keywords and strict metadata filtering. Supports AND/OR logic for keywords.

Endpoint: POST /v1/spaces/{spaceId}/vector-stores/{vectorStoreId}/keyword-filter-search

Authentication: Required

Request Body:

{
  "keywords": ["SDK", "configuration"],
  "filters": {
    "category": "documentation",
    "contentType": "api_reference",
    "page": 1
  },
  "limit": 10,
  "requireAllKeywords": false
}

Response:

{
  "vectorStoreId": "699eb4fb78db14c7c97a9a1e",
  "results": [
    {
      "embeddingId": "678901abc234def5678906",
      "score": 0.95,
      "chunk": "The SDK provides a comprehensive API for configuration...",
      "documentId": "sdk_guide_2024",
      "sequence": 42,
      "metadata": {
        "category": "documentation",
        "contentType": "api_reference",
        "page": 1
      }
    }
  ]
}

Example Request:

curl -X 'POST' \
  'https://agents.api.caip.bmw.cloud/v1/spaces/space_12345/vector-stores/699eb4fb78db14c7c97a9a1e/keyword-filter-search' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "keywords": ["password", "reset"],
    "filters": {"category": "security"},
    "requireAllKeywords": false
  }'

Response Codes:

200: Search completed successfully
400: Invalid keywords or filters
404: Vector store or space not found
500: Search failed

Fields:

Field	Type	Required	Description
`keywords`	array[string]	Yes	List of keywords to search (1-10 keywords)
`filters`	object	Yes	Required metadata filters (all must match - AND logic)
`limit`	integer	No	Max results (1-100, default: 10)
`requireAllKeywords`	boolean	No	Keyword logic: false = OR (at least one must match), true = AND (all must match). Default: false

Backend Query Logic:

requireAllKeywords: false → Keywords in 'should' clause (OR logic, at least one keyword must match)
requireAllKeywords: true → Keywords in 'must' clause (AND logic, all keywords must match)
Filters always in 'must' clause (all required filters must match)

Hybrid Search

Combine vector similarity and keyword search for optimal results. Recommended for production RAG applications.

Hybrid Search

Perform combined vector and keyword search with configurable weighting.

Endpoint: POST /v1/spaces/{spaceId}/vector-stores/{vectorStoreId}/hybrid-search

Authentication: Required

Request Body:

{
  "queryText": "How to reset password?",
  "queryEmbedding": [0.0123, -0.0456, 0.0789, ...],
  "limit": 10,
  "vectorWeight": 0.7,
  "metadataFilter": {
    "category": "security"
  },
  "scoreThreshold": 0.7,
  "includeEmbeddings": false
}

Response:

{
  "vectorStoreId": "699eb4fb78db14c7c97a9a1e",
  "results": [
    {
      "embeddingId": "678901abc234def5678902",
      "score": 0.89,
      "chunk": "To reset your password, navigate to Settings...",
      "documentId": "user_guide_2024",
      "sequence": 42,
      "metadata": {
        "category": "security"
      }
    }
  ]
}

Example Request:

curl -X 'POST' \
  'https://agents.api.caip.bmw.cloud/v1/spaces/space_12345/vector-stores/699eb4fb78db14c7c97a9a1e/hybrid-search' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "queryText": "password reset",
    "queryEmbedding": [0.0123, -0.0456, 0.0789],
    "vectorWeight": 0.7
  }'

Response Codes:

200: Search completed successfully
400: Invalid parameters
404: Vector store or space not found
500: Search failed

Fields:

Field	Type	Required	Description
`queryText`	string	Yes	Text query for keyword matching
`queryEmbedding`	array[float]	Yes	Query vector for semantic search
`limit`	integer	No	Max results (1-100, default: 10)
`vectorWeight`	float	No	Weight for vector search (0-1, default: 0.7). Remaining weight goes to keyword search
`metadataFilter`	object	No	Optional metadata filters
`scoreThreshold`	float	No	Minimum combined score threshold (0-1)
`includeEmbeddings`	boolean	No	Include full embedding vectors (default: false)

Weighting Guide:

0.7 (default): 70% vector, 30% keyword - Balanced, recommended for most use cases
0.8-0.9: Favor semantic similarity - Better for concept matching
0.5-0.6: More keyword emphasis - Better for exact term matching
1.0: Vector only
0.0: Keyword only

Search Evaluation

Evaluate search quality using RAG metrics. Useful for optimizing search strategies and parameters.

Evaluate Search Quality

Compare different search strategies and get performance metrics.

Endpoint: POST /v1/spaces/{spaceId}/vector-stores/{vectorStoreId}/evaluate

Authentication: Required

Request Body:

{
  "queryText": "How to reset password?",
  "queryEmbedding": [0.0123, -0.0456, ...],
  "relevantIds": ["emb_123", "emb_456"],
  "k": 10,
  "compareStrategies": true
}

Response:

{
  "metrics": {
    "precisionAtK": 0.9,
    "recallAtK": 0.85,
    "mrr": 0.95,
    "ndcg": 0.92,
    "averageScore": 0.91,
    "totalResults": 10,
    "relevantResults": 9
  },
  "comparison": {
    "Vector Only": {
      "precisionAtK": 0.8,
      "recallAtK": 0.7,
      "mrr": 0.9,
      "ndcg": 0.85,
      "averageScore": 0.88,
      "totalResults": 10,
      "relevantResults": 8
    },
    "Keyword Only": {
      "precisionAtK": 0.7,
      "recallAtK": 0.6,
      "mrr": 0.8,
      "ndcg": 0.75,
      "averageScore": 0.78,
      "totalResults": 10,
      "relevantResults": 7
    },
    "Hybrid": {
      "precisionAtK": 0.9,
      "recallAtK": 0.85,
      "mrr": 0.95,
      "ndcg": 0.92,
      "averageScore": 0.91,
      "totalResults": 10,
      "relevantResults": 9
    }
  },
  "recommendations": [
    "High precision - search is working well",
    "Best performing strategy: Hybrid"
  ]
}

Example Request:

curl -X 'POST' \
  'https://agents.api.caip.bmw.cloud/v1/spaces/space_12345/vector-stores/699eb4fb78db14c7c97a9a1e/evaluate' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "queryText": "How to reset password?",
    "queryEmbedding": [0.0123, -0.0456, 0.0789],
    "relevantIds": ["678901abc234def5678901", "678901abc234def5678902"],
    "k": 10,
    "compareStrategies": true
  }'

Response Codes:

200: Evaluation completed successfully
400: Invalid parameters
404: Vector store or space not found

Fields:

Field	Type	Required	Description
`queryText`	string	Yes	The search query text
`queryEmbedding`	array[float]	Yes	Query embedding vector
`relevantIds`	array[string]	Yes	Known relevant embedding IDs for evaluation (1+ IDs)
`k`	integer	No	Number of top results to evaluate (1-100, default: 10)
`compareStrategies`	boolean	No	Compare all search strategies (vector, keyword, hybrid). Default: true

Metrics Explained:

Precision@K: Proportion of retrieved results that are relevant (0-1, higher is better)
Recall@K: Proportion of relevant results that were retrieved (0-1, higher is better)
MRR (Mean Reciprocal Rank): 1 / rank of first relevant result (0-1, higher is better)
NDCG (Normalized Discounted Cumulative Gain): Quality of ranking (0-1, higher is better)

Version 1.0.0 (2025-01-09)

Initial Release

Agent management (CRUD operations)
Thread management for conversations
Message handling within threads
Model listing and selection
API key authentication (Authorization: Bearer <your-api-key> header)
MongoDB backend integration
Comprehensive error handling
Rate limiting support
CORS configuration for browser access
Vector Search & RAG Functionality

Version 1.1 (2026-08-04)

Minor Enhancements

Authentication examples updated to use the Authorization: Bearer <your-api-key> header consistently across all endpoints
Telemetry endpoint references removed from this API reference to reflect the current Agents API surface
Search documentation clarified to cover vector, keyword, keyword-filter, hybrid, and evaluation endpoints

Support

For questions, issues, or feature requests:

Email: caip-offboard-bmw@list.bmw.com
CAIP Portal: https://caip.bmw.cloud

External Documentation

Swagger API Docs

Contact

For support, contact: ConnectedAI@bmw.de

Overview​

Authentication​

Error Handling​

Common HTTP Status Codes​

Table of Contents​

Models​

List Available Models​

Agents​

Create Agent​

Get Agent​

List Agents​

Update Agent​

Delete Agent​

Threads​

Create Thread​

Get Thread​

List Threads​

Update Thread​

Delete Thread​

Messages​

Create Message​

Get Message​

List Messages​

Update Message​

Delete Message​

Vector Stores​

Create Vector Store​

Get Vector Store​

List Vector Stores​

Update Vector Store​

Delete Vector Store​

Embeddings​

Create Embeddings (Batch)​

List Embeddings​

Delete Embeddings​

Vector Search​

Search by Vector​

Keyword Search​

Search by Keywords​

Advanced Keyword + Filter Search​

Hybrid Search​

Hybrid Search​

Search Evaluation​

Evaluate Search Quality​

Version 1.0.0 (2025-01-09)​

Version 1.1 (2026-08-04)​

Support​

External Documentation​

Contact​

Overview

Authentication

Error Handling

Common HTTP Status Codes

Table of Contents

Models

List Available Models

Agents

Create Agent

Get Agent

List Agents

Update Agent

Delete Agent

Threads

Create Thread

Get Thread

List Threads

Update Thread

Delete Thread

Messages

Create Message

Get Message

List Messages

Update Message

Delete Message

Vector Stores

Create Vector Store

Get Vector Store

List Vector Stores

Update Vector Store

Delete Vector Store

Embeddings

Create Embeddings (Batch)

List Embeddings

Delete Embeddings

Vector Search

Search by Vector

Keyword Search

Search by Keywords

Advanced Keyword + Filter Search

Hybrid Search

Hybrid Search

Search Evaluation

Evaluate Search Quality

Version 1.0.0 (2025-01-09)

Version 1.1 (2026-08-04)

Support

External Documentation

Contact