# REST API Reference
Version 8.0.1 of the IronVault REST API.
The API is behind the `api` cargo feature and is served by `iv serve`:
```bash
cargo build --release --features api
iv serve --port 8080
```
Every endpoint below is prefixed as shown and returns JSON. Unless an
endpoint is marked **no auth**, it requires a bearer token obtained from
`POST /api/v1/auth/token`:
```bash
curl -sX POST localhost:8080/api/v1/auth/token \
-H 'content-type: application/json' \
-d '{"passphrase":"..."}'
```
The machine-readable spec is served at `/api/v1/openapi.json` and lives at
[`.well-known/openapi.yaml`](https://github.com/nervosys/IronVault/blob/master/.well-known/openapi.yaml).
72 operations across 31 groups.
## Access Control
### `DELETE /api/v1/acl`
Revoke access from principal.
Request body:
| `principal` | `string` | yes | |
Responses:
- `200` -- Access revoked
### `GET /api/v1/acl`
List access control entries.
Responses:
- `200` -- ACL entries
### `POST /api/v1/acl`
Grant role to principal.
Request body:
| `principal` | `string` | yes | |
| `role` | `string` | yes | |
Responses:
- `200` -- Role granted
## Auth
### `POST /api/v1/auth/logout`
Revoke the presented token.
Responses:
- `200` -- Token revoked
### `POST /api/v1/auth/token`
Get JWT authentication token.
**No auth** -- callable without a bearer token.
Request body:
| `passphrase` | `string` | yes | |
Responses:
- `200` -- JWT token
## Backups
### `GET /api/v1/backups/history`
Get backup history.
Responses:
- `200` -- Backup history
### `GET /api/v1/backups/schedules`
List backup schedules.
Responses:
- `200` -- Schedule list
### `POST /api/v1/backups/schedules`
Create or update backup schedule.
Request body:
| `vault` | `string` | yes | |
| `interval` | `string` | yes | |
| `hour` | `integer` | no | |
Responses:
- `200` -- Schedule set
## Benchmarks
### `GET /api/v1/models/{name}/benchmarks`
Show benchmark scores for a model.
Path parameters:
- `name`
Responses:
- `200` -- Benchmark scores
### `POST /api/v1/models/{name}/benchmarks`
Record a benchmark score.
Path parameters:
- `name`
Request body:
| `version` | `integer` | yes | |
| `benchmark` | `string` | yes | |
| `score` | `number` | yes | |
| `unit` | `string` | yes | |
Responses:
- `201` -- Benchmark recorded
## Bundle
### `POST /api/v1/vault/export`
Export the active vault as a tar.gz bundle.
Responses:
- `200` -- The bundle
### `POST /api/v1/vault/import`
Import a vault bundle (tar.gz).
Responses:
- `200` -- Bundle imported
## Compliance
### `GET /api/v1/compliance`
Run compliance checks (FIPS 140-3, CVE, MITRE ATT&CK, CMMC 2.0).
Responses:
- `200` -- Compliance report
## Conversion
### `GET /api/v1/conversions`
List supported conversion paths.
**No auth** -- callable without a bearer token.
Responses:
- `200` -- Conversion paths
### `POST /api/v1/convert`
Convert model format.
Responses:
- `200` -- Conversion result
## Diffing
### `POST /api/v1/models/diff`
Diff two model artifacts at the tensor level.
Request body:
| `left` | `string` | yes | `name` or `name@version`, resolved against the vault. A filesystem path is not accepted.
|
| `right` | `string` | yes | `name` or `name@version`, resolved against the vault |
Responses:
- `200` -- Diff report
## Discovery
### `GET /api/v1/introspect`
Return the CLI schema for agent bootstrapping.
**No auth** -- callable without a bearer token.
Responses:
- `200` -- CLI schema
## Download
### `POST /api/v1/models/pull`
Download a model from HuggingFace, Ollama, or a URL.
Request body:
| `source` | `string` | yes | huggingface://owner/repo, ollama://name, or https URL |
| `sha256` | `string` | no | |
| `token` | `string` | no | |
| `store` | `boolean` | no | |
| `name` | `string` | no | |
Responses:
- `200` -- Download report
## Evaluation
### `GET /api/v1/evaluations`
List evaluation results.
Responses:
- `200` -- Evaluation results
### `POST /api/v1/evaluations`
Record evaluation result.
Request body:
| `model` | `string` | yes | |
| `version` | `integer` | no | |
| `suite` | `string` | yes | |
| `metric` | `string` | yes | |
| `score` | `number` | yes | |
Responses:
- `201` -- Result recorded
### `GET /api/v1/evaluations/suites`
List known evaluation suites.
Responses:
- `200` -- Suite list
## Federation
### `GET /api/v1/federation/manifest`
Sync manifest advertising this node's models.
Responses:
- `200` -- Manifest of models and vector clocks
- `401` -- Missing or unrecognised peer key
- `404` -- Federation is not enabled on this node
### `GET /api/v1/federation/models/{name}/versions/{checkpoint_id}`
Fetch a model version from a federated peer.
Path parameters:
- `name`
- `checkpoint_id`
Responses:
- `200` -- Model bytes, sealed unless sealing is disabled
- `401` -- Missing or unrecognised peer key
- `404` -- Federation is not enabled, or no such version
### `PUT /api/v1/federation/models/{name}/versions/{checkpoint_id}`
Accept a model version pushed by a federated peer.
Path parameters:
- `name`
- `checkpoint_id`
Responses:
- `200` -- Version accepted
- `400` -- Unsealed body refused while sealing is enabled
- `401` -- Missing or unrecognised peer key
## Interop
### `POST /api/v1/models/{name}/register`
Register a model with a local inference engine (Ollama or LM Studio).
Path parameters:
- `name`
Request body:
| `engine` | `string` | yes | |
| `alias` | `string` | no | |
| `system_prompt` | `string` | no | |
Responses:
- `200` -- Registered
## License
### `POST /api/v1/license-scan`
Scan a stored model for licenses; returns SPDX identifiers.
Request body:
| `model` | `string` | yes | |
| `version` | `integer` | no | Defaults to the latest version |
Responses:
- `200` -- License findings
## Lineage
### `GET /api/v1/lineage-graph`
Show cross-model lineage graph.
Responses:
- `200` -- Lineage graph
### `POST /api/v1/lineage-graph`
Add edge to lineage graph.
Request body:
| `child` | `string` | yes | |
| `parents` | `array[string]` | yes | |
| `kind` | `string` | yes | |
Responses:
- `201` -- Edge added
## Model Cards
### `GET /api/v1/models/{name}/card`
Generate model card from vault metadata.
Path parameters:
- `name`
Responses:
- `200` -- Model card JSON
- `404` -- Model not found
### `POST /api/v1/models/{name}/card`
Create or overwrite a custom model card.
Path parameters:
- `name`
Responses:
- `201` -- Model card created
- `400` -- Invalid model card JSON
- `404` -- Model not found
### `POST /api/v1/models/{name}/card/generate`
Auto-generate a model card from existing metadata.
Path parameters:
- `name`
Responses:
- `200` -- Generated card
### `POST /api/v1/models/{name}/card/validate`
Validate a model card against the schema.
Path parameters:
- `name`
Responses:
- `200` -- Validation result
## Models
### `GET /api/v1/models`
List all models.
Responses:
- `200` -- List of models
### `GET /api/v1/models/{name}`
Get model (latest version binary).
Path parameters:
- `name`
Responses:
- `200` -- Model binary
### `POST /api/v1/models/{name}`
Store a new model.
Path parameters:
- `name`
Responses:
- `201` -- Model stored
### `POST /api/v1/models/{name}/validate`
Validate model integrity.
Path parameters:
- `name`
Responses:
- `200` -- Validation result
## Multi-Vault
### `GET /api/v1/vaults`
List registered vaults.
Responses:
- `200` -- Vault list
### `POST /api/v1/vaults`
Register a new vault.
Request body:
| `name` | `string` | yes | |
| `path` | `string` | yes | |
Responses:
- `201` -- Vault registered
### `POST /api/v1/vaults/{name}/activate`
Activate a registered vault.
Path parameters:
- `name`
Responses:
- `200` -- Vault activated
## Observability
### `GET /api/v1/audit`
Get audit log entries.
Responses:
- `200` -- Audit log
### `GET /api/v1/events`
Get recent events.
Responses:
- `200` -- Event stream
### `GET /api/v1/health`
Health check.
**No auth** -- callable without a bearer token.
Responses:
- `200` -- Service healthy
### `GET /api/v1/metrics`
Get vault metrics.
Responses:
- `200` -- Metrics data
### `GET /api/v1/openapi.json`
Get OpenAPI specification.
**No auth** -- callable without a bearer token.
Responses:
- `200` -- OpenAPI JSON spec
## Plugins
### `GET /api/v1/plugins`
List installed plugins.
Responses:
- `200` -- Plugin list
## Policies
### `PUT /api/v1/models/{name}/policy`
Set retention policy for model.
Path parameters:
- `name`
Request body:
| `max_versions` | `integer` | no | |
| `max_age_days` | `integer` | no | |
| `keep_minimum` | `integer` | no | |
Responses:
- `200` -- Policy set
### `GET /api/v1/policies`
List all retention policies.
Responses:
- `200` -- Policy list
## Profiles
### `GET /api/v1/profiles`
List configuration profiles.
Responses:
- `200` -- Profile list
### `POST /api/v1/profiles`
Create configuration profile.
Request body:
| `name` | `string` | yes | |
| `description` | `string` | no | |
| `overrides` | `object` | no | |
Responses:
- `201` -- Profile created
### `POST /api/v1/profiles/{name}/activate`
Activate configuration profile.
Path parameters:
- `name`
Responses:
- `200` -- Profile activated
## Quantization
### `POST /api/v1/quantization/estimate`
Estimate quantized output size.
Request body:
| `model` | `string` | yes | |
| `method` | `string` | yes | |
Responses:
- `200` -- Size estimate
### `GET /api/v1/quantization/profiles`
List quantization profiles.
Responses:
- `200` -- Quantization profiles
### `POST /api/v1/quantization/profiles`
Set quantization profile for model.
Request body:
| `model` | `string` | yes | |
| `method` | `string` | yes | |
| `version` | `integer` | no | |
| `bits` | `integer` | no | |
Responses:
- `200` -- Profile set
## RAG
### `POST /api/v1/rag/documents`
Add document to RAG knowledge base.
Request body:
| `content` | `string` | yes | |
| `metadata` | `object` | no | |
Responses:
- `201` -- Document stored
- `400` -- Empty content
### `POST /api/v1/rag/search`
Search RAG knowledge base.
Request body:
| `query` | `string` | yes | |
| `limit` | `integer` | no | |
Responses:
- `200` -- Search results
- `400` -- Empty query
## Safety
### `POST /api/v1/models/{name}/scan`
Scan a model for unsafe pickle opcodes / patterns.
Path parameters:
- `name`
Request body:
| `version` | `integer` | no | |
Responses:
- `200` -- Scan report
## Signing
### `POST /api/v1/models/{name}/sign`
Generate an HMAC-SHA256 signature for a model.
Path parameters:
- `name`
Request body:
| `version` | `integer` | no | |
| `identity` | `string` | no | |
| `key` | `string` | no | HMAC key (or resolved via KMS) |
Responses:
- `200` -- Signature generated
### `POST /api/v1/models/{name}/verify`
Verify a model signature.
Path parameters:
- `name`
Request body:
| `signature` | `object` | yes | The document returned by `/sign`, passed back verbatim |
| `version` | `integer` | no | |
| `key` | `string` | no | Without it, verification reports `signature_checked: false` rather than inferring validity from a hash the signature file supplies about itself.
|
Responses:
- `200` -- Verification result
## Tags
### `DELETE /api/v1/models/{name}/tags`
Remove tags from model.
Path parameters:
- `name`
Request body:
| `tags` | `array[string]` | no | |
Responses:
- `200` -- Tags removed
### `GET /api/v1/models/{name}/tags`
Get model tags.
Path parameters:
- `name`
Responses:
- `200` -- Model tags
### `POST /api/v1/models/{name}/tags`
Add tags to model.
Path parameters:
- `name`
Request body:
| `tags` | `array[string]` | no | |
Responses:
- `200` -- Tags added
### `POST /api/v1/search`
Search models by name, tags, or annotations.
Request body:
| `query` | `string` | no | |
| `tag` | `string` | no | |
Responses:
- `200` -- Search results
## Telemetry
### `GET /api/v1/telemetry/status`
Show telemetry configuration status.
Responses:
- `200` -- Telemetry status
## Vault
### `POST /api/v1/gc`
Run garbage collection.
Request body:
| `dry_run` | `boolean` | no | |
Responses:
- `200` -- GC report
### `GET /api/v1/stats`
Get vault statistics.
Responses:
- `200` -- Vault statistics
## Versions
### `GET /api/v1/models/{name}/lineage/{version}`
Get version lineage tree.
Path parameters:
- `name`
- `version`
Responses:
- `200` -- Lineage tree
### `GET /api/v1/models/{name}/versions`
List model versions.
Path parameters:
- `name`
Responses:
- `200` -- Version list
### `DELETE /api/v1/models/{name}/versions/{version}`
Delete a specific version.
Path parameters:
- `name`
- `version`
Responses:
- `204` -- Version deleted
### `GET /api/v1/models/{name}/versions/{version}`
Get specific version (binary download).
Path parameters:
- `name`
- `version`
Responses:
- `200` -- Model binary for specific version
## Webhooks
### `GET /api/v1/webhooks`
List webhook targets.
Responses:
- `200` -- Webhook list
### `POST /api/v1/webhooks`
Add webhook target.
Request body:
| `url` | `string` | yes | |
| `secret` | `string` | no | |
Responses:
- `201` -- Webhook created
### `DELETE /api/v1/webhooks/{id}`
Remove webhook target.
Path parameters:
- `id`
Responses:
- `200` -- Webhook removed