# 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](/guides/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](/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](/guides/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

```bash
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](/guides/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:

```bash
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:

```json
{
  "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:

```bash
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](/reference) has the full schema of every resource.

## 3. Handle errors

Every error answers with the same envelope:

```json
{
  "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](/guides/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](/guides/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](/guides/agent-quickstart) — the whole path for an AI agent, REST and MCP.
- [MCP server](/guides/mcp-server) — tools for assistants and agents.
- [Authentication](/guides/authentication) — the header, the key format, expiry and revocation.
- [Scopes](/guides/scopes) — what a key is allowed to read.
- [Pagination](/guides/pagination) — walking lists and dataset rows.
- [Rate limits](/guides/rate-limits) — how much you can call, and how to back off.
- [Webhooks](/guides/webhooks) — events pushed to you instead of polling.
