> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usefused.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bring your own API in

> Turn a spec, a GraphQL endpoint, or a documentation page into a versioned service.

Your internal billing API, a partner's API, the SaaS tool nobody has integrated yet — if it has a description, Fused can turn it into a service your workspace can enable. If it has no description at all, Fused can read the provider's documentation instead.

Import is a two-step review: `plan` parses the source and diffs it against the live service, `apply` commits exactly what you reviewed.

## Import from a spec

The format is detected automatically — OpenAPI 3, Swagger 2, Google Discovery, AsyncAPI, Postman Collection, WSDL, GraphQL SDL, or an introspectable GraphQL endpoint.

```bash theme={null}
fused-cli import plan ./openapi.json \
  --name "Internal Billing API" \
  --slug billing-api \
  --target endpoints

fused-cli import apply
```

Remote sources work the same way:

```bash theme={null}
fused-cli import plan \
  --url https://developer.example.com/asyncapi.yaml \
  --name "Events API" \
  --slug events-api \
  --version 2026-08
```

<Note>
  Formats that carry no version of their own — Postman collections especially — need `--version`. Without it, planning stops with `import_version_required` and writes no receipt. The CLI never invents a version.
</Note>

## When you only have a URL

`import plan` expects you to know where the spec lives. `import discover` does not — point it at the provider and it finds a machine-readable spec if one exists, and crawls the documentation if it does not.

```bash theme={null}
fused-cli import discover \
  --url https://developer.example.com \
  --name "Docs API" \
  --slug docs-api
```

Discovery is a session rather than a single shot. It resolves the source, pulls out the operations, extracts a contract, and proposes optional Fused enrichment — then stops and waits for you to review. In a terminal it opens the Engine's review page; `--no-browser` prints the URL and waits instead.

It never applies. When the session reaches `plan_ready` it writes the same receipt `import plan` would, at `.fused/.state/import.plan.json`, and you commit it the same way:

```bash theme={null}
fused-cli import apply
```

Sessions outlive the command. Resume one with `--session <id>`; the identity and crawl limits it started with are fixed and cannot be changed on resume.

<Note>
  Nothing is interactive in CI. Pass `--all` or repeat `--select 'GET:/invoices'`, then either repeat `--accept-proposal <id>` or pass `--reject-enrichment`. Non-interactive runs never open or wait for browser review.
</Note>

## Flags

### `import plan`

| Flag            | What it does                                                      | Example                                                                               |
| --------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `--name`        | Service name (required)                                           | `fused-cli import plan ./api.json --name "Billing API" --slug billing`                |
| `--slug`        | Account-scoped slug to create or update (required)                | `fused-cli import plan ./api.json --name Billing --slug billing-api`                  |
| `--url`         | Imports from an HTTP(S) source instead of a local file            | `fused-cli import plan --url https://api.example.com/openapi.json --name X --slug x`  |
| `--version`     | Provider version when the source declares none                    | `fused-cli import plan ./collection.json --name X --slug x --version 2026-08`         |
| `--target`      | What to import: `all`, `endpoints`, or `webhooks`                 | `fused-cli import plan ./api.yaml --name X --slug x --target all`                     |
| `--overlay`     | A local overlay that corrects or extends provider metadata        | `fused-cli import plan ./api.json --name X --slug x --overlay ./billing.overlay.yaml` |
| `--strict`      | Rejects the import when any warning or error diagnostic is raised | `fused-cli import plan ./api.json --name X --slug x --strict`                         |
| `--public`      | Marks a new service public in the Registry                        | `fused-cli import plan ./api.json --name X --slug x --public`                         |
| `--category`    | Category for a new service                                        | `fused-cli import plan ./api.json --name X --slug x --category payments`              |
| `--json`        | Returns the raw plan response for CI or an agent                  | `fused-cli import plan ./api.json --name X --slug x --json`                           |
| `--receipt-out` | Writes the plan receipt to a chosen path                          | `fused-cli import plan ./api.json --name X --slug x --receipt-out ./ci/import.json`   |

### `import apply`

| Flag            | What it does                                              | Example                                                            |
| --------------- | --------------------------------------------------------- | ------------------------------------------------------------------ |
| `--plan-id`     | Applies one exact remote plan; needs `--review-hash`      | `fused-cli import apply --plan-id pln_31a… --review-hash sha256:…` |
| `--review-hash` | The combined Registry review hash paired with `--plan-id` | `fused-cli import apply --plan-id pln_31a… --review-hash sha256:…` |
| `--receipt`     | Applies a specific receipt instead of the most recent     | `fused-cli import apply --receipt ./ci/import.json`                |

### `import discover`

| Flag                  | What it does                                                                | Example                                                                                |
| --------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `--url`               | Provider spec or documentation URL; required unless resuming                | `fused-cli import discover --url https://developer.example.com --name X --slug x`      |
| `--name`              | Service name; required unless resuming                                      | `fused-cli import discover --url … --name "Docs API" --slug docs-api`                  |
| `--slug`              | Account-scoped slug to create or update; required unless resuming           | `fused-cli import discover --url … --name X --slug docs-api`                           |
| `--session`           | Resumes a session; its identity and limits are already fixed                | `fused-cli import discover --session ses_9f2…`                                         |
| `--source-mode`       | `auto` finds a spec and falls back to docs; force one with `spec` or `docs` | `fused-cli import discover --url … --name X --slug x --source-mode docs`               |
| `--all`               | Selects every discovered operation                                          | `fused-cli import discover --url … --name X --slug x --all`                            |
| `--select`            | Selects one operation as `METHOD:/path`; repeatable                         | `fused-cli import discover --url … --name X --slug x --select 'GET:/invoices'`         |
| `--accept-proposal`   | Accepts one enrichment proposal by ID; repeatable                           | `fused-cli import discover --session ses_9f2… --accept-proposal prp_4c1…`              |
| `--reject-enrichment` | Takes the contract as extracted, with no enrichment                         | `fused-cli import discover --url … --name X --slug x --all --reject-enrichment`        |
| `--overlay`           | A local Fused overlay reviewed alongside the discovered contract            | `fused-cli import discover --url … --name X --slug x --overlay ./billing.overlay.json` |
| `--version`           | Provider version when discovery cannot find one                             | `fused-cli import discover --url … --name X --slug x --version 2026-08`                |
| `--no-browser`        | Prints the review URL and waits, rather than opening it                     | `fused-cli import discover --url … --name X --slug x --no-browser`                     |
| `--receipt-out`       | Writes the receipt somewhere other than the default path                    | `fused-cli import discover --url … --name X --slug x --receipt-out ./ci/import.json`   |
| `--json`              | Prints the plan-ready snapshot for CI or an agent                           | `fused-cli import discover --url … --name X --slug x --all --json`                     |
| `--timeout`           | Caps the whole session; defaults to 20m                                     | `fused-cli import discover --url … --name X --slug x --timeout 45m`                    |

`--workers`, `--max-pages`, and `--max-depth` request crawl limits. The Registry clamps whatever you ask for, so treat them as hints rather than guarantees.

`--all` and `--select` are alternatives, as are `--accept-proposal` and `--reject-enrichment`.

## Overlays beat forking

An overlay corrects or extends provider metadata without you maintaining a fork of their spec. It stays local; the Registry parses, validates, and merges it, then returns one combined review hash. The receipt binds apply to that exact source *and* overlay — so what you reviewed is what lands, not whatever the URL happens to return later.

## Diagnostics

Planning reports structured diagnostics wherever provider metadata cannot be represented exactly. Treat the diagnostic codes as the stable contract for automation; the messages are written for people.

* `--json` gives you the diagnostic objects unchanged.
* `--strict` fails the plan on warnings and errors.
* Info-level diagnostics never fail strict mode.

<Warning>
  Import plan and apply allow 20 minutes by default. If apply times out, its outcome is unknown — the Registry may have committed before the response was lost. Do not replay the receipt. Check `workspace services list -q <slug>` and `service show <slug>` first.
</Warning>

## Re-importing

Importing the same provider version again creates a new internal revision rather than mutating the published one. A different provider version creates that version. Your slug resolves within your own Registry account: a matching slug updates that service, an unknown slug creates it.

<Card title="Enable it in your workspace" icon="toggle-on" href="/workspace/enable-a-service">
  Import registers the service. Enabling it is what makes it callable.
</Card>