Importing API descriptions and saved requests

tungsten init --from <input> accepts one API description or saved-request input at a time. Local importing parses data offline: it sends no API request, replays no capture, and executes no shell command or collection script. Remote document acquisition is a separate, explicit step described below. Importing writes an initialized project for the ordinary check, generate and mock commands. The setup input limit is 8 MiB; use the explicit compiler flow for larger native OpenAPI documents.

Remote documents and pinned Git inputs

--from also accepts an HTTP(S) document URL or a git+https://github.com/example/api@main#contracts/openapi.yaml input. Acquisition downloads the selected source before the same format-specific import and review rules apply; it does not replay captured requests or execute repository code. Native OpenAPI URLs and Git inputs also work directly as compiler paths and manifest inputs. Converted formats still enter through init.

The supported-input guide provides complete commands, private-source authentication, cache retention, source pins, --offline and --refresh-inputs behavior, and acquisition limits. Retain the complete source cache for offline use. A converted import whose source changes must be re-imported into a fresh project and reviewed again. Remote references from an HTTP document remain blocked; Git references must stay inside the materialized repository tree. Neither route discovers an API from live traffic.

Local input formats

Run tungsten explain <code> for a diagnostic, including PM, HR and TC codes. File access, missing route templates and other setup errors can also be reported directly by init before the importer produces a coded diagnostic. Commands here assume a shell that preserves single-quoted arguments; in Windows CMD, put path templates in double quotes instead. --shell-dialect describes the saved command's syntax, independently of the shell running tungsten.

Review before live use

Imported operations stay unreviewed. Conversion does not establish complete response types, authentication, authorization, required fields, safe retry rules or permission to call a live origin. Review the normalized contract and every import report, including omissions, before using the generated SDK.

For each imported operation, separately review its safety tier and exact allowed origin in agent.yml, using imported_reviewed_safety and imported_reviewed_origins under its tools entry. Ordinary safety defaults, a route mapping, --server-url and confirmation flags do not count as import review. See the manifest reference and safety guide. Use the operation ID in your generated manifest rather than copying an example ID.

Imported-operation policy is supported by TypeScript, Python, Rust, MCP, WebMCP and docs targets. Java, Kotlin, C#, F#, Dart, Ruby and external emitters without an explicit import-policy capability are refused with TG0705; configuring a target does not bypass this gate. Build and inspect locally with a loopback mock before separately approving any live use.

Except for native OpenAPI, conversion writes imported.openapi.json next to tungsten.yml and agent.yml; Postman, saved-request and HAR routes also write import-report.json. Manual setup writes inferred.openapi.json and inference-report.json. Keep original inputs separately. Use a fresh output directory for conversion; existing converted files are not silently overwritten.

Postman collections

The importer supports Collection v2.1 JSON, nested folders, raw or structured URLs, explicit :path variables, unique query/header names, raw JSON request bodies and saved JSON responses for multiple statuses. Collection, folder and request auth helpers inherit; explicit noauth overrides inheritance. Supported helpers are basic, bearer and header/query API keys. Actual credentials belong in the generated client's runtime configuration.

Collection/folder/request variables are expanded with bounded precedence; unresolved shape-affecting or dynamic variables cannot be guessed. The CLI uses the collection's literal variables and does not load a Postman environment file. Origin-only unresolved variables need explicit client configuration. Pre-request or unknown scripts, unsupported auth helpers, non-JSON bodies/responses and other unsupported request structures are omitted per item and listed in import-report.json. Test scripts are skipped and counted. If every request is omitted, import fails with PM008. Never interpret a successful partial import as coverage of the whole collection; fix omitted items or supply reviewed OpenAPI.

Saved cURL and HTTP request files

Save a single cURL invocation as UTF-8 text, then import that file. Accepted options are -X/--request, -H/--header, --url, and one inline JSON body using -d, --data, --data-raw, --data-binary or --json. Data flags need an explicit JSON Content-Type; --json supplies it. The default method is POST with a body and GET otherwise. File uploads/references, config files, pipelines, redirections, compound commands and shell expansions are rejected.

Choose --shell-dialect posix, cmd or powershell to match the saved text. POSIX accepts single/double quotes and backslash continuations; CMD accepts double quotes and caret continuations; PowerShell accepts its quoting and backtick continuations, using curl.exe explicitly. Variable, expression and command expansion are rejected. Quote POSIX wildcard, brace and tilde arguments; cURL URL brace lists and bracket ranges are unsupported even when quoted. This parser implements a bounded syntax subset, not a shell emulator.

Each saved request needs an explicit --route, in input order. For a captured URL https://api.example.test/pets/123, use --route '/pets/{id}'; placeholders occupy complete segments and literal segments must match. A literal path such as /health also needs a route declaration. Detection is automatic for .curl, .http and .rest; --input-format curl or --input-format http overrides it.

HTTP files accept METHOD URL (optionally HTTP/1.1), headers, a blank separator and an optional inline JSON body. Repeat --route once per ### separated request. The CLI supplies no variable bindings: materialize {{name}} placeholders before importing. Inline variable declarations, scripts and file includes fail. Repeated query/header names, captured credentials and transport override headers need a reviewed endpoint manifest or OpenAPI document. Missing response samples remain unknown; importing a request does not discover a response schema.

HAR captures and reviewed paths

Select an exact canonical origin with --har-origin when the capture contains more than one origin. Include/exclude filters use literal path prefixes and exclusions win. Every retained path must be reviewed before converted output is saved, including paths that contain no variable segment.

For example, paths.json can contain:

{"/pets/123": "/pets/{id}", "/health": "/health"}

Alternatively, repeat --route '/pets/{id}' --route /health; the most literal matching template wins. Ambiguous or malformed mappings fail with HR006. Number- or UUID-looking segments are never generalized automatically. Exclude unneeded paths with --exclude-prefix, narrow them with --include-prefix, and remove sensitive property names with repeatable --redact-property flags.

Credential/cookie header and query values are omitted; JSON observations retain shapes rather than sample values. Retained literal paths and property names are structural output, so review them for personal or confidential data. Arbitrary sensitive data cannot be detected automatically. Auth stays unknown. Encoded, truncated, missing and non-JSON bodies remain unknown; responses and statuses in a capture do not prove completeness. Each imported operation stays a partial capture, even after its path has been reviewed.

Swagger 2.0 conversion

The converter preserves local definitions and schema references, reusable local parameters/responses, body/form parameters, supported serialization, multipart uploads, basic/API-key/OAuth security, explicit servers and supported schema constraints. It writes OpenAPI 3.0.3 before ordinary normalization.

External references, path-item references, chained parameter/response references, reference siblings, ambiguous media/transport choices and unsupported constructs fail with TG0111 and an original-source pointer. Explicit consumes/produces is required when a payload schema needs a media type; a host requires schemes. Supply a reviewed OpenAPI document when conversion cannot preserve semantics. OpenAPI 3.2 remains unsupported. Conversion does not approve imported operations.

JSON Schema models and endpoint manifests

A standalone JSON Schema model does not declare HTTP endpoints. Pair models with an endpoint manifest (endpoint_manifest: 1) declaring title/version, base URL, endpoint method/path/ID, parameters, media/status mappings and security. Models can be embedded or referenced from local JSON/YAML files. Parameters may be path, query or header; auth declarations support basic, bearer and API keys in header/query/cookie locations, with no credential values.

The supported JSON Schema 2020-12 subset includes types/null, properties and requiredness, additional properties, items/prefixItems, $defs and static $ref, compositions, numeric/string/array/object constraints and readOnly/writeOnly. Other dialects, IDs/anchors, dynamic references, conditional/unevaluated keywords and literal-bearing annotations (default, examples, enum, const) fail with TG0112 instead of being silently weakened. All references must stay inside the manifest's directory tree; network, absolute and percent-encoded references are rejected. Models are not rewritten and no application is executed.

For one manually declared endpoint, --method and --endpoint are an alternative to --from. Optional --request-example / --response-example files contribute structure only; responses use status 200. Missing observations remain unknown, and this path carries the same imported-operation review rules.