Docs, SDKs & OpenAPI

To build an API from an existing description, import it. Open the API from APIs and choose Import / Export in the API editor's section list. REST and HTTP APIs have it, and only Owners and Admins can import.

1. Under Import OpenAPI, paste a Swagger 2.0 or OpenAPI 3.x document in JSON or YAML into Document, or choose a file under Upload a file. Documents can be up to 6 MB.
2. Pick the Import mode: Overwrite draft, the default, replaces the draft with the document; Merge into draft combines the two.
3. Optional: turn on Fail on warnings to stop the import if the document produces any warning.
4. Optional: choose Preview Warnings for a dry run. It lists up to 50 warnings and changes nothing.
5. Choose Confirm Import. For an overwrite, Pods asks you to confirm.

An overwrite replaces the draft's routes or resources, integrations, models and authorizers. Integrations described in the document are created and connected to their routes or methods. The import changes only the draft, so deploy afterwards to serve it.

To download an API's description, open it from APIs, choose Import / Export in the API editor's section list and go to Export. The file is built from what a stage serves, never the draft, so the API needs at least one stage. Only Owners and Admins can export.

• Stage: the stage to export.
• Type: OpenAPI 3.0, the default, or Swagger 2.0.
• Format: JSON or YAML.
• Extensions: AWS, the default, which lets the file round-trip into AWS API Gateway; Pods; None; or Postman v2.1 for a Postman collection.
• Include documentation: on by default. Embeds the stage's documentation in the file.

Choose Download. The file is named after the API and the stage.

Documentation in Pods is a set of documentation parts, each attached to one place in a REST API. Open the API from APIs, choose Docs in the API editor's section list, then Add Part.

• Location type: API, AUTHORIZER, MODEL, RESOURCE, METHOD (the default), PATH_PARAMETER, QUERY_PARAMETER, REQUEST_HEADER, REQUEST_BODY, RESPONSE, RESPONSE_HEADER or RESPONSE_BODY.
• Path, Method and Status code: where it applies, such as /pets, GET and 200. Use * for the method or status code to cover every match.
• Properties: a JSON object, such as a description and summary.

Choose Add Part. A part with a *, or on a parent path, applies to everything beneath it until a more specific part overrides it; the list marks these with Inherits. To remove a part, choose Delete in its ⋯ menu and confirm. Owners, Admins and Managers can edit documentation.

A documentation version freezes the current documentation parts under a name, so later edits don't change it. In the API editor's Docs section:

1. Choose Freeze Version, type a Version name such as v1, and choose Freeze Version.
2. To show a version on a stage, choose Pin to Stage, or Pin to stage in the version's ⋯ menu. Pick the Stage and the Version, then choose Pin Version.

To unpin, pick No version (unpin) and choose Unpin. Deleting a documentation part leaves frozen versions as they were. The versions list shows how many parts each one holds and when it was frozen.

Pods can generate a client library for a REST API from what a stage serves. Open the API from APIs and choose SDKs in the API editor's section list. The API needs a stage first, and only Owners and Admins can generate SDKs.

1. Pick the Stage to build from.
2. Pick a Language: JavaScript, TypeScript (the default) or Python.
3. Optional: change the Package name (pods-client to start with) and Version (0.1.0).
4. Choose Generate & Download.

Pods downloads the SDK as a ZIP file. The client calls the stage's invoke URL, and describes request and response bodies from the API's models.

Agent tools serve a REST API's operations to AI agents as MCP tools, one tool per operation. Open the API from APIs and choose Agent Tools in the API editor's section list. Agent tools are set per stage, and the API needs a stage first.

1. Pick the Stage.
2. Turn on Serve agent tools. It saves straight away.
3. Optional: under Allowed operations, list the operations to offer, one per line, as an operation name or a method and path such as GET /pets/{id}, then choose Save Allow-List. Leave it empty to offer every operation.

Agents connect over MCP's Streamable HTTP at the stage's invoke URL followed by /_mcp. Each tool call runs through the stage like a normal request, so authorizers, API keys, throttling, the firewall and logs all apply: give the agent's client the same Authorization and x-api-key headers a normal caller sends. Tool descriptions come from the API's documentation parts. Owners, Admins and Managers can change agent tools.