Mira API - Projects

In this guide we’ll explain how you can get started with Mira Projects when using the Mira API. Mira Projects allow you to ground Mira API responses with top level instructions, and Meltwater assets.

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.

Listing projects

The API provides access to your available projects through the GET /v3/mira/projects endpoint.

Note that this response will list the projects accessible to the user you have associated with your API key.

To retrieve projects:

curl -X GET \
  --url "https://api.meltwater.com/v3/mira/projects" \
  --header "Accept: application/json" \
  --header "apikey: **********"

Example response:

{
  "projects": [
    {
      "id": "proj-123456789",
      "name": "Brand Monitoring Q1 2024",
      "share_level": "user",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-03-20T14:45:00Z"
    },
    {
      "id": "proj-987654321",
      "name": "Competitor Analysis",
      "share_level": "company",
      "created_at": "2024-02-01T09:15:00Z",
      "updated_at": "2024-03-18T16:20:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 10,
    "total_items": 25,
    "total_pages": 3
  }
}

Pagination

The projects endpoint supports pagination with the following query parameters:

• page - Page number (default: 1, minimum: 1)
• page_size - Items per page (default: 10, minimum: 1, maximum: 100)
• sort - Sort order: “asc” or “desc” (default: “desc”)
• 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.

Example with pagination:

curl -X GET \
  --url "https://api.meltwater.com/v3/mira/projects?page=2&page_size=20&sort=asc" \
  --header "Accept: application/json" \
  --header "apikey: **********"

Project properties

Each project includes the following properties:

• id - Unique project identifier
• name - Human-readable project name
• share_level - Access level (“user”, “company”, “workspace”)
• created_at - ISO 8601 timestamp of project creation
• updated_at - ISO 8601 timestamp of last project update

Using projects for Mira requests

You can associate a project with your responses endpoint requests by including the project ID in the Project-ID header:

curl -X POST \
  --url "https://api.meltwater.com/v3/mira/responses" \
  --header "Accept: application/json" \
  --header "apikey: **********" \
  --header "Project-ID: proj-123456789" \
  --data '{
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "What are the latest trends in sustainable fashion?"
          }
        ]
      }
    ],
    "stream": false
  }'