# REST api

One endpoint shape, five methods. Base URL:

```text
https://api.mivia.app
```

Every call is `POST /v1/models/{api}/{method}` with a JSON body
and one bearer key. The answer is the model's own JSON, plus billing
and rate-limit headers. See [errors](/docs/errors) for the failure
table and [pricing](/docs/pricing) for what a call costs.

Self-hosted containers expose the same methods under `/v1/`
(`/v1/extract`, `/v1/structure`, and so on) plus `/v1/route`,
`/v1/repair`, and `/health`; the model card lists the full surface.

## Methods

### POST /v1/models/mivia-small-json/extract

Extract a structured JSON record from one free-text input: a ticket, a log line, a message.

Request body:

| field | type | required | notes |
| --- | --- | --- | --- |
| `text` | string | yes | the single record to extract |
| `dump` | boolean | no | stream mode: one record per line, stack traces grouped atomically |

```bash
curl -X POST https://api.mivia.app/v1/models/mivia-small-json/extract \
  -H "Authorization: Bearer mivia_..." \
  -H "Content-Type: application/json" \
  -d '{"text":"ERROR [auth]: token expired"}'
```

Response (200):

```json
{
  "records": [
    {
      "result": {
        "type": "log_event",
        "level": "ERROR",
        "component": "auth",
        "message": "token expired"
      },
      "meta": {
        "routed_by": "model",
        "valid": true,
        "retries": 1,
        "latency_ms": 1266.916
      }
    }
  ]
}
```

### POST /v1/models/mivia-small-json/structure

Structure a multi-line dump into grouped JSON sections: stack traces grouped, diffs kept atomic.

Request body:

| field | type | required | notes |
| --- | --- | --- | --- |
| `text` | string | yes | the multi-line dump to group |
| `schema` | string | yes | built-in or registered schema name to fill |

```bash
curl -X POST https://api.mivia.app/v1/models/mivia-small-json/structure \
  -H "Authorization: Bearer mivia_..." \
  -H "Content-Type: application/json" \
  -d '{"text":"ERROR [auth]: token expired","schema":"log_event"}'
```

Response (200):

```json
{
  "schema": "log_event",
  "record": {
    "type": "log_event",
    "level": "ERROR",
    "component": "auth",
    "message": "token expired"
  },
  "valid": true,
  "retries": 1,
  "routed_by": "declared",
  "model": "mivia-small-json",
  "latency_ms": 0.75
}
```

### POST /v1/models/mivia-small-json/select

Rank the candidates given in the input text, zero-shot.

Request body:

| field | type | required | notes |
| --- | --- | --- | --- |
| `text` | string | yes | the candidates to rank and the criterion |
| `candidates` | array of strings | yes | the candidates to rank |

```bash
curl -X POST https://api.mivia.app/v1/models/mivia-small-json/select \
  -H "Authorization: Bearer mivia_..." \
  -H "Content-Type: application/json" \
  -d '{"text":"which tool fits? sum two numbers","candidates":["calculate_sum","run_sql"]}'
```

Response (200):

```json
{
  "choice": "calculate_sum",
  "confidence": 0.9133,
  "status": "ok"
}
```

### POST /v1/models/mivia-small-json/grade

Grade the input's severity on a fixed four-tier scale.

Request body:

| field | type | required | notes |
| --- | --- | --- | --- |
| `text` | string | yes | the content to grade |
| `anchors` | array of strings | no | custom severity anchors; default is the canonical four tiers |

```bash
curl -X POST https://api.mivia.app/v1/models/mivia-small-json/grade \
  -H "Authorization: Bearer mivia_..." \
  -H "Content-Type: application/json" \
  -d '{"text":"ERROR [auth]: token expired"}'
```

Response (200):

```json
{
  "result": {
    "action": "act",
    "tier_index": 2,
    "tier": "error level: operation failures, faults, and errors that disrupted a task or transaction.",
    "tier_set": [
      2
    ],
    "score": 0.3404662807061354,
    "clarification": null
  },
  "anchors": [
    "info level: routine informational messages about normal successful operation and expected events.",
    "warning level: recoverable abnormal conditions that may need attention but are not failures.",
    "error level: operation failures, faults, and errors that disrupted a task or transaction.",
    "critical level: severe crashes, fatal errors, data loss, or complete system failure requiring immediate action."
  ]
}
```

### POST /v1/models/mivia-small-json/guard

Judge a proposed tool call; returns CALL, CLARIFY, or ABSTAIN.

Request body:

| field | type | required | notes |
| --- | --- | --- | --- |
| `request` | string | yes | the user request to judge against the catalogue |
| `tools` | array | no | optional tool catalogue: BFCL-style specs, a {name: description} map, or a list of names |

```bash
curl -X POST https://api.mivia.app/v1/models/mivia-small-json/guard \
  -H "Authorization: Bearer mivia_..." \
  -H "Content-Type: application/json" \
  -d '{"request":"calculate the sum of 15 and 30","tools":[{"name":"calculate_sum","description":"Calculate the sum of two numbers.","parameters":{"type":"object","properties":{"num1":{"type":"number"},"num2":{"type":"number"}},"required":["num1","num2"]}}]}'
```

Response (200):

```json
{
  "action": "CALL",
  "tool": "calculate_sum",
  "missing_parameters": null,
  "clarification_prompt": null,
  "record": {
    "type": "tool_call",
    "name": "calculate_sum",
    "arguments": "{\"num1\":15,\"num2\":30}",
    "result": ""
  },
  "meta": {
    "routed_by": "model",
    "valid": true,
    "retries": 0,
    "latency_ms": 7.698
  }
}
```