---
title: "Get relay configuration"
method: GET
path: "/relays/config"
---

# Get relay configuration

`GET /relays/config`

## Request

- Base URL: `https://api.endclose.com/v1`
- URL: `https://api.endclose.com/v1/relays/config`
- Auth: API key in header `X-API-KEY`

The routes document End Close is managing for the environment this API key belongs to: which processor webhook routes the relay accepts, how each is verified, and the field map that decides what leaves your network.

This is the only thing End Close tells a relay, and the status code is the whole message. A 200 is itself the statement that End Close owns this configuration, so the relay runs the document and hides its own config editor — there is no local copy that can drift. A 304 says the same and that nothing moved. A 404 means End Close is not managing this environment (nothing provisioned, or the switch turned off in Settings → Relay). It is a state, not a terminal answer: keep the document you already have, fall back to local configuration if you have one, and keep polling at your normal cadence — this is the only way you will hear that management was switched back on, and stopping forwarding on a 404 would turn a settings toggle into an outage.

Poll it with `If-None-Match`. The 200 carries a strong `ETag` identifying the document, which changes only when the document itself changes — a save that alters nothing keeps it — so the ordinary answer on a heartbeat is a 304 with no body. The API key alone resolves the environment: no parameters are needed, and rotating the key does not change the document. `routes` has the same content as the `routes:` block of the relay's `relay.yaml`; `environment` is informational.

## Headers

- `If-None-Match` string

## Response `200`

The provisioned routes document. The ETag header identifies it.

- RelayConfig
  - `environment` string: Name of the environment the API key belongs to, and that owns this document. Informational: the relay logs it and writes it into a comment in its stored copy.
  - `routes` RelayRoute[], required: The relay's routes document — the same content as the `routes:` block of `relay.yaml`. Never empty: an environment with no document gets a 404 instead.
    - `id` string, required: Unique lowercase slug for the route.
    - `source` 'payabli' | 'generic_hmac', required: The processor adapter that verifies and parses the webhook.
    - `auth` object, required: How inbound webhooks are verified. `mode: static_header` (header, secret_env, allowed_ips) or `mode: hmac` (header, algorithm, secret_env, signed_content, timestamp_header, tolerance_seconds, event_id, event_type). `secret_env` names an environment variable on the relay.
      - `mode` 'static_header' | 'hmac', required
      - `header` string
      - `secret_env` string, required
      - `allowed_ips` string[]
    - `events` string[]: Payload event types accepted by this route (glob `*` allowed). Others are dropped locally and never forwarded.
    - `map` object, required: How a webhook event becomes an End Close record: only fields named here are forwarded. Field references are dot-notation paths into the payload (`batchId`, `batch.id`) or `{ source, transform }` objects (transforms: trim, lowercase, hash).
      - `data_stream_key` string, required
      - `external_id` unknown, required
      - `amount` unknown, required
      - `direction` 'credit' | 'debit', required
      - `date` unknown
      - `description` unknown
      - `currency` string
      - `metadata` object: Extra fields to forward, as snake_case output name → field reference.
    - `max_body_bytes` integer

## Other responses

- `304`: Not Modified — End Close still owns this configuration and the document has not changed. No body; keep running what you have.
- `401`: Unauthorized — missing, invalid, or revoked API key
- `403`: Forbidden — the key is a run-scoped agent session key, not a relay key
- `404`: End Close is not managing the relay configuration for this environment. Keep the document you have and keep polling — a 404 is a state, not a terminal answer.

## Changes

- **2026-09-10** `7cb4a01bf0be`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/endclose/apis/end-close-api/changes/relays/config/get.md)

---

[API](https://skmtc.dev/endclose/apis/end-close-api.md) - [All operations](https://skmtc.dev/endclose/apis/end-close-api/llms.txt) - [OpenAPI document](https://skmtc.dev/endclose/apis/end-close-api/revisions/dfe0fde00f12?raw)