Importing your API
Supported formats
| Format | How we handle it |
|---|---|
| OpenAPI 3.x (JSON or YAML) | Native import. Paste the text, upload the file, or give a URL. |
| Swagger 2.0 | Converted to OpenAPI 3.x internally — same pipeline, same tools as the equivalent 3.x spec. |
| Postman Collection v2.1 | Folders become tags; auth helpers, variables, query/header params, and JSON bodies carry over. Paste JSON, upload the file, or give a URL. Multi-host collections collapse to the first server; exotic auth (hawk, digest, SigV4) imports unauthenticated. |
| Docs URL (no spec) | Coming in v2 — docs-led inference is one of our defensible moats. Today, creating a project from a docs URL parks the import until it ships. |
After import, the service builds an operations inventory, scores your documentation, and flags findings — then compiles one proposed tool per operation. Request bodies work for JSON bodies; form bodies import but aren't wired to the upstream yet, so key-protected form endpoints still need attention in review.
When an import fails
A broken spec fails loudly with exactly what's wrong and where, and nothing is stored:
- A bad
$refreturns the node pointer, the offending ref, and — when a
close match exists — a "did you mean" suggestion with a repair hint (e.g. inline external refs). Raw-text imports include 1-based line numbers.
- The failure is HTTP
400with a machine-readableissueslist, so you can
fix and re-import in one loop.
Header, query, cookie, and path parameters
Path, query, header, and cookie parameters all reach the upstream. If your spec declares an API key in the header, the credential broker injects the real key at call time and wins over the declared value — see Credentials.
What happens next
Import → compile is a background job (the console shows live progress and dedupes re-submits). Once tools are proposed, head to Review, edit, and approve — then run eval.