API Reference

Plugins

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

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.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

OK

no_authenticated_consumer: The gateway forwarded no API key identity

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.

Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.

Example Request
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/plugins'
Example Response
{  "data": [    {      "slug": "example",      "name": "Example: payment notes",      "version": "1.0.0",      "description": "Reference plugin: keeps a timeline of notes per payment intent, and adds one when it is paid.",      "author": "Cosmos Pay support",      "capabilities": [        "payment_intents:read"      ],      "egress": [],      "config": {        "label": {          "type": "string",          "description": "Optional prefix for every note, e.g. your team name.",          "required": false,          "secret": false        }      },      "queries": [        "get-notes"      ],      "commands": [        "add-note"      ],      "events": [        "PAYMENT_INTENT_SUCCEEDED"      ],      "installation": {        "id": "clx9z8a1b0000abcd1234efgh",        "pluginVersion": "1.0.0",        "grantedCapabilities": [          "payment_intents:read"        ],        "pendingCapabilities": [],        "config": {},        "secretsSet": [],        "createdAt": "2019-08-24T14:15:22Z",        "updatedAt": "2019-08-24T14:15:22Z"      }    }  ]}
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.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

slug*string

The plugin, e.g. example.

OK

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.

no_authenticated_consumer: The gateway forwarded no API key identity

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.

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.

Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.

Example Request
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/plugins/example'
Example Response
{  "slug": "example",  "name": "Example: payment notes",  "version": "1.0.0",  "description": "Reference plugin: keeps a timeline of notes per payment intent, and adds one when it is paid.",  "author": "Cosmos Pay support",  "capabilities": [    "payment_intents:read"  ],  "egress": [],  "config": {    "label": {      "type": "string",      "description": "Optional prefix for every note, e.g. your team name.",      "required": false,      "secret": false    }  },  "queries": [    "get-notes"  ],  "commands": [    "add-note"  ],  "events": [    "PAYMENT_INTENT_SUCCEEDED"  ],  "installation": {    "id": "clx9z8a1b0000abcd1234efgh",    "pluginVersion": "1.0.0",    "grantedCapabilities": [      "payment_intents:read"    ],    "pendingCapabilities": [],    "config": {},    "secretsSet": [],    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  }}
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.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

slug*string

The plugin, e.g. example.

OK

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.

no_authenticated_consumer: The gateway forwarded no API key identity

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.

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.

Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.

Example Request
curl -X DELETE 'https://api.cosmospay.lat/cosmos-api/v1/plugins/example/installation'
Example Response
{  "slug": "example",  "uninstalled": true}
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.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

slug*string

The plugin, e.g. example.

application/json
  1. body

Request to install a plugin, or re-consent to or reconfigure it: consent to exactly its capabilities, and its settings.

grantCapabilities*array<string>

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?

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.

OK

validation_failed: The body, query or headers failed validation

plugin_consent_mismatch: grantCapabilities must list exactly the capabilities the plugin declares

no_authenticated_consumer: The gateway forwarded no API key identity

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.

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.

Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.

Example Request
curl -X PUT 'https://api.cosmospay.lat/cosmos-api/v1/plugins/example/installation' \  -H 'Content-Type: application/json' \  -d '{  "grantCapabilities": [    "payment_intents:read"  ]}'
Example Response
{  "slug": "example",  "name": "Example: payment notes",  "version": "1.0.0",  "description": "Reference plugin: keeps a timeline of notes per payment intent, and adds one when it is paid.",  "author": "Cosmos Pay support",  "capabilities": [    "payment_intents:read"  ],  "egress": [],  "config": {    "label": {      "type": "string",      "description": "Optional prefix for every note, e.g. your team name.",      "required": false,      "secret": false    }  },  "queries": [    "get-notes"  ],  "commands": [    "add-note"  ],  "events": [    "PAYMENT_INTENT_SUCCEEDED"  ],  "installation": {    "id": "clx9z8a1b0000abcd1234efgh",    "pluginVersion": "1.0.0",    "grantedCapabilities": [      "payment_intents:read"    ],    "pendingCapabilities": [],    "config": {},    "secretsSet": [],    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  }}
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.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

slug*string

The plugin, e.g. example.

action*string

An action the plugin lists under queries / commands.

application/json
  1. body

Request to run one of a plugin's queries or commands.

input?

The action input, as the plugin documents it. Plain JSON, at most 64 KiB.

OK

validation_failed: The body, query or headers failed validation

plugin_rejected: The plugin refused the input; the message is the plugin’s own

no_authenticated_consumer: The gateway forwarded no API key identity

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.

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.

plugin_not_installed: The plugin is not installed for this key, or its consent is out of date

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.

Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.

plugin_failed: The plugin failed or timed out (the detail is logged, never returned)

plugin_failed: The plugin failed or timed out (the detail is logged, never returned)

Example Request
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/plugins/example/queries/get-notes' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "plugin": "example",  "action": "get-notes",  "output": {    "paymentIntentId": "clx9z8a1b0000abcd1234efgh",    "notes": [      {        "at": "2026-09-29T12:00:00.000Z",        "text": "Customer called",        "source": "tenant"      }    ]  }}
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.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

slug*string

The plugin, e.g. example.

action*string

An action the plugin lists under queries / commands.

application/json
  1. body

Request to run one of a plugin's queries or commands.

input?

The action input, as the plugin documents it. Plain JSON, at most 64 KiB.

OK

validation_failed: The body, query or headers failed validation

plugin_rejected: The plugin refused the input; the message is the plugin’s own

no_authenticated_consumer: The gateway forwarded no API key identity

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.

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.

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

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.

Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.

plugin_failed: The plugin failed or timed out (the detail is logged, never returned)

plugin_failed: The plugin failed or timed out (the detail is logged, never returned)

Example Request
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/plugins/example/commands/add-note' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "plugin": "example",  "action": "get-notes",  "output": {    "paymentIntentId": "clx9z8a1b0000abcd1234efgh",    "notes": [      {        "at": "2026-09-29T12:00:00.000Z",        "text": "Customer called",        "source": "tenant"      }    ]  }}