> ## Documentation Index
> Fetch the complete documentation index at: https://developer.hellgate.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Protocols

> A protocol is a versioned, schema-validated API contract: the actions callers invoke and the shape of each request and response.

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](/products/link/concepts/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

```json theme={null}
{
  "$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](/products/link/concepts/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:

```bash theme={null}
curl https://developer.hellgate.io/schemas/link-protocol/v1
```

<Badge color="green">Standalone</Badge>

<Note>
  On a [Bundled](/products/link/plans-and-access) instance, imports are restricted to the protocols that serve
  its Specter instance. To author and import **your own** protocols, you need a
  [Standalone](/products/link/plans-and-access) instance; see the
  [Protocol schema](/products/link/concepts/protocol-schema) reference.
</Note>

## 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:

```bash theme={null}
curl -H "Authorization: Bearer $TOKEN" \
  https://{instance}.eu1.on-hellgate.cloud/api/admin/protocols/specter-v1/openapi
```

<Info>
  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.
</Info>

## Next steps

<CardGroup cols={2}>
  <Card title="Backends" icon="plug" href="/products/link/concepts/backends">
    Bind a protocol to a real provider with credentials, authentication, and mapping rules.
  </Card>

  <Card title="Invocation" icon="bolt" href="/products/link/concepts/invocation">
    Call a protocol action and handle the result.
  </Card>
</CardGroup>