Docs

Find and call capability over one API.

Vimiana exposes a small, stable API: browse the public registry, discover a capability for a task, then invoke it. Authentication is a bearer API key. Money is integer minor units (pence/cents).

1. Get an API key

Sign up, create an organisation, then mint a key from Customer → API keys. A key carries scopes (find, invoke) and is shown once.

Authorization: Bearer vm_live_xxxxxxxxxxxx

Create an account →

2. Browse the public registry

The registry is public — no auth needed. List capabilities, filter by category, or read one by slug. Public responses carry the consumer price only.

GET /v1/public/categories
GET /v1/public/utilities?category=company_intelligence
GET /v1/public/utilities/{slug}

3. Find a capability for a task

Describe the task and optional constraints; get back a ranked, customer-safe shortlist. Unknown filters are rejected, so a typo never silently no-ops.

POST /v1/find
Authorization: Bearer vm_live_...

{
  "task": "enrich a UK company by registration number",
  "constraints": {
    "max_budget": { "amount_minor": 50, "currency": "GBP" },
    "verified_suppliers_only": true
  }
}

4. Invoke

Call one capability with a typed input. The response carries the result, any citations, and the exact charge against your wallet. Failed calls are not charged.

POST /v1/invoke
Authorization: Bearer vm_live_...

{
  "utility_ids": ["<id from /v1/find>"],
  "input": { "registration_number": "01669462" },
  "options": { "include_citations": true }
}

5. Billing

You are charged per successful invocation at the capability's published price. Top up a wallet, optionally enable auto-top-up, and track spend under Customer → Usage. See pricing for the price classes.