Innerva

API reference

Innerva API v0.1.0 · generated from the OpenAPI document this deployment serves

The live Innerva HTTP contract. Paths are added only when their handlers, authentication requirements, validation, and tests are implemented.

Protected operations carry a P-256 HTTP Message Signature and a fresh Innerva-Nonce. Credential-bearing POST operations also send Authorization, Content-Digest, and Idempotency-Key, as listed below. Use a client SDK where possible: each implements the canonical signing, callback binding, and stream processing the protocol requires, and is verified against shared conformance vectors.

This deployment: https://stg.innerva.net

Operations

`GET /.well-known/innerva`

Discover the protocol endpoints and supported profile.

Operation ID getDiscovery

Responses

200 application/json

Discovery

Protocol discovery metadata.

`POST /v1/access-requests`

Create an access request and receive a customer interaction link.

Operation ID createAccessRequest

Parameters

Content-Digest

header · string · required · length 16–128

Innerva-Nonce

header · string · required · pattern ^[A-Za-z0-9_-]{16,128}$

Signature-Input

header · string · required · length 16–2048

Signature

header · string · required · length 16–2048

Idempotency-Key

header · string · optional · length 1–128

Scopes an exact create-response replay to this proof key, route, and signed body.

Request body

AccessRequest as application/json, required.

Responses

200 application/json

AccessRequestCreated

Access request created or an idempotent result replayed.

default application/problem+json

Problem

Request rejected.

`POST /v1/access-requests/{id}/continue`

Exchange a completed interaction for an inference capability.

Operation ID continueAccessRequest

Parameters

id

path · ResourceID · required · pattern ^ar_[a-z2-7]{26}$

Authorization

header · string · required · length 16–128

Send the issued opaque credential as Innerva <token>.

Content-Digest

header · string · required · length 16–128

Innerva-Nonce

header · string · required · pattern ^[A-Za-z0-9_-]{16,128}$

Signature-Input

header · string · required · length 16–2048

Signature

header · string · required · length 16–2048

Idempotency-Key

header · string · required · length 1–128

Required so a credential-consuming operation can safely return the same success response after response loss.

Request body

ContinuationRequest as application/json, required.

Responses

200 application/json

CapabilityResponse

A new inference capability and its management credential, or the exact prior response for an idempotent retry.

default application/problem+json

Problem

Request rejected.

`DELETE /v1/capabilities/{id}`

Revoke a capability and its grant.

Operation ID revokeCapability

Parameters

id

path · ResourceID · required · pattern ^cap_[a-z2-7]{26}$

Authorization

header · string · required · length 16–128

Send the issued opaque credential as Innerva <token>.

Innerva-Nonce

header · string · required · pattern ^[A-Za-z0-9_-]{16,128}$

Signature-Input

header · string · required · length 16–2048

Signature

header · string · required · length 16–2048

Responses

204

Capability and grant revoked.

default application/problem+json

Problem

Request rejected.

`POST /v1/capabilities/{id}/rotate`

Rotate an inference capability.

Operation ID rotateCapability

Parameters

id

path · ResourceID · required · pattern ^cap_[a-z2-7]{26}$

Authorization

header · string · required · length 16–128

Send the issued opaque credential as Innerva <token>.

Content-Digest

header · string · required · length 16–128

Innerva-Nonce

header · string · required · pattern ^[A-Za-z0-9_-]{16,128}$

Signature-Input

header · string · required · length 16–2048

Signature

header · string · required · length 16–2048

Idempotency-Key

header · string · required · length 1–128

Required so a credential-consuming operation can safely return the same success response after response loss.

Request body

EmptyRequest as application/json, required.

Responses

200 application/json

CapabilityResponse

A rotated inference capability, or the exact prior successor for an idempotent retry.

default application/problem+json

Problem

Request rejected.

`POST /v1/responses`

Stream a metered inference response.

Operation ID createInferenceResponse

Parameters

Authorization

header · string · required · length 16–128

Send the issued opaque credential as Innerva <token>.

Content-Digest

header · string · required · length 16–128

Innerva-Nonce

header · string · required · pattern ^[A-Za-z0-9_-]{16,128}$

Signature-Input

header · string · required · length 16–2048

Signature

header · string · required · length 16–2048

Idempotency-Key

header · string · required · length 1–128

Required so a credential-consuming operation can safely return the same success response after response loss.

Request body

InferenceRequest as application/json, required.

Responses

200 text/event-stream

string

A normalized text response streamed as server-sent events. The stream starts with one response.created event, may contain response.output_text.delta events, and ends with exactly one response.completed, response.incomplete, or error event. Each SSE event has one event field naming the event and one data field whose JSON object matches InferenceCreatedEvent, InferenceDeltaEvent, InferenceTerminalEvent, or InferenceErrorEvent.

default application/problem+json

Problem

Request rejected.

Server-sent events

Each streamed event's event field names it, and its data field is a JSON object matching the schema listed here.

response.created: InferenceCreatedEvent
response.output_text.delta: InferenceDeltaEvent
response.completed, response.incomplete: InferenceTerminalEvent
error: InferenceErrorEvent

A terminal response's status is completed or incomplete. See InferenceTerminalResponse for when an incomplete response is charged 0 credits and what retrying it means.

Problem codes

Rejected requests return application/problem+json matching Problem. Branch on code.

empty_output_brake HTTP 429: The grant recently produced too many uncharged empty responses (ADR 0003). New requests are refused until older empty responses leave the rolling window; no operator action is needed.
idempotency_mismatch HTTP 409: The Idempotency-Key was already used with a different request.
inference_already_started HTTP 409: An inference operation already exists for this Idempotency-Key. Streamed content is never retained, so it cannot be replayed.
insufficient_credits HTTP 402: The grant does not have enough available credits for this request.
internal_error HTTP 500: The request could not be completed.
invalid_content_digest HTTP 400: Content-Digest is missing or does not match the request body.
invalid_content_type HTTP 400: Content-Type must be application/json.
invalid_credential HTTP 401: The Authorization credential is missing, malformed, or not valid for this operation.
invalid_proof HTTP 401: The HTTP message signature could not be verified.
invalid_proof_key HTTP 400: A public P-256 proof key is required.
invalid_request HTTP 400: The headers, path, or body do not match this contract or violate a policy bound.
invalid_spend_authorization HTTP 401: A staging spend authorization is missing, expired, or not issued for this proof key.
invalid_state HTTP 409: The operation is not valid in the resource's current state.
overloaded HTTP 503: The service is temporarily overloaded; retry later.
provider_unavailable HTTP 502: The inference provider could not start the request.
replayed_request HTTP 401: The signed request nonce has already been used.
request_expired HTTP 410: The access request is no longer active.
sandbox_unavailable HTTP 503: Access fulfillment is not configured in this environment.
streaming_unavailable HTTP 500: The HTTP server cannot stream this response.
unsupported_protocol_version HTTP 400: This server supports protocol version 0.1.

Schemas

`AccessRequest`

object

access_token: RequestedAccessToken · required
client: RequestClient · required
client_reference: string · optional · length 1–256
interact: RequestedInteraction · required
protocol_version: ProtocolVersion · required

`AccessRequestCreated`

object

continue: Continuation · required
expires_in: integer · required · value ≥ 1
instance_id: ResourceID · required
interact: object · required
interact.finish: string · required
interact.redirect: string · required · format uri
protocol_version: ProtocolVersion · required
request_id: ResourceID · required

`CapabilityResponse`

object

access_token: InferenceAccessToken · required

`Continuation`

object

access_token: OpaqueAccessToken · required
uri: string · required · format uri
wait: integer · required · value ≥ 0

`ContinuationRequest`

object

interact_ref: string · required · length 16–128

`Discovery`

object

access_request_endpoint

string · required · format uri

inference_endpoint

string · required · format uri

interaction_start_modes_supported

array<string> · required · items 1–1; item one of redirect

issuer

string · required · format uri

jwk_algorithms_supported

array<string> · required · items 1–1; item one of ES256

openapi_document

string · required · format uri

The OpenAPI document this deployment was generated from, served verbatim as application/yaml with a Content-Digest header.

proof_methods_supported

array<string> · required · items 1–1; item one of httpsig

protocol_version

ProtocolVersion · required

protocol_versions_supported

array<ProtocolVersion> · required · items 1–1

sdk_index

string · required · format uri

Human-readable index of client SDK downloads. The tarballs beneath it are embedded in the server binary at build time, so a download always matches the deployed protocol version.

`EmptyRequest`

object

`GrantedAccess`

object

actions: array<string> · required · item one of responses.create
credits: object · required
credits.grant_limit: integer · required · format int64
credits.grant_remaining: integer · required · format int64
credits.unit: string · required · one of innerva_credit
grant_id: ResourceID · required
models: array<string> · required · item one of innerva:standard
type: string · required · one of innerva_inference

`InferenceAccessToken`

object

access: array<GrantedAccess> · required · items 1–1
expires_in: integer · required · value ≥ 1
key: object · required
key.jkt: string · required
manage: object · required
manage.access_token: OpaqueAccessToken · required
manage.uri: string · required · format uri
value: string · required · length 32–128

`InferenceCreatedEvent`

object

response: InferenceCreatedResponse · required
type: string · required · one of response.created

`InferenceCreatedResponse`

object

id: ResourceID · required
model: string · required · one of innerva:standard
status: string · required · one of in_progress

`InferenceCredits`

object

capped: boolean · required
charged: integer · required · format int64; value ≥ 0
unit: string · required · one of innerva_credit

`InferenceDeltaEvent`

object

delta

string · required

The next normalized text fragment. Innerva does not persist it.

response_id

ResourceID · required

type

string · required · one of response.output_text.delta

`InferenceErrorEvent`

object

error: InferenceStreamError · required
type: string · required · one of error

`InferenceRequest`

object

input: string · required · length 1–32768
max_output_tokens: integer · required · format int64; value 1–4096
model: string · required · one of innerva:standard
stream: boolean · required · one of true

`InferenceStreamError`

object

code: string · required · one of incomplete_provider_stream, provider_stream_failed, invalid_provider_stream, accounting_failed
message: string · required

`InferenceTerminalEvent`

object

response: InferenceTerminalResponse · required
type: string · required · one of response.completed, response.incomplete

`InferenceTerminalResponse`

object

credits

InferenceCredits · required

id

ResourceID · required

model

string · required · one of innerva:standard

status

string · required · one of completed, incomplete

completed means output text was delivered and settled at measured usage. incomplete covers both a provider-declared incomplete response and a response that terminated without delivering any output text (for example a reasoning model consuming the entire output budget on reasoning tokens); in the no-output case the reservation is released and credits.charged is 0, so retrying an incomplete response with charged 0 repeats work that may again produce no output.

usage

InferenceUsage · required

`InferenceUsage`

object

input_units: integer · required · format int64; value ≥ 0
output_units: integer · required · format int64; value ≥ 0

`OpaqueAccessToken`

object

value: string · required · length 32–128

`Problem`

object

An RFC 9457 problem details object returned for every rejected request. Branch on code rather than title or detail; the x-problem-codes extension lists the codes the public API returns.

code: string · required
detail: string · optional
status: integer · required
title: string · required
type: string · required · format uri

`ProtocolVersion`

string · one of 0.1

`PublicJWK`

object

crv: string · required · one of P-256
kty: string · required · one of EC
x: string · required · pattern ^[A-Za-z0-9_-]{43}$
y: string · required · pattern ^[A-Za-z0-9_-]{43}$

`RequestClient`

object

display: object · required
display.name: string · required · length 1–120
display.uri: string · required · format uri; length ≤ 2048
key: object · required
key.jwk: PublicJWK · required
key.proof: string · required · one of httpsig

`RequestedAccess`

object

actions: array<string> · required · items 1–1; item one of responses.create
credits: RequestedCredits · required
duration: string · required · one of until_depleted_or_revoked
models: array<string> · required · items 1–1; item one of innerva:standard
type: string · required · one of innerva_inference

`RequestedAccessToken`

object

access: array<RequestedAccess> · required · items 1–1

`RequestedCredits`

object

minimum: integer · optional · format int64; value 1–1000000
suggested: integer · optional · format int64; value 1–1000000
unit: string · required · one of innerva_credit

`RequestedInteraction`

object

finish: object · required
finish.hash_method: string · required · one of sha-256
finish.method: string · required · one of redirect
finish.nonce: string · required · pattern ^[A-Za-z0-9_-]{16,128}$
finish.uri: string · required · format uri; length ≤ 2048
start: array<string> · required · items 1–1; item one of redirect

`ResourceID`

string · pattern ^[a-z][a-z0-9]{1,15}_[a-z2-7]{26}$; length 29–43

Also available: OpenAPI document · client SDKs · Innerva home