MuviaDevelopers
Guides: Getting started

Getting started

The Muvia public API lets an integration read its own company's Muvia data: the company, its projects, the datasets of each project and the rows they hold, and the nodes that collect the data. Version 1 is read-only.

Every request carries an API key. A key belongs to one company and only ever sees that company's data.

Building with an AI agent? Start with the Agent quickstart: the whole path, REST and MCP, with complete requests and responses.

Base URL

The base URL is https://api.muviabi.com/api/public, the server shown at the top of the API Reference.

Every v1 path starts with /v1, so the company's projects are at https://api.muviabi.com/api/public/v1/projects.

1. Get an API key

A company administrator issues keys in Muvia, under Settings → Company → API keys. A key has a name, a lifetime in days (90 by default, at most 3650) and the scopes the integration needs — for example settings_read to list projects and datasets_read to read datasets.

The key, mvk_<key_id>_<secret>, is shown once, when it is issued. Store it in a secret manager. A lost key cannot be recovered: revoke it and issue a new one.

2. Make your first request: who am I

export MUVIA_API_KEY="mvk_<key_id>_<secret>"
curl -H "X-Api-Key: $MUVIA_API_KEY" https://api.muviabi.com/api/public/v1/whoami

GET /v1/whoami answers with the key (its scopes and expiry), the company, the request limits, whether the MCP server is available and where the documentation is. Any valid key may call it, and it does not count toward the daily quota. Then list the projects:

curl -H "X-Api-Key: $MUVIA_API_KEY" https://api.muviabi.com/api/public/v1/projects

The answer is one page of the company's projects:

{
  "items": [
    {
      "id": "66f1a2b3c4d5e6f708192a3b",
      "name": "Line 3 monitoring",
      "description": "Sensors on the third production line",
      "is_default": true,
      "created_at": "2026-05-12T08:30:00Z",
      "updated_at": "2026-09-20T14:05:12Z"
    }
  ],
  "total": 1,
  "page": 1,
  "size": 50,
  "pages": 1
}

From a project, read its datasets, then a dataset's rows:

curl -H "X-Api-Key: $MUVIA_API_KEY" \
  https://api.muviabi.com/api/public/v1/projects/<project_id>/datasets

curl -H "X-Api-Key: $MUVIA_API_KEY" \
  "https://api.muviabi.com/api/public/v1/projects/<project_id>/datasets/<dataset_id>/rows?size=100"

The API Reference has the full schema of every resource.

3. Handle errors

Every error answers with the same envelope:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key",
    "status": 401,
    "hint": "Send a valid key in the X-Api-Key header; check it has not expired or been revoked in Settings > API keys, and that it belongs to this environment."
  }
}

Branch on code, never on message. The Errors guide lists every code.

Operations

Every REST operation, with its effect, whether it spends the company's daily quota, and the scope it needs. The OpenAPI document states the same on each operation as x-muvia-effect and x-muvia-quota.

Method Path Effect Counts toward the daily quota Scope
GET /v1/whoami read no none (any valid key)
GET /v1/company read yes settings_read
GET /v1/projects read yes settings_read
GET /v1/projects/{project_id} read yes settings_read
GET /v1/projects/{project_id}/datasets read yes datasets_read
GET /v1/projects/{project_id}/datasets/{dataset_id} read yes datasets_read
GET /v1/projects/{project_id}/datasets/{dataset_id}/rows read yes datasets_read
GET /v1/projects/{project_id}/nodes read yes nodes_read
GET /v1/projects/{project_id}/nodes/{node_id} read yes nodes_read

Version 1 of the REST API is read-only. The MCP server is where an agent can also write: each MCP tool carries an annotation that says whether it reads (readOnlyHint) or writes.

The datasets of a project are the project's own datasets plus the physical datasets of the project's database.

Next steps

  • Agent quickstart — the whole path for an AI agent, REST and MCP.
  • MCP server — tools for assistants and agents.
  • Authentication — the header, the key format, expiry and revocation.
  • Scopes — what a key is allowed to read.
  • Pagination — walking lists and dataset rows.
  • Rate limits — how much you can call, and how to back off.
  • Webhooks — events pushed to you instead of polling.