---
title: "Create a gateway trigger"
method: POST
path: "/trigger/gateway"
tags: ["Gateway Triggers"]
---

# Create a gateway trigger

`POST /trigger/gateway`

## Request

- Base URL: `https://api.quiva.ai`
- URL: `https://api.quiva.ai/trigger/gateway`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/quivaworks/apis/quiva-ai-gateway-6/docs/trigger/gateway/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a new gateway trigger for API endpoint management. A gateway trigger establishes an HTTP endpoint that can be accessed from outside the system and routes requests to appropriate handlers.

**Usage Notes:**
- The system automatically generates a unique topic for your gateway trigger
- Default timeout is 30 seconds (30000ms) if not specified
- Gateway mappings define the HTTP method, path, and access controls
- Setting `is_public: true` allows the endpoint to be accessed without authentication
- Rate limits can be configured per endpoint
- After creation, the gateway endpoint is immediately available for traffic
- The response includes the full subject identifier which may be needed for other operations

## Request body

- GatewayTriggerRequest
  - `name` string, required: Unique name identifier for the trigger. Used to construct the trigger's topic and subject.
  - `collection` string: Logical grouping the trigger belongs to. Used for organizing and filtering triggers.
  - `description` string: Human-readable description explaining the trigger's purpose and function.
  - `trigger_type` 'gateway', required: Must be 'gateway' for this endpoint. Determines the trigger's behavior and available properties.
  - `gateway_mapping` GatewayMapping, required
    - `error` string: Error message or identifier for failed mapping attempts or validation issues.
    - `gateway` string: Gateway identifier associated with this mapping. Links to the specific gateway infrastructure.
    - `is_public` boolean: Whether the endpoint is publicly accessible without authentication. Default is false.
    - `limit` GatewayLimit
      - `request` integer, required: Maximum number of requests allowed within the specified time window. Used for rate limiting.
      - `time` integer, required: Time window in milliseconds for rate limiting calculations. Typically 1000ms (1 second).
    - `method` 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD': HTTP method for the gateway endpoint. Determines how clients should interact with this endpoint.
    - `path` string: URL path for the gateway endpoint, including the leading slash. Forms the route that clients use to access this endpoint.
    - `subject` string: Subject identifier for the gateway mapping. Used internally for routing and message delivery.
    - `timeout` integer: Maximum time in milliseconds before the request times out. Default is 30000ms (30 seconds).
    - `traffic_distribution` object: Traffic distribution configuration mapping version numbers to percentage allocations. Used for A/B testing or canary deployments.

## Response `201`

Gateway trigger created successfully

- GatewayTriggerResponse
  - `body` object
    - `name` string: Unique name identifier for the trigger. Used to construct the trigger's topic and subject.
    - `collection` string: Logical grouping the trigger belongs to. Used for organizing and filtering triggers.
    - `gateway_mapping_subject` string: Full subject identifier assigned to the gateway mapping. Used for routing and message delivery.
    - `stream` string: Stream identifier where the trigger configuration is stored.
    - `subject` string: Full subject identifier for the trigger, following the pattern "ms.trigger.gateway.[name]".
    - `trigger_type` 'gateway': Type of trigger, always 'gateway' for gateway triggers.
    - `type` string: Specific type identifier providing additional classification information.
  - `status_code` integer: HTTP status code indicating the result of the operation.

## Other responses

- `400`: Invalid request. Occurs when required parameters are missing, validation fails, or the request format is incorrect.
- `401`: Unauthorized access. Occurs when authentication is missing or invalid, or when the authenticated user lacks permission.
- `500`: Internal server error. Occurs when an unexpected condition prevents the server from fulfilling the request.

---

[API](https://skmtc.dev/quivaworks/apis/quiva-ai-gateway-6.md) - [All operations](https://skmtc.dev/quivaworks/apis/quiva-ai-gateway-6/llms.txt) - [OpenAPI document](https://skmtc.dev/quivaworks/apis/quiva-ai-gateway-6/revisions/a9f443efdc5d?raw)