Invoke a service

POST/v1/invoke

Validates the input against the service's declared input schema, calls the provider, and validates the response against the declared output schema. A response that violates the output schema is a failure: the provider has not delivered.

Requires an agent key. A developer API key is rejected with 403.

Headers

AuthorizationBearer <token>required

An agent key, prefixed var_ak_. Invokes and spends.

Idempotency-Keystringrequired

Scoped to the agent. Reusing a key returns the recorded outcome of the first call and does not invoke the provider again. Reusing a key against a different service is a 409.

Body

application/json

service_idstringrequired

The service to invoke.

inputobject

Passed to the provider unchanged. Must validate against the service's input_schema. A malformed input fails the invocation without calling the provider and without creating a transaction. Leave it out for a service that takes no input: a missing input is treated as {}, and still has to pass the schema, so a service with required fields rejects it.

Response

application/json

The provider returned output matching its declared schema.

request_idstringrequired

Unique to this request. Present on every response.

invocation_idstringrequired

outputobjectrequired

The provider's response, verbatim.

curl -X POST 'https://api.usevaris.com/v1/invoke' \  -H 'Idempotency-Key: 8f1a0c2e-3b4d-4f5a-9c6e-7d8f9a0b1c2d' \  -H 'Content-Type: application/json' \  -d '{  "service_id": "string"}'

{  "request_id": "var_req_fc8e8702-6a7f-4f3f-9147-748936e5fee1",  "invocation_id": "var_invk_HgD8njwg3gkTca",  "output": {    "echoed": "hello",    "received_at": "2026-09-19T02:41:12.996Z"  }}