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

# Erebor API Reference

> Management API for vaults, settings, merkle authorization, registries, upkeep, notifications, session keys, and pause controls.

Erebor is the SuperVaults management API. It powers vault reads, settings preparation, registries, merkle workflows, upkeep, users, pause controls, notification channels, and public vault data.

**Base URL:** `https://erebor.superform.xyz`

**Auth:** `Authorization: Bearer <jwt>` except public endpoints

<Note>
  For onchain changes, Erebor prepares calldata and the manager wallet signs the transaction. The REST request is not the state change; the signed transaction is.
</Note>

## Auth

| Endpoint              | Method | Description                           |
| --------------------- | ------ | ------------------------------------- |
| `/api/v1/auth/me`     | GET    | Current user, wallet, and vault roles |
| `/api/v1/auth/verify` | GET    | Lightweight JWT verification          |

## Vaults and Public Discovery

| Endpoint                                    | Method | Description              |
| ------------------------------------------- | ------ | ------------------------ |
| `/api/v1/public/vaults`                     | GET    | Public vault list        |
| `/api/v1/vaults`                            | GET    | Authenticated vault list |
| `/api/v1/vaults/{chain_id}/{vault_address}` | GET    | Full vault detail        |

Vault detail includes onchain identity, managers, fees, PPS, balances, TVL, upkeep information, activation state, and allocation data when available. Authenticated list responses may include `activation`; public vault responses include `upkeep_info` and `activation` when Erebor can compute them.

Public discovery depends on more than deployment. Erebor only surfaces vaults with known activation when `activation.is_discoverable` is true. If activation is unknown because a subgraph dependency is unavailable, the vault can still be returned with `activation` unset rather than treated as deleted.

## Vault Creation

| Endpoint                          | Method | Description                                          |
| --------------------------------- | ------ | ---------------------------------------------------- |
| `/api/v1/vaults/create/prepare`   | POST   | Prepare vault creation transaction                   |
| `/api/v1/vaults/create/confirm`   | POST   | Confirm creation transaction hash and start indexing |
| `/api/v1/vaults/create/jobs/{id}` | GET    | Poll creation job                                    |

`ConfirmCreateVaultRequest` can include `vault_config.redeem_timelock_seconds` for post-indexing settings.

Distribution metadata is handled by the dashboard/listing layer after vault address resolution. Onchain creation and Superform availability are separate states.

## Settings and Upkeep

| Endpoint                                                    | Method         | Description                                          |
| ----------------------------------------------------------- | -------------- | ---------------------------------------------------- |
| `/api/v1/settings/fee-config`                               | GET            | Read current fee config                              |
| `/api/v1/settings/fee-config/propose`                       | POST           | Prepare fee-config proposal transaction              |
| `/api/v1/settings/fee-config/execute`                       | POST           | Prepare fee-config execution transaction             |
| `/api/v1/settings/deviation-threshold`                      | GET            | Read PPS deviation threshold                         |
| `/api/v1/settings/deviation-threshold/update`               | POST           | Prepare deviation-threshold update transaction       |
| `/api/v1/settings/pps-expiration`                           | GET            | Read PPS expiration / staleness setting              |
| `/api/v1/settings/pps-expiration/propose`                   | POST           | Prepare PPS-expiration proposal transaction          |
| `/api/v1/settings/pps-expiration/execute`                   | POST           | Prepare PPS-expiration execution transaction         |
| `/api/v1/settings/pps-expiration/cancel`                    | POST           | Prepare PPS-expiration cancellation transaction      |
| `/api/v1/settings/redeem-timelock`                          | GET/PUT/DELETE | Read, update, or remove redeem timelock              |
| `/api/v1/settings/banned-hook-leaves`                       | GET            | Read banned hook leaves                              |
| `/api/v1/settings/banned-hook-leaves/update`                | POST           | Prepare banned-hook-leaf update transaction          |
| `/api/v1/settings/min-update-interval`                      | GET            | Read minimum PPS update interval                     |
| `/api/v1/settings/min-update-interval/propose`              | POST           | Prepare min-update-interval proposal transaction     |
| `/api/v1/settings/min-update-interval/execute`              | POST           | Prepare min-update-interval execution transaction    |
| `/api/v1/settings/min-update-interval/cancel`               | POST           | Prepare min-update-interval cancellation transaction |
| `/api/v1/settings/upkeep`                                   | GET/POST       | Read or prepare upkeep settings update               |
| `/api/v1/settings/upkeep/deposit`                           | POST           | Prepare upkeep deposit                               |
| `/api/v1/settings/upkeep/withdraw/propose`                  | POST           | Prepare upkeep withdrawal proposal                   |
| `/api/v1/settings/upkeep/withdraw/execute`                  | POST           | Prepare upkeep withdrawal execution                  |
| `/api/v1/redeem-timelocks`                                  | GET            | List redeem timelocks                                |
| `/api/v1/redeem-timelocks/bulk`                             | GET            | Bulk redeem timelock lookup                          |
| `/api/v1/vaults/{chain_id}/{vault_address}/redeem-timelock` | GET            | Read one vault's redeem timelock                     |

Upkeep data drives activation and discoverability in the dashboard. Operators should treat insufficient upkeep as a launch blocker.

Current upkeep responses use:

| Field                                    | Description                                                      |
| ---------------------------------------- | ---------------------------------------------------------------- |
| `upkeep_info.balance`                    | Current upkeep balance in raw token units.                       |
| `upkeep_info.token`                      | Upkeep token address on settings responses.                      |
| `upkeep_info.threshold.required_balance` | Required upkeep balance for activation.                          |
| `upkeep_info.threshold.shortfall`        | Remaining amount needed; `0` means the threshold is satisfied.   |
| `activation.is_active`                   | Whether the vault is eligible for keeper operations.             |
| `activation.is_discoverable`             | Whether the vault is surfaced on public listing responses.       |
| `activation.status`                      | `active` or `insufficient_upkeep`.                               |
| `activation.reason`                      | Optional explanation when inactive.                              |
| `withdrawal_status`                      | Pending withdrawal lifecycle; separate from `activation.status`. |

## Merkle Authorization

| Endpoint                                      | Method | Description                    |
| --------------------------------------------- | ------ | ------------------------------ |
| `/api/v1/merkle/configs/versions`             | GET    | Config version history         |
| `/api/v1/merkle/configs/version`              | GET    | Single config version          |
| `/api/v1/merkle/configs/active`               | GET    | Active config                  |
| `/api/v1/merkle/configs`                      | POST   | Create config                  |
| `/api/v1/merkle/configs/{id}`                 | GET    | Get config by ID               |
| `/api/v1/merkle/configs/activate`             | PUT    | Activate config                |
| `/api/v1/merkle/trees`                        | GET    | List trees                     |
| `/api/v1/merkle/trees/{id}`                   | GET    | Get tree                       |
| `/api/v1/merkle/proofs`                       | GET    | List proofs                    |
| `/api/v1/merkle/proofs/lookup`                | GET    | Lookup proof                   |
| `/api/v1/merkle/generate`                     | POST   | Generate tree                  |
| `/api/v1/merkle/jobs/{id}`                    | GET    | Poll generation job            |
| `/api/v1/merkle/jobs`                         | GET    | List jobs                      |
| `/api/v1/merkle/sync`                         | GET    | Determine onchain sync action  |
| `/api/v1/merkle/publish`                      | POST   | Publish active proof artifact  |
| `/api/v1/merkle/publish/jobs/{id}`            | GET    | Poll publish job               |
| `/api/v1/merkle/published/{chain_id}/{vault}` | GET    | Public published tree metadata |

## Registry

| Endpoint                                             | Method | Description                                 |
| ---------------------------------------------------- | ------ | ------------------------------------------- |
| `/api/v1/registry/yield-sources`                     | GET    | Browse yield sources for operator selection |
| `/api/v1/registry/oracles`                           | GET    | Browse oracles for operator selection       |
| `/api/v1/registry/hooks`                             | GET    | Browse hooks for merkle config authoring    |
| `/api/v1/registry/token-assets`                      | GET    | Browse token metadata                       |
| `/api/v1/registry/token-assets/{chain_id}/{address}` | GET    | Read token metadata                         |

Yield source registry entries include active/inactive state and can carry external provider metadata. Registry create, update, delete, and sync endpoints are registry-maintainer surfaces, not normal third-party operator flows.

## Yield Source Whitelist

| Endpoint                                           | Method | Description                            |
| -------------------------------------------------- | ------ | -------------------------------------- |
| `/api/v1/yield-sources/prepare-add`                | POST   | Prepare add transaction                |
| `/api/v1/yield-sources/prepare-remove`             | POST   | Prepare remove transaction             |
| `/api/v1/yield-sources/prepare-update-oracle`      | POST   | Prepare oracle update transaction      |
| `/api/v1/yield-sources/prepare-bulk-add`           | POST   | Prepare bulk add transaction           |
| `/api/v1/yield-sources/prepare-bulk-remove`        | POST   | Prepare bulk remove transaction        |
| `/api/v1/yield-sources/prepare-bulk-update-oracle` | POST   | Prepare bulk oracle update transaction |

## Users and Permissions

| Endpoint                                         | Method | Description                                  |
| ------------------------------------------------ | ------ | -------------------------------------------- |
| `/api/v1/users`                                  | GET    | List users for a vault                       |
| `/api/v1/users/secondary-manager/prepare`        | POST   | Prepare add-secondary-manager transaction    |
| `/api/v1/users/secondary-manager/remove/prepare` | POST   | Prepare remove-secondary-manager transaction |
| `/api/v1/users/view-only`                        | POST   | Add view-only user                           |
| `/api/v1/users/view-only/{wallet}`               | DELETE | Remove view-only user                        |
| `/api/v1/users/{wallet}/display-name`            | PATCH  | Update display name                          |

## Session Keys

| Endpoint                                                | Method | Description                       |
| ------------------------------------------------------- | ------ | --------------------------------- |
| `/api/v1/session-keys`                                  | GET    | List manager-visible session keys |
| `/api/v1/vaults/{chain_id}/{vault_address}/session-key` | GET    | Read vault session key            |
| `/api/v1/vaults/session-key/prepare`                    | POST   | Prepare session-key grant         |
| `/api/v1/vaults/session-key/revoke/prepare`             | POST   | Prepare session-key revoke        |

OMS owns additional readiness and rotation endpoints for strategy automation.

## Notification Channels

| Endpoint                                                                       | Method   | Description             |
| ------------------------------------------------------------------------------ | -------- | ----------------------- |
| `/api/v1/notification-channels`                                                | GET/POST | List or create channels |
| `/api/v1/vaults/{chain_id}/{vault_address}/notification-channels`              | GET      | List vault channels     |
| `/api/v1/vaults/{chain_id}/{vault_address}/notification-channels/{channel_id}` | POST     | Attach channel          |
| `/api/v1/vaults/{chain_id}/{vault_address}/notification-channels/{channel_id}` | DELETE   | Detach vault channel    |

Providers include Slack, webhook, and websocket channels.

## Pause and Services

| Endpoint                                                   | Method | Description                  |
| ---------------------------------------------------------- | ------ | ---------------------------- |
| `/api/v1/vaults/pause-status`                              | GET    | Batch pause status           |
| `/api/v1/vaults/emergency-pause/prepare`                   | POST   | Prepare onchain pause        |
| `/api/v1/vaults/emergency-unpause/prepare`                 | POST   | Prepare onchain unpause      |
| `/api/v1/vaults/{chain_id}/{vault}/services`               | GET    | List keeper services         |
| `/api/v1/vaults/{chain_id}/{vault}/services/{name}/pause`  | PUT    | Pause service                |
| `/api/v1/vaults/{chain_id}/{vault}/services/{name}/resume` | PUT    | Resume service               |
| `/api/v1/vaults/{chain_id}/{vault}/services/enabled`       | PUT    | Bulk enable/disable services |
| `/api/v1/vaults/{chain_id}/{vault}/services/{name}`        | PUT    | Update service config        |
| `/api/v1/services/bulk`                                    | PUT    | Bulk service update          |

## Analytics and Audit

Analytics endpoints live under:

```bash theme={null}
/api/v1/vaults/{chain_id}/{address}/analytics/*
```

Audit endpoints:

| Endpoint                  | Method | Description       |
| ------------------------- | ------ | ----------------- |
| `/api/v1/audit/logs`      | GET    | Query audit trail |
| `/api/v1/audit/logs/{id}` | GET    | Single audit row  |
| `/api/v1/audit/export`    | GET    | Export audit rows |