OpenAPI extensions

Gatelion turns your API's OpenAPI description into tools: each operation becomes one tool that agents can call and your policy can govern. This page describes what Gatelion reads from the document and the optional x-gatelion-* extensions that tell it more. Other OpenAPI tools ignore these extensions, so you can keep them in your normal API description.

You import a description from Tools & agents → Connections with Import API description, choosing An OpenAPI file or Paste OpenAPI. See Connect a system.

If your API has no OpenAPI description, choose Describe the operations instead, and fill in the form by hand or start it with Import from Postman or Paste a curl command. Gatelion turns what you describe into an OpenAPI 3.1 document and imports it the same way, so the rules on this page apply to described operations too. The form sets each operation's name, risk, field kinds and response fields. For nested request bodies, or for the other extensions on this page, write an OpenAPI description instead.

Accepted documents#

The document's servers are ignored: requests always go to the connection's own address.

Before anything is saved, Preview lists each operation, whether it can become a tool, and why not if it can't, with any warnings. Re-importing a changed description creates new versions only of the tools that changed. Tools whose operation is no longer in the description are switched off. Requests waiting for approval on a changed or removed tool can no longer run, and the preview says how many. Clicking Import cancels them, with tool_changed or tool_disabled.

Operations become tools#

Gatelion reads operations with the methods GET, POST, PUT, PATCH and DELETE.

Tool id. The id is the connection's System key, a dot, and the operation's operationId. With system key erp and operationId: purchase_orders.create, the tool id is erp.purchase_orders.create. Gatelion lowercases the operationId and replaces other characters than letters, digits, _ and . with _, so createPurchaseOrder becomes createpurchaseorder. Without an operationId, the id is built from the method and path, for example post_purchase_orders. If two operations end up with the same id, the second gets _2, the third _3, and so on. Tool ids are at most 100 characters; an operation whose id would be longer isn't supported.

Choose operationId values with your policy in mind: rules name tools by these ids.

Name and description. The tool's name is x-gatelion-name, otherwise the summary, otherwise words made from the tool id. Its description is the description, otherwise the summary. Agents see both, so write them for an agent that has never seen your API.

Risk. By default GET is a read, DELETE is high risk, and POST, PUT and PATCH are writes. Writes are never retried, and a write without a reliable answer is marked unknown. Change the risk with x-gatelion-risk.

Arguments#

The tool's arguments come from the operation's parameters and its request body:

• Path, query and header parameters become arguments with the parameter's name. A query parameter may be an array of plain values; other structured values are only supported in the body.
• Cookie parameters aren't supported, and headers the Gateway controls itself (such as Authorization and any X-Gatelion-* header) are refused. A required parameter of this kind makes the operation unsupported; an optional one is left out.
• A JSON request body whose schema is an object with properties is flattened: each body field becomes a top-level argument. That's what lets a policy write "path": "max_total" rather than reaching into a body. If a body field has the same name as a parameter, or the body isn't an object, the whole body becomes one argument named body.
• Argument names keep letters, digits and _; other characters become _.

Schemas are made strict: every object accepts only its declared fields, and readOnly fields are left out. Gatelion can't represent free-form objects (any keys), oneOf/anyOf with different shapes, not, if/then/else, files or binary data, or schemas that refer to themselves. A required field like that makes the operation unsupported; an optional one is left out with a warning. A tool has at most 300 fields.

How values are handled:

• type: integer arrives as an integer.
• type: number is treated as an exact decimal. Agents send it as text such as "1500.25", and your API receives a JSON number. Gatelion doesn't check minimum, maximum or multipleOf on decimals; your API still does.
• A string path parameter is an identifier by default (see x-gatelion-identifier).

Responses#

Gatelion reads the first 2xx response with a JSON body. Its top-level properties are the tool's output fields: what the agent gets back. Change them with x-gatelion-output-fields.

Some values are replaced with [REDACTED] before the agent or the audit trail sees them:

• Fields at any depth whose names contain password, passwd, secret, token, api_key, apikey, cookie, credential, private_key or authorization.
• Top-level response properties named like secrets, by whole words in the name (split on _, -, . and capital letters): password, passwd, passcode, secret, token, apikey, ssn, cvv, cvc, pin, iban, cardnumber, or the pairs api key, card number, credit card, private key and security code. So access_token, cardNumber and user_password are redacted, while passenger_name, boarding_card and discard_reason are not (the first rule above still applies at any depth). writeOnly properties are redacted too.
• Tools imported before this rule keep their earlier list until you re-import their description; the re-import shows them as changed.
• Anything you list in x-gatelion-sensitive-fields.

Only your API's error code reaches the agent, never its error text.

Extensions on an operation#

Extensions on a parameter or schema#

The approval view#

x-gatelion-display controls what an approver sees on a request. Without it, Gatelion shows up to 8 required arguments and path parameters, with labels from each schema's title or the field name.

x-gatelion-display:
  title: Create purchase order
  fields:
    - { label: Supplier, path: supplier_id }
    - { label: Deliver to warehouse, path: warehouse }
    - { label: Most it may cost, path: max_total, format: money, currency: USD }
    - label: Lines
      path: lines
      format: table
      columns:
        - { label: SKU, path: sku }
        - { label: Quantity, path: quantity, format: number }

If the object isn't valid, Gatelion ignores it with a warning and builds the default view.

A complete operation#

paths:
  /purchase-orders:
    post:
      operationId: purchase_orders.create
      summary: Create purchase order
      description: Creates a purchase order. max_total is the most the order may cost.
      x-gatelion-risk: high
      x-gatelion-timeout-ms: 10000
      x-gatelion-output-fields: [id, po_number, status, total]
      x-gatelion-audit-fields: [po_number, total]
      parameters:
        - { name: Idempotency-Key, in: header, schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [supplier_id, warehouse, max_total]
              properties:
                supplier_id: { type: string, maxLength: 20, x-gatelion-identifier: true }
                warehouse: { type: string, maxLength: 20, x-gatelion-identifier: true }
                max_total: { type: string, x-gatelion-canonical: decimal, x-gatelion-currency: USD }
      responses:
        "201":
          description: The new purchase order.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PurchaseOrder" }

With system key erp, this becomes the tool erp.purchase_orders.create with the arguments supplier_id, warehouse and max_total, which a policy can test directly. See Policy format.

Still stuck? Contact support from the console.