Skip to main content
A protocol is the contract at the heart of Link. It declares a set of actions and the input and output shape of each — independent of any provider’s wire format. Callers code against the protocol; backends bind it to real providers. A protocol is a JSON document validated against Link’s meta-schema. Importing it stores the contract, generates an OpenAPI 3.1 specification for it, and makes its actions invokable.

​
Anatomy

{
  "$schema": "https://developer.hellgate.io/schemas/link-protocol/v1",
  "$id": "https://developer.hellgate.io/protocols/specter/v1",
  "name": "Specter v1",
  "version": "1.0.0",
  "actions": {
    "assess": {
      "method": "POST",
      "description": "Score a transaction for fraud risk.",
      "request": { "...": "..." },
      "responses": { "200": { "...": "..." } }
    }
  }
}
  • $id — the canonical URL identifying this protocol. Backends reference the protocol by this URL, and it is the join key between a protocol and the backends that implement it.
  • name / version — human-readable identity and a version string.
  • actions — the operations the protocol exposes (see below).
  • components — optional reusable schema definitions referenced across actions.

​
Actions

An action is a named operation — for example assess. Each action declares:
  • A method — one of POST, GET, PUT, PATCH, DELETE. Callers must invoke the action with this method.
  • A description — a human-readable summary.
  • A request schema — the input the caller sends.
  • A set of responses — keyed by HTTP status code, each with an output schema.
Action names may use dot notation to namespace related operations — for example notify.authorization, notify.chargeback, notify.fraud_report. For the exact field-by-field definition, see the Protocol schema reference.

​
Variants and discriminators

An action’s request can be either:
  • Monomorphic — a single request schema, or
  • Polymorphic — a discriminated union. A discriminator field in the request selects which variant applies.
For example, the assess action might discriminate on credential.type: a request with credential.type: "pan" resolves to the assess.pan variant, while credential.type: "token" resolves to assess.token. Backends implement variants by their full key (assess.pan), and Link rejects a backend that misses a required action or variant.

​
Versioning

The protocol version and its $id together identify a contract. A new version is a new protocol document with its own $id — existing backends keep targeting the version they were bound to, so contract changes never silently alter live behavior.

​
Meta-schema

Every protocol is validated against the Link protocol meta-schema (link-protocol-v1) at import time. A protocol that does not conform is rejected. The meta-schema is served by each instance: 
curl https://developer.hellgate.io/schemas/link-protocol/v1
Link Studio
By default, imports are restricted to Hellgate-published protocol URLs — this is what Link Connect uses. To author and import your own protocols, you need Link Studio; see the Protocol schema reference.

​
Generated OpenAPI

Because a protocol fully describes its actions and schemas, Link generates an OpenAPI 3.1 specification for each imported protocol. This is the contract a consumer of the protocol integrates against — the invoke surface for that specific protocol — and is retrieved per protocol: 
curl -H "Authorization: Bearer $TOKEN" \
  https://{instance}.eu1.on-hellgate.cloud/api/admin/protocols/specter-v1/openapi
Link operates at the protocol level: the invoke API is defined by whichever protocol you import, not by a single fixed Link API. To document the endpoints your callers use, generate the OpenAPI for that protocol.

​
Next steps

Backends

Bind a protocol to a real provider with credentials, authentication, and mapping rules.

Invocation

Call a protocol action and handle the result.