API resources
This page is a short map of what the REST API covers. Each resource matches a page of the web UI and follows the same rules. For every field and answer, see the REST API reference. How requests, errors and lists work is in REST API basics.
All paths are below /api/v1. {id} is a number, except for a message, whose ID is a UUID.
Parties and routes
| Path | Methods | What |
|---|---|---|
/organizations, /organizations/{id} | GET, POST, PUT, DELETE | Your organizations: name and display_name. |
/partners, /partners/{id} | GET, POST, PUT, DELETE | Your partners, with the same fields. |
/routes, /routes/{id} | GET, POST, PUT, DELETE | Routes: source_plugin, from, to, target_plugin. from and to may be * (Any). |
A name is 1 to 64 lower case letters, digits, _ and -. A route applies to the next message, with no restart. See routes.
Certificates
| Path | Methods | What |
|---|---|---|
/certificates, /certificates/{id} | GET, POST, PUT, DELETE | Upload, read, describe and delete certificates. |
/certificates/import | POST | Import chosen certificates from an upload with several. |
/certificates/expiring | GET | Expired and expiring certificates, soonest first. days sets the window (default 30). |
/certificates/{id}/download | GET | The certificate as PEM. Never the private key. |
Upload with multipart/form-data and an X-Requested-With header. The fields are certificate (required), private_key, password (for PKCS#12) and description:
curl -X POST -H "Authorization: Bearer $ACCESS_TOKEN" -H "X-Requested-With: XMLHttpRequest" \
-F "description=MyCompany signing" -F "[email protected]" -F "[email protected]" \
http://localhost:8080/api/v1/certificates- One certificate with a
descriptionis stored at once:201. - Anything else stores nothing yet. The answer is
200with what the upload holds and animport_token, valid for ten minutes. Send it to/certificates/importwith the certificates you want. - A certificate that is already stored is refused with
409 CERTIFICATE_EXISTS. PUTchanges only thedescription.- A certificate that a profile still uses cannot be deleted:
409 CERTIFICATE_IN_USE.details.userslists the profiles. Change them first.
Filters of the list: q (text in the description, names, serial number or the start of the fingerprint), status (valid, expiring, expired) and key (present, absent). See certificates.
AS2 profiles
| Path | Methods | What |
|---|---|---|
/as2/local-profiles, /as2/local-profiles/{id} | GET, POST, PUT, DELETE | An organization’s AS2 profile. {id} is the organization’s ID. |
/as2/remote-profiles, /as2/remote-profiles/{id} | GET, POST, PUT, DELETE | A partner’s AS2 profile. {id} is the partner’s ID. |
/as2/remote-profiles/{id}/check-connection | POST | Checks that a sender can reach the partner’s endpoint. |
/as2/remote-profiles/{id}/test-message | POST | Sends a test message to the partner. |
A new partner profile starts with the same secure defaults as the form. The fields are explained in partner AS2 profile and organization AS2 profile. The two tests are described in testing a partner. A connection check answers 503 SENDER_NOT_RUNNING when the AS2 sender is not running.
Plugin instances
| Path | Methods | What |
|---|---|---|
/plugins/configs?type=<type> | POST | Create an instance of a type. |
/plugins/configs/{type}/{name} | GET, PUT, DELETE | One instance. |
/plugins/configs/notification-webhook/{name}/test | POST | Send a test notification. |
/services | GET | Every running instance with its status and possible actions. |
/services/{type}/{name}/{action} | POST | start, stop or restart an instance. |
The types are as2-receiver, as2-sender, file-poller, file-writer, http-poster and notification-webhook. A missing type is 400 MISSING_TYPE, an unknown one 400 INVALID_TYPE. An instance name is unique across all types.
A changed instance is read when it starts, so restart it afterwards. There is no list of configurations; GET /services and GET /stats name every instance.
On /services, an action on an instance that is busy or in the wrong state is a 409. The API server itself cannot be stopped: 403. A failed start is a 500 with the reason.
Messages
| Path | Methods | What |
|---|---|---|
/messages | GET | List messages. |
/messages | POST | Send a message by hand (multipart/form-data). |
/messages/{id} | GET | One message, with its deliveries, history and payload stages. |
/messages/{id}/payload?stage= | GET | Download one stage of the message’s content. |
/messages/{id}/redispatch | POST | Match the routes again. |
/messages/{id}/deliveries/{delivery_id}/redeliver | POST | Send one delivery again. |
/events | GET | A live stream (Server-Sent Events) of message history lines. |
/stats | GET | The dashboard’s counters and plugin status. |
Filters of the list: status, from, to (party names) and since (an RFC 3339 time).
Sending a message by hand takes from, to, file and an optional target. One party must be an organization and the other a partner. The file holds at most 64 MiB:
curl -X POST -H "Authorization: Bearer $ACCESS_TOKEN" -H "X-Requested-With: XMLHttpRequest" \
-F "from=local" -F "to=acme" -F "[email protected]" \
http://localhost:8080/api/v1/messagesRedispatch and redeliver take no body but still send Content-Type: application/json. They answer with the message. When the action does not apply, the answer is 409 NOT_REDISPATCHABLE or 409 NOT_REDELIVERABLE. See messages and message actions.
curl -X POST -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
http://localhost:8080/api/v1/messages/$MESSAGE_ID/redispatchThe event stream sends only new lines. After a reconnect with Last-Event-ID, it first sends what you missed. If you missed too much, you get one reload event: list the messages again and reconnect. A reverse proxy must not buffer this stream.
curl -N -H "Authorization: Bearer $ACCESS_TOKEN" http://localhost:8080/api/v1/eventsAccess
| Path | Methods | What |
|---|---|---|
/service-accounts, /service-accounts/{id} | GET, POST, PUT, DELETE | Service accounts. Name and kind cannot change. |
/api-tokens, /api-tokens/{id} | GET, POST, DELETE | API tokens. DELETE revokes a token. |
/oidc-providers, /oidc-providers/{id} | GET, POST, PUT, DELETE | Identity providers. |
POST /api-tokens takes service_account, label and expires_in_days (1 to 365, default 90). Its answer is the only one that ever holds the token, under token. Copy it then. See service accounts and identity providers.
Users are managed in the web UI and with microb2b users, not with the API. See users.
System
| Path | Methods | What |
|---|---|---|
/settings | GET, PUT | The global settings: payload storage, delivery and identification. |
/settings/storage/test | POST | Tests the saved payload storage. |
/notifications | GET | The notification log. |
/audit | GET | The audit log, newest first. |
/audit/verify | POST | Checks the audit log’s hash chain. |
/openapi.yaml | GET | The OpenAPI document. |
Saved storage settings take effect after a restart. GET /settings says so with restart_needed. See settings.
Filters of the notification log: severity, code, instance, outcome, from, to and include_tests. See notifications.
Filters of the audit log: kind, action, actor, record_id, record_name, from and to. Without an audit key on the server, verifying a log with hashed events is 409 AUDIT_KEY_REQUIRED. See audit log.