OpenAPI Spec

• The OpenAPI Specification (OpenAPI Spec, sometimes still called Swagger) is a language-agnostic, machine-readable format for describing REST APIs. It is maintained by the OpenAPI Initiative under the Linux Foundation.
• An OpenAPI spec describes an API's endpoints, request and response shapes, authentication, and errors in a single YAML or JSON file. Tools consume it to generate clients, servers, docs, and tests.
• Guild uses OpenAPI specs to bulk-import operations into an integration. One command turns a spec file into a full set of callable operations agents can invoke as tools.
• The command is: guild integration operation create <integration> --openapi ./openapi.yaml. It saves the pain of hand-declaring every endpoint your agents will call.

The OpenAPI Specification is a standard for describing HTTP APIs in a machine-readable file. A single YAML or JSON document lists every endpoint the API exposes, the shape of every request and response, the authentication methods it accepts, and the errors it returns. Anything that speaks HTTP can be described this way, and any tool that reads OpenAPI can then work with that API without a human writing custom glue.

The format grew out of Swagger, which was donated to the Linux Foundation and rebranded as the OpenAPI Initiative in 2015. The current version is OpenAPI 3.x. "Swagger" is still commonly used to refer to specific tools (Swagger UI, Swagger Editor), while "OpenAPI" refers to the spec itself.

If you have worked with SDK generators, API documentation portals, or contract-testing tools, you have almost certainly encountered OpenAPI. It is one of the most widely adopted specifications in modern API tooling.

Paths and operations

The heart of a spec is the paths section. Each path (like /users or /orders/{orderId}) lists the HTTP methods it supports, and each method describes what an operation does: the parameters it takes, the request body it expects, the responses it can return, and the auth it requires. Every path + method combination is one operation.

Components: schemas, security, and reusables

The components section holds reusable pieces — data schemas, security schemes, common parameters, response bodies — that individual operations reference. Keeping shapes in components (rather than inlining them in every operation) is what makes a large API spec maintainable.

Security schemes

OpenAPI describes auth in a first-class way: bearer tokens, API keys, OAuth 2, mutual TLS, and more. Tools that consume the spec can generate the right auth flow for a client automatically.

YAML or JSON, both valid

Specs can be written in YAML or JSON. YAML is more human-readable and is what most teams choose for a source-of-truth spec. Tools tend to read either, so pick the one your team prefers to maintain.

One source of truth for many consumers

An API spec is not just documentation. It is a contract that clients, servers, docs, tests, and code generators all read from. When the spec changes, every downstream artifact can be regenerated. That is a huge amount of leverage from one well-maintained YAML file.

Machines can do work humans should not have to

Hand-writing SDKs, API docs, and test scaffolding for every endpoint is tedious and error-prone. OpenAPI-aware tools do that mechanically. The engineering time saved by generating clients and mocks from a spec is substantial and compounding.

It bridges design and implementation

Design-first workflows write the OpenAPI spec before code and use it as the contract implementations must satisfy. Code-first workflows generate the spec from the running server. Either way, the spec is what makes API design a conversation instead of a series of surprises.

Guild integrations expose external services to agents as sets of callable operations. Rather than declaring every operation by hand, Guild lets you point at an OpenAPI spec and import every operation the spec describes in one command.

The command

guild integration operation create myorg~my-service --openapi ./openapi.yaml

Substitute myorg~my-service with the qualified name of your integration and ./openapi.yaml with the path to your spec. Guild reads the spec, walks every path and method, and creates a corresponding operation on the integration for each one.

What the import brings across

Guild picks up the endpoint path and method, the parameters and request body schema, the response schema, and the auth requirements. The imported operations behave like any other operation on the integration — they can be exposed to agents as tools, invoked with typed inputs, and tracked in session logs.

When to use it

OpenAPI bulk-import is the fastest way to give an agent access to a large or evolving API. If the service you want to call publishes an OpenAPI spec (most modern SaaS APIs do), skip hand-declaration and use the spec. When the API changes, re-run the command and update the operations in place. Reference: the CLI commands guide for integrations.

Not every spec is well-formed

OpenAPI is a large spec and not every published API spec is complete or valid. If bulk-import fails or produces incorrect operations, the first place to look is the spec itself. Validation tools (Redocly's, Stoplight's, the OpenAPI Initiative's) will catch most issues before you import.

Auth still has to be configured

Import creates the operations, but the credentials the integration uses to call them still need to be connected. In Guild, credentials are configured at the organization level and scoped per workspace. An imported operation without connected credentials will fail at call time.

The spec is a snapshot

An OpenAPI spec captures the API at the moment you imported it. If the upstream API adds endpoints or changes shapes, re-running the import against the updated spec keeps your integration in sync. Automate this if the service you depend on ships frequently.

Swagger 2 vs. OpenAPI 3

Modern tooling assumes OpenAPI 3.x. If you have a Swagger 2 spec, convert it first — most OpenAPI tools include or bundle a converter.

Guild is a control plane for AI agents, a place to build, deploy, and govern the agents your teams run in production. OpenAPI import is how you bring an entire external API into Guild as a set of callable operations your agents can use as tools without hand-writing anything.

• The CLI commands reference documents the full integration operation create command.
• Integrations use qualified names like every other Guild resource.
• Explore the Guild CLI and the rest of the platform at guild.ai.