# Plugins (https://dev.cosmospay.lat/docs/api/plugins/)

> Extensions served under a slug: list them, install one for your account, and call its queries and commands.

Base URL: `https://api.cosmospay.lat/cosmos-api`

## List the plugins this deployment serves, with this key’s installations

`GET /v1/plugins`

Each plugin with its manifest (`capabilities`, `egress`, `config` settings, `queries`, `commands`, `events`) and `installation`: this consumer's installation of it, or null. An installation lists `pendingCapabilities` when the plugin was updated to ask for more than was granted, and its actions are refused until it is installed again. Answers `{ data }`, not paged.

Requires the `plugins:read` scope.

**Responses**

- `200` (`PluginListEntity`): OK
  - `data` (PluginEntity[], required): Each plugin, with the calling API key's installation of it.
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `500`: InternalError (see Shared responses)

## Describe a plugin: capabilities, egress, settings, actions

`GET /v1/plugins/{slug}`

One plugin's manifest and this consumer's `installation` of it (null when not installed). Read it before installing: `PUT /v1/plugins/{slug}/installation` must grant exactly the `capabilities` listed here. Secret settings are never returned; `installation.secretsSet` names the ones that hold a value.

Requires the `plugins:read` scope.

**Path parameters**

- `slug` (string, required): The plugin, e.g. `example`.

**Responses**

- `200` (`PluginEntity`): OK
  - `slug` (string, required): The plugin id: URL-safe, unique and permanent, as `/v1/plugins/{slug}` takes it.
  - `name` (string, required): The plugin's display name.
  - `version` (string, required): The plugin's current version (semver).
  - `description` (string, required): What the plugin does, as its manifest describes it.
  - `author` (string, required): Who maintains the plugin: a person, a company or a repository URL.
  - `capabilities` (string[], required): What the plugin may do with the core. Installing grants exactly these.
  - `egress` (string[], required): The only hosts the plugin can reach over HTTPS.
  - `config` (object, required): The settings the plugin declares, by setting name.
  - `queries` (string[], required): Read-only actions, run with `POST /v1/plugins/{slug}/queries/{action}`.
  - `commands` (string[], required): Actions that write, run with `POST /v1/plugins/{slug}/commands/{action}`.
  - `events` (string[], required): The core events the plugin handles.
  - `installation` (PluginInstallationEntity, required): The calling API key's installation of the plugin; null when it is not installed.
- `400`: ValidationFailed (see Shared responses)
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `404`: NotFound (see Shared responses)
- `500`: InternalError (see Shared responses)

## Install a plugin (or re-consent / reconfigure it), granting its capabilities

`PUT /v1/plugins/{slug}/installation`

Installing is consent: `grantCapabilities` must list exactly the capabilities the plugin declares, no more and no fewer (`400 plugin_consent_mismatch`). `config` is checked against the plugin's settings; secret settings are stored sealed and kept when not sent again. Call it again after an update leaves `pendingCapabilities`; it answers the plugin with its new `installation`.

Requires the `plugins:write` scope.

**Path parameters**

- `slug` (string, required): The plugin, e.g. `example`.

**Request body** (`application/json`, required): `InstallPluginDto`

- `grantCapabilities` (string[], required): Consent: exactly the capabilities the plugin declares (see GET /v1/plugins/{slug}). A partial or extra list is refused, so installing means having read it.
- `config` (object, optional): Settings, as the plugin declares them. Secret fields are sealed at rest and never returned; leave one out on a re-install to keep the value already stored.

**Responses**

- `200` (`PluginEntity`): OK
- `400` (`ApiErrorBodyEntity`): `validation_failed`: The body, query or headers failed validation `plugin_consent_mismatch`: grantCapabilities must list exactly the capabilities the plugin declares
  - `statusCode` (number, required): Always the HTTP status of the response itself.
  - `code` (string, required): Stable machine-readable code. Branch on this, never on the message: messages are human-facing and may be reworded; codes are never renamed once published. Each response documents the subset it can return. One of: `insufficient_scope`, `no_authenticated_consumer`, `gateway_required`, `admin_console_only`, `not_found`, `validation_failed`, `payload_too_large`, `idempotency_conflict`, `operation_in_flight`, `invalid_state_transition`, `slippage_exceeded`, `insufficient_balance`, `no_path_found`, `trustline_missing`, `invalid_amount`, `invalid_memo`, `transaction_rejected`, `transaction_already_settled`, `recipient_not_registered`, `payment_transfer_mismatch`, `fee_transfer_mismatch`, `merchant_fee_transfer_mismatch`, `payer_mismatch`, `transaction_not_found`, `expired`, `network_unsupported`, `asset_unsupported`, `merchant_fee_unsupported`, `provider_error`, `provider_unavailable`, `quote_not_found`, `quote_expired`, `kyc_state_invalid`, `kyc_review_required`, `account_disabled`, `payload_expired`, `rate_limited`, `customer_wallet_taken`, `alias_taken`, `alias_name_invalid`, `alias_challenge_invalid`, `alias_signature_invalid`, `alias_recovery_invalid`, `alias_address_conflict`, `wallet_handshake_invalid`, `wallet_verifier_invalid`, `wallet_login_code_invalid`, `wallet_login_code_cooldown`, `wallet_session_invalid`, `wallet_signature_invalid`, `wallet_backup_invalid`, `wallet_backup_limit`, `wallet_account_mismatch`, `wallet_provider_unavailable`, `wallet_return_url_not_allowed`, `wallet_recovery_setup_refused`, `easy_recovery_not_found`, `easy_recovery_already_offered`, `easy_recovery_not_offered`, `easy_recovery_code_invalid`, `easy_recovery_burned`, `plugin_not_installed`, `plugin_consent_mismatch`, `plugin_rejected`, `plugin_quota_exceeded`, `plugin_failed`, `protected_payment_buyer_mismatch`, `protected_payment_signature_invalid`, `misconfigured`, `internal_error`.
  - `error` (string, required): The HTTP reason phrase for `statusCode`.
  - `message` (string | string[], required): Human-readable detail. An array when class-validator rejected the body.
  - `details` (object, optional): Machine-readable facts about this failure, present only on the codes whose example shows it: `easy_recovery_code_invalid` carries `{ "attemptsLeft": 4 }`. Absent everywhere else.
  - `path` (string, required): The path of the request that failed.
  - `timestamp` (string, required): When the envelope was produced, ISO 8601.
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `404`: NotFound (see Shared responses)
- `500`: InternalError (see Shared responses)

## Uninstall a plugin and delete every record it kept for this key

`DELETE /v1/plugins/{slug}/installation`

Deletes this consumer's installation and, with it, everything the plugin stored for the consumer. It works even when the deployment no longer serves the plugin; a plugin that is not installed is a 404. Answers `{ slug, uninstalled: true }`.

Requires the `plugins:write` scope.

**Path parameters**

- `slug` (string, required): The plugin, e.g. `example`.

**Responses**

- `200` (`PluginUninstalledEntity`): OK
  - `slug` (string, required): The plugin uninstalled.
  - `uninstalled` (boolean, required): Always true.
- `400`: ValidationFailed (see Shared responses)
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `404`: NotFound (see Shared responses)
- `500`: InternalError (see Shared responses)

## Run a read-only plugin action

`POST /v1/plugins/{slug}/queries/{action}`

Runs one of the plugin's `queries` with `input` (JSON, at most 64 KiB) and answers its `output`; a query cannot write the plugin storage, customers or products. The plugin must be installed with every capability it now asks for (`409 plugin_not_installed`). A refusal by the plugin is `400 plugin_rejected`, a failure `502 plugin_failed`, and a run over 10 seconds `504 plugin_failed`.

Requires the `plugins:read` scope.

**Path parameters**

- `slug` (string, required): The plugin, e.g. `example`.
- `action` (string, required): An action the plugin lists under `queries` / `commands`.

**Request body** (`application/json`, required): `InvokePluginActionDto`

- `input` (object, optional): The action input, as the plugin documents it. Plain JSON, at most 64 KiB.

**Responses**

- `200` (`PluginActionResultEntity`): OK
  - `plugin` (string, required): The slug of the plugin that ran the action.
  - `action` (string, required): The action that ran.
  - `output` (object, required): Whatever the plugin returned, as JSON.
- `400` (`ApiErrorBodyEntity`): `validation_failed`: The body, query or headers failed validation `plugin_rejected`: The plugin refused the input; the message is the plugin’s own
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `404`: NotFound (see Shared responses)
- `409` (`ApiErrorBodyEntity`): `plugin_not_installed`: The plugin is not installed for this key, or its consent is out of date
- `429`: RateLimited (see Shared responses)
- `500`: InternalError (see Shared responses)
- `502` (`ApiErrorBodyEntity`): `plugin_failed`: The plugin failed or timed out (the detail is logged, never returned)
- `504` (`ApiErrorBodyEntity`): `plugin_failed`: The plugin failed or timed out (the detail is logged, never returned)

## Run a plugin action that writes

`POST /v1/plugins/{slug}/commands/{action}`

Runs one of the plugin's `commands` with `input` (JSON, at most 64 KiB) and answers its `output`; a command may write its own storage and, as far as the granted capabilities allow, this consumer's customers and products. It needs an installation with every capability the plugin now asks for (`409 plugin_not_installed`), and storage is capped per installation (`409 plugin_quota_exceeded`). A refusal by the plugin is `400 plugin_rejected`, a failure `502 plugin_failed`, and a run over 10 seconds `504 plugin_failed`.

Requires the `plugins:write` scope.

**Path parameters**

- `slug` (string, required): The plugin, e.g. `example`.
- `action` (string, required): An action the plugin lists under `queries` / `commands`.

**Request body** (`application/json`, required): `InvokePluginActionDto`

- `input` (object, optional): The action input, as the plugin documents it. Plain JSON, at most 64 KiB.

**Responses**

- `200` (`PluginActionResultEntity`): OK
- `400` (`ApiErrorBodyEntity`): `validation_failed`: The body, query or headers failed validation `plugin_rejected`: The plugin refused the input; the message is the plugin’s own
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `404`: NotFound (see Shared responses)
- `409` (`ApiErrorBodyEntity`): `plugin_not_installed`: The plugin is not installed for this key, or its consent is out of date `plugin_quota_exceeded`: The installation holds as many records as it may
- `429`: RateLimited (see Shared responses)
- `500`: InternalError (see Shared responses)
- `502` (`ApiErrorBodyEntity`): `plugin_failed`: The plugin failed or timed out (the detail is logged, never returned)
- `504` (`ApiErrorBodyEntity`): `plugin_failed`: The plugin failed or timed out (the detail is logged, never returned)

## Shared responses

- **Unauthorized** (`ApiErrorBodyEntity`): `no_authenticated_consumer`: The gateway forwarded no API key identity
- **Forbidden** (`ApiErrorBodyEntity`): `insufficient_scope`: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked `x-cosmos-public-key`, with a message saying so; more scopes will not help, the key is the wrong one. `gateway_required`: the request did not arrive through APISIX.
- **InternalError** (`ApiErrorBodyEntity`): Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
- **ValidationFailed** (`ApiErrorBodyEntity`): The body, query or path failed validation. `message` is an array of the individual failures. Routes that reject a *valid* request for a reason of their own (an amount, a memo, a state) document the code for it on their own 400.
- **NotFound** (`ApiErrorBodyEntity`): No such resource, or it exists and belongs to another consumer. The two are deliberately the same answer: "exists but not yours" is an ownership oracle.
- **RateLimited** (`ApiErrorBodyEntity`): The budget in `x-cosmos-rate-limit` is spent for this caller. Honour `Retry-After`. The `ratelimit-*` triple rides along on successful responses too, so a client can pace itself instead of being refused. If the counter store itself is unreachable the guard fails closed and answers `503 provider_unavailable`.
