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.

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 (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
500 Internal Server Error: Unexpected error processing the request