Client API reference

Authentication and prerequisites

Base URL: https://api.modelvia.dev. Send Authorization: Bearer $MODELVIA_CLIENT_KEY with the dedicated mgt_ integration key from operator-assisted onboarding. This is a backend management credential. Keep it out of browser JavaScript, mobile bundles, shared logs and customer-visible responses.

Your active client account defines the owning business, payer, allowed models and ceilings. Establish billing identity, accepted rates, service entitlement and customer commercial policies with Modelvia before serving real usage. Creating records does not activate terms. Start with Customers, projects and keys for the complete sequence.

JSON requests use Content-Type: application/json. Successful operations return HTTP 200, including creates. Refusals return {"error":"code"}. The invoice document route returns HTML. No client-key request requires or accepts an operator secret.

Supported operations

Replace path parameters with the exact IDs you retain on your server. Customer/project path IDs use letters, numbers, underscores, periods or hyphens; prefer a business prefix. Key IDs are 16 lowercase hexadecimal characters.

Provisioning request bodies

The JSON examples on the customer setup guide come from this same OpenAPI contract. All caps are exact integer strings in nano-AUD; 1 AUD is 1,000,000,000 nano-AUD. They must fit your agreed parent account.

Key lifecycle and retries

Mint/rotate responses contain key and public record; rotation additionally returns replaced, the previous key ID. The secret is shown once. Listing returns {"keys":[...]} without secret/hash fields.

Do not automatically replay key issuance. Repeating a mint POST issues another secret. A successful rotation revokes the original key; repeating that original rotation URL returns key_revoked (409), without recovering the replacement secret. An Idempotency-Key header does not provide response replay for either operation. Serialize issuance and list/reconcile keys after an unknown response before deliberately replacing a credential. Revocation preserves the original revokedAt on repeated calls.

# KEY_ID is the 16-character id from the key record, not the secret.
# Choose ONE operation deliberately. Do not run these as a sequence.
# Rotate: POST .../keys/$KEY_ID/rotate (returns a new one-time secret)
# Revoke: POST .../keys/$KEY_ID/revoke (returns the revoked public record)
curl --fail-with-body -X POST \
  "$MODELVIA_API_URL/v1/client/customers/$MODELVIA_CUSTOMER_ID/projects/$MODELVIA_PROJECT_ID/keys/$KEY_ID/revoke" \
  -H "Authorization: Bearer $MODELVIA_CLIENT_KEY"

Customer/project creates behave differently: an identical body returns the existing record without another write; a changed body returns 409 account_version_conflict. Inference has its own stable request-idempotency rules.

Read one customer’s month

Set MODELVIA_PERIOD to YYYY-MM, or omit the query for the current month in Australia/Brisbane. Usage-summary accepts only one period and no other filters.

curl --fail-with-body \
  "$MODELVIA_API_URL/v1/client/customers/$MODELVIA_CUSTOMER_ID/usage-summary?period=$MODELVIA_PERIOD" \
  -H "Authorization: Bearer $MODELVIA_CLIENT_KEY"

{
  "period": "2026-09",
  "requests": 0,
  "tokens": {
    "input": "0",
    "output": "0"
  },
  "money": {
    "customerNetNanoAud": "0"
  },
  "monthlyCapNanoAud": "50000000000",
  "remainingNanoAud": "50000000000",
  "updatedAt": 1790200000000
}

This example is a valid empty month after a successful scoped read. A failed connection is unavailable, not zero. Monetary totals can be null; input tokens exclude cache reads/writes; remainingNanoAud is display headroom, not a promise of admission. updatedAt is epoch milliseconds.

Summary has no customer ID field: retain and check your own request context. Billing includes clientId and customerId; verify them before rendering. Usage totals sum the whole month at any volume; only the recent-requests list is paged, with requestsLimit (1–500) and requestsCursor from the previous recentRequestsPage.nextCursor. Never present a partial page as a complete period.

Build the customer console covers identity, display and privacy. Business-level analytics are not a customer-safe response and are intentionally outside this focused contract.

Invoices and payment methods

A usage estimate is not an issued invoice. The invoice names its seller; Square checkout does not change that owner. Method settings use the current clientId assertion and version. Customer payment actions also depend on the separate checkout surface and fresh server eligibility.

Checkout takes no amount or seller body. Direct-payment recording is provider bookkeeping for an exact full amount already received; it never charges the customer. An unresolved checkout must suppress all collection alternatives across reload, even if a fresh read says not_started. See payments and recovery before enabling either route.

The OpenAPI billing/invoice response schemas describe the verified fields. Tolerate additional response fields, but render or forward only the documented fields needed for your customer’s view. Never infer eligibility from a missing property.

Errors and recovery