mivia

mivia / docs / rest-api

REST api

One endpoint shape, five methods. Base URL:

codetext
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 for the failure table and 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:

fieldtyperequirednotes
textstringyesthe single record to extract
dumpbooleannostream mode: one record per line, stack traces grouped atomically
codebash
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):

codejson
{
  "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:

fieldtyperequirednotes
textstringyesthe multi-line dump to group
schemastringyesbuilt-in or registered schema name to fill
codebash
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):

codejson
{
  "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:

fieldtyperequirednotes
textstringyesthe candidates to rank and the criterion
candidatesarray of stringsyesthe candidates to rank
codebash
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):

codejson
{
  "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:

fieldtyperequirednotes
textstringyesthe content to grade
anchorsarray of stringsnocustom severity anchors; default is the canonical four tiers
codebash
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):

codejson
{
  "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:

fieldtyperequirednotes
requeststringyesthe user request to judge against the catalogue
toolsarraynooptional tool catalogue: BFCL-style specs, a {name: description} map, or a list of names
codebash
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):

codejson
{
  "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
  }
}
← AuthenticationMCP →