/import-new-api

name: import-new-api
description: Import an API that is not yet in jentic-public-apis end to end — generate or find an OpenAPI spec from the vendor's docs, optionally import it into the local Jentic registry so the agent is unblocked immediately, publish it to the user's reusable public import-openapi-specs repo, and open the import issue that drives it into the community catalog. Use when the user says "import the <vendor> API", "add <vendor> — it's not in the catalog yet", "generate a spec for <company> and open an import issue", or gives a docs URL to import. For fixing a spec already in the catalog, use contribute-spec-fix instead.
metadata:
  kind: freeform
  argument-hint: "[vendor name or API docs URL]"

Import a New API (spec → local registry → import-openapi-specs repo → import issue)

Import an API that is **not yet in [jentic-public-apis](https://github.com/jentic/jentic-public-apis)**: generate an OpenAPI spec from the vendor's docs, optionally import it into the **local Jentic registry first** (so the user's agent can execute it immediately), then publish it to the user's single reusable public repo `import-openapi-specs` and open the import issue that drives it into the community catalog.

This is the greenfield counterpart to `contribute-spec-fix` (which fixes a spec already in the catalog). Use `contribute-spec-fix` when the vendor already exists; use this skill when it does not.

Target: `$ARGUMENTS` (a vendor name like `firecrawl`, or a URL to the vendor's API docs). If only a company name is given, find its public API docs by searching for `<company> API documentation`.

Prerequisites

• `gh` CLI authenticated (`gh auth status`) with `repo` scope. Note which account is **active** —

the spec repo is created there and its raw links must resolve publicly.

• No local jentic-public-apis checkout needed — the vendor-existence check runs against GitHub

via `gh`.

• For the optional local-first step only: a running Jentic control plane and a registered agent

identity (`jentic doctor` confirms a resolvable identity with a usable token; `jentic api GET /me` shows what you can do).

Steps

1. Confirm the vendor is NOT already in the catalog (hard gate)

Check the live repo, not a local checkout:

gh api "repos/jentic/jentic-public-apis/contents/apis/openapi" --paginate \
  --jq '.[].name' | grep -i '<vendor-guess>'

Try the real domain (`firecrawl.dev`), bare name (`firecrawl`), and obvious variants (with and without subdomains: `api.foo.com` vs `foo.com`). **If a matching vendor directory exists, STOP** and tell the user — re-importing produces a duplicate, and the import workflow hard-fails on an existing version directory anyway. Point them at `contribute-spec-fix` if they meant to fix the existing spec, or offer a genuinely-absent alternative.

2. Generate the OpenAPI spec

Two paths, in strict priority order:

1. **Path 1 — look for an official spec first.** Probe `https://{domain}/openapi.json`, `/swagger.json`, `api.{domain}/openapi.json`, and the vendor's GitHub org (`raw.githubusercontent.com/{org}/{repo}/main/.../openapi.json`). Vendors often ship a spec in-repo (Firecrawl publishes one at `firecrawl/firecrawl/apps/api/openapi.json`). If found, download it, validate it has a top-level `openapi`/`swagger` key, and **add `info.x-jentic-source-url`** pointing at where it came from. Done — do not hand-generate. 2. **Path 2 — generate from docs** only if no official spec exists. Extract every endpoint, method, path/query/body param, and auth scheme; build valid OpenAPI 3.0.3 with response/error schemas referenced via `$ref`, root-level `security`, and `securitySchemes` under `components`.

In both paths, embed **`info.x-vendor`** = the vendor domain (e.g. `firecrawl.dev`) next to `info.x-jentic-source-url` — the local registry's ingest resolves vendor from `x-vendor` (falling back to `contact.name`) and fails with `missing vendor` without it.

**Validate** before moving on: parses as JSON/YAML, has `openapi`, `info.title`, and `paths` with ≥1 path; note the server URL.

**Private-host refusal (do not skip).** If any `servers[].url` points at a private or internal host, **refuse to publish and stop after the local-first step**:

python3 -c "
import json,sys,re
spec=json.load(open('<spec>.json'))
bad=re.compile(r'localhost|127\.|10\.|172\.(1[6-9]|2[0-9]|3[01])\.|192\.168\.|\.(internal|local|corp|lan)([/:]|$)')
hosts=[s.get('url','') for s in spec.get('servers',[])]
print('PRIVATE' if any(bad.search(h) for h in hosts) else 'OK', hosts)"

`PRIVATE` means this looks like an internal API — publishing it to a public repo would disclose it. Tell the user why you stopped; only continue if they explicitly confirm the API is public.

Decide the layout parts (used verbatim as the repo path, deterministically):

• **vendor.domain** — the real registrable domain with TLD (`firecrawl.dev`), lowercase, no

scheme, no `www.`, no API subdomain (`api.foo.com` → `foo.com`). Not a slug.

• **api-slug** — from `info.title`: lowercase, spaces and `/` → hyphens, strip any character that

is not `[a-z0-9-]`, collapse repeats (`Firecrawl API` → `firecrawl-api`).

• **version** — `info.version` verbatim (`1.0.0`, `v1.2`, `2023-01-01` are all fine as directory

names); `1.0.0` only when the spec has none.

3. Local-first: import into the local Jentic registry (optional)

If a local jentic-one instance is running, import the spec there **before** contributing upstream — the user's agent can execute the API immediately instead of waiting on catalog review. Skip this step if `jentic doctor` reports the control plane unreachable.

Local import needs the `apis:write` permission, which is not granted by default — ask your operator to grant it to this agent in the dashboard. Granted permissions bake into your token at mint time, so once they confirm run `jentic logout` (it clears only the cached token, not your identity) and the next call