Skip to main content
This guide takes you from a token to a live invocation: import a protocol, register a backend that binds it to a real provider, invoke an action, and read the execution log. The examples use the specter-v1 protocol — the contract Specter uses to reach external risk engines — but the flow is identical for any protocol.

​
Prerequisites

  • A Link instance and its base URL (see Plans & Access).
  • A bearer token. The steps below note the scope each call needs — see Authentication.
  • Credentials for the provider you want to connect (this example uses a card-risk provider).
Your instance URL follows the pattern https://{instance}.eu1.on-hellgate.cloud — {instance} is your unique slug and eu1 is the current environment. Substitute it in the examples below, and set $TOKEN to a bearer token that holds the scope named in each step.

​
Steps

1

Import a protocol

A protocol is a versioned contract, imported by URL. The URL must return a document matching the protocol meta-schema. Requires admin:protocols:write.
curl -X POST https://{instance}.eu1.on-hellgate.cloud/api/admin/protocols/import \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://developer.hellgate.io/protocols/specter/v1"}'
The response includes the local_id you will use when invoking — here, specter-v1. Inspect the action requirements (useful when writing mapping rules):
curl -H "Authorization: Bearer $TOKEN" \
  https://{instance}.eu1.on-hellgate.cloud/api/admin/protocols/specter-v1/requirements/assess
2

Register a backend

A backend binds the protocol to a real provider — its host, credentials, an authentication strategy, and the mapping rules that translate the protocol request into the provider’s wire format and the response back. Requires admin:backends:write.
curl -X POST https://{instance}.eu1.on-hellgate.cloud/api/admin/backends \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "acme-risk",
    "name": "Acme Risk",
    "protocol": "https://developer.hellgate.io/protocols/specter/v1",
    "host": "api.acme.example",
    "credentials": { "token": "secret_key_test_..." },
    "auth_pipeline": { "source_type": "inline", "credential_type": "bearer" },
    "connections": {
      "assess.pan": {
        "endpoint": {
          "method": "POST",
          "path": "/v1/decisions",
          "content_type": "application/json",
          "timeout_ms": 5000
        },
        "request_mapping": {
          "body": {
            "cardNumber": "{{ $req.body.credential.pan.value | required }}",
            "amount": "{{ $req.body.transaction.amount | required }}",
            "currency": "{{ $req.body.transaction.currency | required }}"
          }
        },
        "response_mapping": {
          "200": {
            "return": "200",
            "body": {
              "type": "enum",
              "value": "{{ $res.body.status | map({ ACCEPTED: ALLOW, REJECTED: BLOCK, PENDING: REVIEW }) | required }}",
              "backend_reference": "{{ $res.body.id | omit_if_null }}"
            }
          }
        }
      }
    }
  }'
Mapping leaves are strings carrying the mustache-style template grammar — {{ expr | filter }}. Paths are scoped: $req.body.* and $req.header.* for the caller’s request, $res.body.* and $res.header.* for the provider’s response. See Backends for the full mapping model.
3

Invoke an action

Call the protocol action. The HTTP method must match the action’s declared method. Requires invoke:execute.
curl -X POST https://{instance}.eu1.on-hellgate.cloud/api/invoke/specter-v1/assess \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "credential": {
      "type": "pan",
      "pan": { "value": "4111111111111111", "expiry_month": 12, "expiry_year": 2030 }
    },
    "transaction": { "amount": 4999, "currency": "USD" }
  }'
Link validates the request, selects the matching backend, runs the mapping, and returns the protocol-shaped result:
{ "type": "enum", "value": "ALLOW", "backend_reference": "dec-xyz" }
The response carries an x-link-execution header with the execution ID, and server-timing with the call timing. If more than one enabled backend implements the action, Link returns 409 — disambiguate with ?backend=acme-risk. See Invocation for method matching, backend selection, and error codes.
4

Inspect the execution log

Every invocation is logged asynchronously. Fetch it by ID. Requires admin:executions:read.
curl -H "Authorization: Bearer $TOKEN" \
  https://{instance}.eu1.on-hellgate.cloud/api/admin/executions/<execution-id>
The entry contains the protocol-mapped result, the raw provider response, timing, the backend that handled the call, and any error detail.

​
Next steps

Protocols

Actions, variants, versioning, and the meta-schema.

Backends

The mapping engine, authentication strategies, and mocks.

Invocation

Method matching, backend selection, and error handling.