Skip to main content

1Gateway API - Swagger

Overview​

1Gateway exposes a set of REST APIs that allow programmatic interaction with the platform. These APIs are primarily intended for integration, automation, and advanced operational use cases.

All available APIs are formally documented using Swagger (OpenAPI), which serves as the authoritative and up-to-date reference.

Accessing the API Documentation (Swagger)​

Swagger UI​

1Gateway provides an interactive Swagger UI that documents all available API endpoints, request models, and responses.

Access URL: http(s)://<1gateway-host>/swagger-ui/index.html

The Swagger UI allows users to:

  • Browse available API endpoints
  • View request and response schemas
  • Inspect required parameters
  • Execute API calls interactively using the Try it out feature

Accessing the 1Gateway API​

Base URL​

  • All APIs are exposed on the same host as the 1Gateway application.
  • API paths include versioned prefixes (for example /api/v3 or /api/v4).

Authentication​

Authentication requirements are defined per API and are documented directly in Swagger. To call secured APIs via Swagger UI:

  1. Open Swagger UI (http(s)://<1gateway-host>/swagger-ui/index.html)
  2. Click Authorize
  3. Provide the 1Gateway username and password
  4. Execute API calls using Try it out
info

The exact authentication mechanism must always be verified in Swagger.

API Groups and Capabilities​

This section describes what you can do with the APIs. For exact endpoint paths, parameters, and payloads, refer to Swagger.

Message API​

The Message API allows external systems to send and retrieve messages from 1Gateway and requeuing them.

  • Sending messages to webhook plugins
  • Injecting messages into queues
  • Requeuing or retrying failed messages
  • Republishing messages from MongoDB collections
  • Retrieving messages from queues (single or bulk)

The Message API supports multiple API versions (v3 and v4). Where available, newer versions should be preferred.

System API​

The System API provides operational and maintenance capabilities.

  • Triggering system backups
  • Downloading backups
  • Installing or downloading support-related artifacts

These APIs are generally intended for administrative and operational use.

Mongo API​

The Mongo API provides controlled access to MongoDB collections managed by 1Gateway.

  • Retrieving documents from a collection
  • Querying documents using filters

These APIs are primarily intended to access user data, diagnostics, inspection, and advanced operational scenarios.

Schema API​

The Schema API is used to manage and validate message schemas.

  • Validating messages against configured schemas
  • Retrieving available schemas

Plugin API​

The Plugin API allows programmatic management and inspection of plugins.

  • Activating or deactivating plugins
  • Purging plugin queues
  • Retrieving plugin configuration
  • Downloading plugin configurations and mappers
  • Listing configured or deleted plugins
  • Inspecting plugin status and metadata

These APIs are used for automating configurations, monitoring, and advanced administration.

Health and Monitoring APIs​

Health and monitoring APIs provide insight into the runtime state of the system.

  • Checking plugin status
  • Monitoring queue states
  • Retrieving version and license information

These APIs are often used by monitoring tools and operational dashboards.

Encryption API​

The Encryption API provides cryptographic utilities and keystore management functions.

  • Encrypting sensitive values for configuration of application.properties.
  • Managing certificates and keypairs
  • Retrieving public keys or certificates
  • Listing keystore aliases

These APIs support secure configuration and certificate lifecycle management.

Audit API​

The Audit API provides access to audit log entries generated by 1Gateway.

  • Filtering and retrieving audit events
  • Compliance and traceability reporting
  • Operational troubleshooting

Mapper API​

The Mapper API allows retrieval of configured mappers.

  • Inspecting mapper configurations
  • Supporting troubleshooting and diagnostics

Usage Guidance​

  • Always consult Swagger for exact request and response formats.
  • Prefer API version /v4 when available.
  • Use Swagger’s Try it out feature for testing.