> ## 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.
# Quickstart
> Import a protocol, register a backend, and invoke your first action end to end.
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](/products/specter/overview) 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](/products/link/plans-and-access)).
* A bearer token. The steps below note the scope each call needs — see [Authentication](/products/link/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
A protocol is a versioned contract, imported by URL. The URL must return a document matching the
[protocol meta-schema](/products/link/concepts/protocols#meta-schema). Requires `admin:protocols:write`.
```bash theme={null}
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):
```bash theme={null}
curl -H "Authorization: Bearer $TOKEN" \
https://{instance}.eu1.on-hellgate.cloud/api/admin/protocols/specter-v1/requirements/assess
```
A backend binds the protocol to a real provider — its host, credentials, an authentication strategy, and the
[mapping rules](/products/link/concepts/backends#mapping) that translate the protocol request into the
provider's wire format and the response back. Requires `admin:backends:write`.
```bash theme={null}
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](/products/link/concepts/backends) for the full mapping model.
Call the protocol action. The HTTP method must match the action's declared method. Requires `invoke:execute`.
```bash theme={null}
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:
```json theme={null}
{ "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](/products/link/concepts/invocation) for method matching, backend
selection, and error codes.
Every invocation is logged asynchronously. Fetch it by ID. Requires `admin:executions:read`.
```bash theme={null}
curl -H "Authorization: Bearer $TOKEN" \
https://{instance}.eu1.on-hellgate.cloud/api/admin/executions/
```
The entry contains the protocol-mapped result, the raw provider response, timing, the backend that handled
the call, and any error detail.
## Next steps
Actions, variants, versioning, and the meta-schema.
The mapping engine, authentication strategies, and mocks.
Method matching, backend selection, and error handling.