Skip to main content
Invocation is calling a protocol action. Link validates the request, selects a matching backend, runs the request mapping, dispatches the provider call, maps the response back to the protocol’s shape, and records an execution.
{protocol} is the protocol’s local ID and {action} is the action name. The call requires the invoke:execute scope.

​
The flow

  1. Validate the request against the action’s schema.
  2. Resolve the variant from the discriminator field, if the action is polymorphic.
  3. Select the backend that implements the action and variant.
  4. Map and dispatch the request to the provider.
  5. Map the response back to the protocol shape and log the execution.

​
Method matching

The HTTP method you invoke with must match the method the action declares in the protocol. A mismatch returns 405 METHOD_NOT_ALLOWED — it is not routed to a different action.

​
Selecting a backend

If exactly one enabled backend implements the action and variant, Link uses it. If several match, Link returns 409 CONFLICT; disambiguate with the backend query parameter:

​
Results

A successful invocation returns the protocol-shaped result. Its shape is defined entirely by the protocol — for the specter-v1 assess action, that is an enum outcome:
Two response headers accompany every result:
  • x-link-execution — the execution ID; use it to fetch the audit entry.
  • server-timing — total and external-call timing, in milliseconds.

​
Mapping errors

When the provider call completes but mapping cannot produce a valid result, Link returns a protocol error result rather than failing silently. The source field tells you where it originated:
source tells you where the error originated: backend (the provider returned an error you mapped through), mapping (a required leaf could not resolve), transport (the provider was unreachable or timed out), encryption (message-level encryption failed), or mock (a configured mock returned an error). Transport and encryption failures carry HTTP 502; the rest use the status from the response mapping.

​
Error codes

​
Execution log

Every invocation — success or failure — is logged asynchronously. Fetch an entry by ID with the admin:executions:read scope:
The entry contains the mapped protocol result, the raw provider response, timing, the backend that handled the call, and any error detail — so you can verify a round trip without provider-side tooling.

​
Next steps

Backends

Configure the mapping that shapes each request and response.

Quickstart

Run the full flow end to end.