Skip to main content

Collections

A Collection is the top-level grouping in Zerq. It represents a backend service or API product and contains all the individual endpoint definitions (Proxies) for that service.

Collection guides​

What is a Collection?​

Think of a Collection as an API product:

  • "Payments API" → proxies to https://payments.internal
  • "User Service" → proxies to https://users.internal
  • "Analytics API" → proxies to https://analytics.internal

Every request to the Zerq gateway is matched first to a Collection (by base path), then to a specific Proxy (by endpoint path and method).

Creating a Collection​

  1. Go to Collections in the sidebar
  2. Click New Collection
  3. Fill in the fields:
FieldDescription
NameDisplay name (e.g., "Payments API")
DescriptionOptional description visible in the Developer Portal
Base PathThe URL prefix for all endpoints in this collection (e.g., /payments)
Target EndpointThe backend URL requests are forwarded to (e.g., https://payments.internal)
CredentialsOptional — select stored credentials for authenticating with the backend
Custom HeadersOptional — headers added to every request forwarded to the backend
  1. Click Create

The collection is created in draft status. Add proxies before publishing.

Base path routing​

The base path is how Zerq knows which collection to route a request to. It must be unique across all collections.

Example: request GET /payments/transactions first matches base path /payments, then routes into the Payments API collection.

Custom headers​

You can add headers that Zerq appends to every backend request in this collection. This is useful for:

  • Passing a secret API key to your backend
  • Adding a service identifier header
  • Including a correlation ID

Headers support two value types:

TypeExampleDescription
Staticmy-secret-valueFixed string value
Environment variable$ENV_VAR_NAMEReferences a gateway environment variable at runtime

Using environment variables keeps secrets out of the database and UI.

Credentials​

If your backend requires authentication, attach a Credential to the collection. Zerq will automatically include the credential in every forwarded request.

For example, if your backend requires a Bearer token, create an API Key credential and attach it — Zerq handles the Authorization header automatically.

→ See Credentials for all supported types.

Importing from OpenAPI​

If you already have an OpenAPI specification, you can import it to create a collection and all its proxies in one step:

  1. Click Import from OpenAPI on the Collections page
  2. Upload your .json or .yaml OpenAPI 3.0/3.1 file
  3. Zerq parses the spec and creates:
    • A collection with the API title as the name
    • A proxy for every endpoint, with paths, methods, parameters, and schemas pre-filled

→ See Import from OpenAPI for full details.

Bulk import / export​

You can export one or more collections as JSON and re-import them:

  • Export: Select collections → Export Selected → downloads a JSON file
  • Import: Click Import → upload a JSON file → choose to replace or merge existing

This is useful for copying configurations between environments (dev → staging → production).

→ See Import & Export

Editing a Collection​

Click the edit icon on any collection to update its name, description, target endpoint, base path, credentials, or headers.

caution

Changing the base path of a live collection will break existing clients immediately. Coordinate base path changes carefully.

Deleting a Collection​

Deleting a collection removes it and all its proxies. This is irreversible. Existing clients assigned to this collection will lose access.

Collection status​

Collections and their proxies each have a draft/published status. Only published collections with published proxies are:

  • Visible in the Developer Portal
  • Accessible through the gateway

→ See Draft & Publish

Duplicating a Collection​

Click the duplicate icon to clone a collection with all its proxies. The clone is created in draft status with a (copy) suffix. Useful for versioning or creating variations.

Downloading OpenAPI spec​

Every collection can generate a standard OpenAPI 3.1 specification from its proxy definitions. Click Download OpenAPI from the collection detail page.