Interfaces

An interface is an endpoint. Add any number of them to a config under interfaces: — each key is the interface name (and default route). When an interface is triggered it runs its ordered list of actions.

interfaces:
  prod/user-login:
    summary: Log a user in
    description: Verify credentials and return a token
    tags: [auth]
    output: http
    method: POST
    actions:
      - name: CheckInput
      - name: VerifyUser
      - name: VerifyPassword

An interface can also run on a schedule, be exposed as an MCP tool, and carry a network policy. All fields follow.

Interface

Field	Type	Description
capture	CaptureSetting (nullable)	How much of this interface's runs to record for execution history. Absent means off, which is also the fleet-wide default: capture is opt-in per interface, then bounded again…
defaults	ActionDefaults (nullable)	Defaults handed to every action in this interface (see [ActionDefaults]). An action that sets the field itself always wins.
summary	string (nullable)
description	string (nullable)
log	CustomLog (nullable)
tags	Array<string> (nullable)
templates	Map<string, string> (nullable)
mqtt	string (nullable)	MQTT trigger name. When set, this interface is triggered by an MQTT PUBLISH to the topic <environment>/<interface_name>/<this value> (carried over MQTT-over-WebSocket at…
ws	string (nullable)	WebSocket marker. When set (to any value), this interface is reachable over WebSocket at /ws/<org>/<environment>/<interface_name>; each inbound JSON text frame runs the…
subscribe_authorizer	string (nullable)	Realtime-channel access control. The name of an interface run to authorize a socket's ap_subscribe to a channel: it runs with { "channel": "<name>" } as a|body and the…
public	boolean (nullable)	Public realtime opt-in. When true, this WebSocket interface accepts END-USER connections with NO credential at all — no org API key and no JWT — for non-sensitive public…
schedule	Schedule (nullable)
silence	boolean (nullable)
method	string (nullable)
route	string (nullable)
show_error_detail	boolean (nullable)
actions	Array<Action> (nullable)
url	string (nullable)
conn_string	string (nullable)
query	string (nullable)
params	Map<string, Param> (nullable)
tests	Array<Test> (nullable)
assert	Assert (nullable)
output	InterfaceOutput (nullable)
response	InterfaceResponse (nullable)
disable_fastpath	boolean (nullable)	Opt this interface out of the compiled fast path (AP_FASTPATH), forcing every request through the interpreter. The fast path is byte-identical, so this never changes output —…
accepts	InterfaceContract (nullable)	What this interface ACCEPTS: the shape of the payload its trigger delivers, and an example of it. Transport-neutral on purpose. An interface is not always an HTTP endpoint — it…
produces	InterfaceContract (nullable)	What this interface PRODUCES: the shape of its result, and an example of it. For an HTTP interface that is the response body; for a schedule it is what the run yielded; for…
request_example	any	Example request body shown in generated API documentation. DEPRECATED: use request: { example: … }. Still read so existing configs keep working; request.example wins when…
response_example	any	Example successful response body shown in generated API documentation. DEPRECATED: use response: { example: … }. Still read so existing configs keep working;…
notes	string (nullable)	Additional free-form documentation notes shown under the endpoint description.
network	NetworkPolicy (nullable)	Network access-control policy for this interface (IP/geo/ASN/rate-limit). Inherits and tightens the config-wide network policy unless inherit: false. Evaluated before any…
mcp	McpTool (nullable)	Expose this interface as an MCP tool (opt-in). When set with enabled: true, the interface is listed by the MCP server (tools/list) and callable via tools/call, reusing…

InterfaceResponse

Field	Type	Description
http_code_on_error	number (nullable)
http_code_inherit_error	Array<string> (nullable)
headers	object (nullable)
custom_body	string (nullable)
http_code_fallback	number (nullable)
http_code_fallback_strategy	ErrorFallbackStrategy (nullable)
logs	Array<InterfaceLog> (nullable)

InterfaceLog

Field	Type	Description
on	InterfaceLogOn	Required.
database	string (nullable)

InterfaceLogOn

Type: string — one of: error, success, any

InterfaceOutput

Type: string — one of: http, cli, none

ErrorFallbackStrategy

Type: string — one of: last_action, last_action_with_error, any_action

McpTool

Opt-in MCP tool exposure for an interface. See [Interface::mcp].

The MCP server auto-generates the tool's inputSchema from the interface's assert tests (the same schema that powers the OpenAPI docs), so no separate schema needs to be authored here.

Field	Type	Description
enabled	boolean	Expose this interface as an MCP tool. Default false. Default: false.
tool_name	string (nullable)	Override the tool name shown to MCP clients. Defaults to the interface name.
description	string (nullable)	Override the tool description. Defaults to the interface summary/description.
list_authorizer	string (nullable)	Optional per-tool tools/list authorizer: the name of an interface in this config that is RUN (with the forwarded request headers) when a client lists tools. The tool appears…
server	string (nullable)	Which declared MCP server this tool belongs to (see [IntegrationConfig::mcp_servers]). Omitted = the default server, which is what every pre-existing config gets. The id may…

McpServer

A named MCP server: an identity, plus the tools that join it by id.

Declared under [IntegrationConfig::mcp_servers] and joined by [McpTool::server]. Declaring and contributing are deliberately separate. Air Pipe's own management MCP is assembled from many configs but is one server with one identity, so repeating the identity in each contributing config would leave no single source of truth; conversely one org may publish several distinct MCP offerings from different subsets of its configs.

title and instructions exist because MCP registries (mcp.so, Glama, Smithery, PulseMCP) read a remote server's listing metadata straight off the initialize response — there is no separate place to write a description. Without them a listing renders as a bare name and a wall of tool descriptions.

Field	Type	Description
title	string (nullable)	Display name shown to MCP clients and registries (serverInfo.title). Absent = clients fall back to the protocol-level server name.
instructions	string (nullable)	Server-level description, emitted as the initialize result's instructions. This is the field MCP registries surface as the listing description.
default	boolean	Serve this identity on the bare /<org>/<env>/mcp route, i.e. adopt the tools that name no server. At most one per org+environment; ties resolve deterministically by config name. Default: false.

Param

Parameter definition for interface-level URL parameters with optional validation and default values.

Example

interfaces:
  getUser:
    method: GET
    params:
      id:
        value: a|params::id|
        error_message: "User ID is required"
        validate:
          is_not_empty: true
          regex: "^[0-9]+$"
      page:
        value: a|params::page|
        default_value: "1"

Field	Type	Description
value	string (nullable)	Source value expression (e.g., a|params::id|).
default_value	string (nullable)	Default value if the parameter is not provided.
error_message	string (nullable)	Custom error message when validation fails.
validate	Test (nullable)	Validation test to run against the parameter value. Example ↓

Field examples

validate

Validation test to run against the parameter value.

Example

validate:
  is_not_empty: true
  is_less_than: 100
  regex: "^[a-zA-Z0-9]+$"

Schedule

AirPipe schedule configuration. Defines when and how an interface should be executed automatically via the scheduler.

Example

myScheduledEndpoint:        # Interface name
  method: POST
  actions:
    - name: MyAction
      http:
        url: https://api.example.com/trigger

  schedule:                 # Schedule configuration (enables auto-execution)
    cron: "0 9 * * *"       # Required: Cron expression (5 fields: minute-hour-day-month-weekday)
    enabled: true           # Optional: Enable/disable the schedule (default: false)

    # Retry configuration
    max_attempts: 3         # Optional: Max retry attempts on failure (default: 1)
    retry_backoff_seconds: 60    # Optional: Initial backoff in seconds (default: 60)
    retry_backoff_multiplier: 2.0 # Optional: Backoff multiplier for exponential backoff (default: 2.0)
    max_backoff_seconds: 3600    # Optional: Maximum backoff cap in seconds (default: 3600)

Field	Type	Description
cron	string	Required. Cron expression in 5-field format (minute hour day month weekday)
enabled	boolean	Required. Whether the schedule is enabled
max_attempts	number (nullable)	Max retry attempts on failure Default: 1.
retry_backoff_seconds	number (nullable)	Initial retry backoff in seconds Default: 60.
retry_backoff_multiplier	number (nullable)	Exponential backoff multiplier Default: 2.
max_backoff_seconds	number (nullable)	Maximum retry backoff cap in seconds Default: 3600.
timezone	string (nullable)	IANA timezone for cron interpretation (e.g. 'America/New_York'); defaults to UTC Default: null.

CaptureSetting

capture: on an interface — either a mode, or a mode that switches itself off.

The window form is what keeps the fleet's resting state at "capture off" no matter how many people click the button. Permanent capture stays a deliberate, tier-gated choice rather than the easy path.

capture: errors                 # plain mode

capture:                        # self-expiring window
  mode: all
  for_minutes: 30
  for_runs: 500                 # whichever comes first

One of:

• CaptureMode
• CaptureWindow

CaptureMode

How much of a run to record.

One of:

• string — Record nothing. The fleet-wide default.
• string — Record failed runs only. The mode worth defaulting to when capture is wanted at all: volume then tracks the ERROR RATE rather than throughput, so a healthy system at a million…
• string — Record successful runs too. The expensive mode, and the one tiers actually buy.

CaptureWindow

Field	Type	Description
mode	CaptureMode	Required.
for_minutes	number (nullable)	Switch off this many minutes after the window opens.
for_runs	number (nullable)	Switch off after this many runs.