Minds Cloud Docs

POST/api/v1/responses

Create Response

This endpoint creates a response using a Mind. It provides an OpenAI-compatible Responses API with support for both streaming and non-streaming responses.

Path parameters

None.

Authorization

Name
MINDS_API_KEY
Type
string
Required
Description
Generate the Minds API key here and use it for authorization.

Request body

Name
input
Type
string | array
Required
Description
Input for the responses request, either a string or a list of messages. If not provided, the conversation ID must be specified.
Name
conversation
Type
string
Required
Description
Conversation ID for the responses request. If not provided, a new conversation will be created.
Name
model
Type
string
Required
Description
Name of the Mind that you created.
Name
stream
Type
boolean
Required
Description
Whether the response should be streamed. If set to true, partial message deltas will be sent as server-sent events. Defaults to false.
Name
tools
Type
array
Required
Description
Tools to use for the request. Currently supports the sql_query tool, which executes a SQL query directly against the Mind's datasources, bypassing the LLM pipeline. The Mind must have allow_direct_queries set to true in its parameters. Each tool object has the following fields:
- type (string) — Must be "sql_query".
- query (string) — The SQL SELECT query to execute.
- max_inline_rows (integer) — Maximum number of rows to return inline. Defaults to 10000. Must be between 1 and 10000.

Request

POST

/api/v1/responses

curl --request POST \
--url 'https://mdb.ai/api/v1/responses' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer MINDS_API_KEY' \
--data '{
    "model": "mind_name",
    "input": "What is the total sales for last month?",
    "stream": false
}'

Response (non-streaming)

{
    "id": "resp-12345678-1234-1234-1234-123456789012",
    "object": "response",
    "created_at": 1234567890,
    "status": "completed",
    "error": null,
    "model": "mind_name",
    "output": [
        {
            "type": "message",
            "id": "msg-12345678-1234-1234-1234-123456789012",
            "status": "completed",
            "role": "assistant",
            "content": [
                {
                    "type": "output_text",
                    "text": "The total sales for last month was $125,000."
                }
            ]
        }
    ]
}

Response (sql_query tool)

{
    "id": "resp-12345678-1234-1234-1234-123456789012",
    "object": "response",
    "created_at": 1234567890,
    "status": "completed",
    "error": null,
    "model": "mind_name",
    "output": [
        {
            "type": "query_result",
            "id": "msg-12345678-1234-1234-1234-123456789012",
            "status": "success",
            "query": "SELECT * FROM house_sales LIMIT 10",
            "column_names": ["id", "sale_date", "amount"],
            "data": [
                [1, "2024-01-15", 250000],
                [2, "2024-01-20", 310000]
            ],
            "total": 2,
            "has_more": false
        }
    ]
}

Response (streaming)

event: response.created
data: {"type":"response.created","sequence_number":1,"response":{"id":"resp-...","object":"response","created_at":1234567890,"status":"created","error":null,"model":"mind_name","output":[]}}

event: response.in_progress
data: {"type":"response.in_progress","sequence_number":2,"response":{"id":"resp-...","status":"in_progress",...}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","sequence_number":3,"response":{"item_id":"msg-...","type":"response.output_text.delta","delta":"The"}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","sequence_number":4,"response":{"item_id":"msg-...","type":"response.output_text.delta","delta":" total"}}

event: response.completed
data: {"type":"response.completed","sequence_number":5,"response":{"id":"resp-...","status":"completed",...}}

Response Status Values

The response object includes a status field that indicates the current state:

"created": Response has been created but not yet started
"in_progress": Response is being generated
"completed": Response generation is complete

Error Responses

400 Bad Request:
- Conversation mind mismatch (conversation belongs to a different mind)
- Invalid request parameters
403 Forbidden: Direct SQL queries are not allowed for this mind. Set allow_direct_queries to true in the mind's parameters to enable the sql_query tool.
500 Internal Server Error: Unexpected error processing the request