Mira API - Responses
In this tutorial we’ll get you up and running with the responses feature of the Mira API.
The responses endpoint provides advanced chat completion capabilities with support for multiple input messages and enhanced context handling. It is our recommended approach for integration with AI assistants and agents.
Before you start
To run through this tutorial, you will need:
- Your Meltwater API token
- Access to the Mira API Beta program
Authentication
You need to provide your API token when you call any Meltwater API endpoint.
You provide the API token as a header called apikey, for example:
curl -X GET \
--url "https://api.meltwater.com/v3/searches" \
--header "Accept: application/json" \
--header "apikey: **********"For full details take a look at the Authentication page.
Responses endpoint
The API supports advanced chat completion through the POST /v3/mira/responses endpoint. This endpoint allows you to send multiple input messages and supports both streaming and non-streaming modes.
Body parameters for the endpoint include:
input- Array of input messages with role and contentstream-truefor streaming mode,falsefor non-streaming mode
Supported headers include:
Thread-ID- (optional) if provided, uses the existing thread; otherwise creates a new threadProject-ID- (optional) if provided, uses the specified Mira project for grounding responses
Query string parmaters include:
company_id- (optional) The ID of the company to access. If not provided, your default company will be used. See working with multiple companies for more details.
Input message format
Each input message should have:
role- The role of the message sender (e.g., “user”, “assistant”)content- Array of content items, each with:type- Content type (“text”)text- The actual text content
Non-streaming mode
For non-streaming responses, send a request to the POST /v3/mira/responses endpoint:
curl -X POST \
--url "https://api.meltwater.com/v3/mira/responses" \
--header "Accept: application/json" \
--header "apikey: **********" \
--data '{
"input": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "What are the latest trends in sustainable fashion?"
}
]
}
],
"stream": false
}'Example response:
{
"id": "resp-684afd4a43dc9fef57f754cb",
"object": "response",
"created": 1749745452,
"output": [
{
"id": "msg-123",
"role": "assistant",
"type": "message",
"status": "completed",
"content": [
{
"type": "text",
"text": "Based on recent industry analysis, here are the key sustainable fashion trends:\n\n1. **Circular Fashion Models** - Brands are increasingly adopting circular economy principles...",
"annotations": [
{
"news_document_citation": {
"citation_id": "cite-1",
"citation_type": "news",
"id": "doc-123",
"title": "Sustainable Fashion Report 2024",
"url": "https://example.com/article",
"source_name": "Fashion Weekly",
"publish_date": "2024-01-15",
"content": "Industry report on sustainable fashion trends...",
"rank": 1,
"reach": 50000,
"engagement": 1200,
"sentiment": "positive"
}
}
]
}
]
}
],
"output_text": "Based on recent industry analysis, here are the key sustainable fashion trends..."
}Streaming mode
For streaming responses, set the stream field to true:
curl -X POST \
--url "https://api.meltwater.com/v3/mira/responses" \
--header "Accept: application/json" \
--header "apikey: **********" \
--data '{
"input": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "What are the latest trends in sustainable fashion?"
}
]
}
],
"stream": true
}'The API will respond with server-sent events containing incremental updates to the response.
Multi-message conversations
The responses endpoint allows you to manage your own conversation history (and provide relevant messsages to Mira as a set of input messages), or alternatively Mira can maintain a conversation thread for you.
If you’d like Mira to answer based upon an ongoing thread managed by Mira you can use the optional Thread-ID header. Start a conversation by providing an input message and no Thread-ID header. Mira will then give a response including a Thread-ID response header for the new conversation. Return this Thread-ID header in follow up calls to have Mira use this thread context for answers.
When managing conversation state yourself, you don’t need to use the Thread-ID header since you’re providing the complete conversation context.
curl -X POST \
--url "https://api.meltwater.com/v3/mira/responses" \
--header "Accept: application/json" \
--header "apikey: **********" \
--data '{
"input": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "What are the latest trends in sustainable fashion?"
}
]
},
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "The main trends include circular fashion, eco-friendly materials, and transparency in supply chains."
}
]
},
{
"role": "user",
"content": [
{
"type": "text",
"text": "Can you provide specific examples of brands implementing these trends?"
}
]
}
],
"stream": false
}'Citations and annotations
Annotations provide additional context for responses from the Mira API. Currently the API only supports document citations. Document citations give you visibility into the documents considered by Mira when providing it’s answer to your prompt.
Citations can be matched to the output text from Mira based upon the following syntax: [^(citation_id)]. For example if the output text contains [^3] then this is referring to the annotation with citation_id of 3 in the annotations list.
For non-streaming mode, annotations are returned in the response payload under the path output.content.annotations.
For streaming mode, annotations are returned in response events under the path item.content.annotations. The following events can contain annotations:
response.completed
Note that citations below are illustrative. Title and content are included when possible, depending to compliance rules the system needs to apply for sources. Depending on the data source for citation different metrics will be available or not.
News document citations
Citations with citation_type of news_document_citation are references to news articles considered by Mira in it’s response.
{
"news_document_citation": {
"citation_type": "news_document_citation",
"citation_id": "14",
"id": "M7VJ0_BNa4jkk5PKzHdl_H2ByqY",
"url": "https://...",
"title": "Adidas Football...",
"content": "Today it was announced that...",
"source_name": "News Site",
"reach": 9504359,
"engagement": 39,
"social_echo": 39,
"outlet_types": [
"television"
],
"views": 20927
}
}Social document citations
Citations with citation_type of social_document_citation are references to social posts considered by Mira in it’s response.
{
"social_document_citation": {
"citation_type": "social_document_citation",
"citation_id": "13",
"id": "1757417640000_g8hdUz_RK8HxrjK2OfyxKqLlkW8A",
"title": "Adidas Football...",
"url": "https:...",
"content": "Today I read that....",
"platform": "facebook",
"author": "fb_user",
"publish_date": "2025-09-09T11:34:33.563000Z"
}
}Generic document citations
Citations with citation_type of other_document_citation are references to documents other than news articles and social posts.
{
"other_document_citation": {
"citation_type": "other_document_citation",
"citation_id": "14",
"id": "M7VJ0_BNa4jkk5PKzHdl_H2ByqY",
"title": "Adidas Football...",
"url": "https:...",
"content": "Today I read that....",
"views": 20927
}
}