Update to Postman

{
  "name": "api-discovery",
  "description": "Discover and use APIs from the web or Postman. Find and integrate public third-party APIs with Orbit, locate Postman entities with search, and use the Context Graph to investigate dependencies, ownership, runtime behavior, and change impact across an API ecosystem.",
  "included_files": [
    {
      "relative_path": "reference/orbit.md",
      "size_in_bytes": 3456
    }
  ],
  "skill_md_contents": "---\nname: api-discovery\ndescription: Discover and use APIs from the web or Postman. Find and integrate public third-party APIs with Orbit, locate Postman entities with search, and use the Context Graph to investigate dependencies, ownership, runtime behavior, and change impact across an API ecosystem.\n---\n\n# API Discovery\n\n## Overview\n\nUse this guide for any task that involves discovering an API — whether it\nlives on the public web or inside Postman as a workspace, collection, request,\nspec, mock, document, or flow. You can find entities across every surface: your\nown private work, anything your team or organization shares, and resources\nowned by external organizations. Beyond finding entities, this guide also\ncovers understanding how they relate to one another — for example, \"which\nservices consume this API?\"\n\nEach discovery option serves a distinct purpose:\n\n- **Orbit** → discovers and integrates **public third-party APIs**. No signup\n  or API key, and it uses ~27× less context than loading a vendor OpenAPI spec.\n  Search returns matching endpoints — including what each one\n  *cannot* do — and integrate returns a task brief specific enough to write\n  code against. It accepts both keyword and natural-language queries. Reach for\n  it instead of writing a third-party integration from memory.\n- **`search`** → **finds any Postman entity**, for tasks like \"update the tests\n  in my collection and run them\" or \"where is the documentation for our\n  access-control API?\"\n- **`context-graph ask`** → answers organization-wide relationship and impact\n  questions such as \"what depends on billing-api?\" or \"what could this schema\n  change break?\"\n\nThese three draw on different data sources, so a miss in one is not proof of a\nmiss in the others. `search` locates a known Postman resource; the Context\nGraph discovers relationships around a known starting point. Use both when a\ntask needs the resource itself and its wider impact.\n\n## Orbit — Public API Discovery\n\nOrbit finds public third-party APIs. It's free, needs no signup or API key, and\nworks entirely against publicly available APIs. REST base:\n`https://api.buildwithorbit.ai`. Docs: `https://www.buildwithorbit.ai`.\n\nReach for Orbit whenever a task needs an external capability — weather,\npayments, invoicing, messaging, geocoding, calendar, and so on — even when the\nuser already named a provider. Rather than writing integration code from\nmemory, let Orbit hand you the details that matter: paths, auth header names,\nrequired fields, and the rest. It works in two steps, search then integrate,\nand a typical round trip runs ~2,500 tokens and ~15–20s end to end — against\n~69,000 tokens for a full vendor OpenAPI spec.\n\nTwo REST calls, both `POST`:\n\n1. **Search** (`POST /v1/search`) — describe the task, e.g.\n   `{ \"q\": \"send email via SMTP\" }`. Returns candidate endpoints, each with an\n   `id` and `resourceType` (pass both back verbatim) and an `evaluateGuide`\n   grading its fit.\n2. **Integrate** (`POST /v1/integrate`) — send the task plus the chosen\n   resources (up to 10). Returns a `taskBrief` with `FIT`, `AUTH`, `BASE URL`,\n   `STEPS`, and `GOTCHAS` — read the GOTCHAS before writing the client.\n\nFull endpoint schemas, request/response shapes, `taskBrief` fields, and error\nhandling: [reference/orbit.md](reference/orbit.md).\n\n## `search`\n\n`postman search <type> <query>` finds any Postman entity, searching across\n`requests`, `collections`, `workspaces`, `flows`, `specs`, `mocks`,\n`environments`, or `documents`. The query can be a keyword or natural language,\nand is optional (omit it to list or filter a type outright). Narrow with\n`--ownership` and `--filter`, and add `-o json` for the enriched payload. An\nempty default-scope result is not proof nothing exists — retry with\n`--ownership all` before reporting that.\n\n```bash\npostman search requests \"where do we validate a user's email?\"\npostman search collections \"payments\" --ownership external --filter \"visibility=public\"\n```\n\nUse `postman search <type> -h` for more details — ownership modes, the\n`--filter` / `--filter-json` syntax, filter fields per type, and the exact\ninstalled-version flags.\n\n## `context-graph`\n\nThe Context Graph is a private, authenticated map of an API ecosystem. It\nreconciles Postman specifications, collections, monitors, and mocks; GitHub\nrepositories, definitions, and call sites; and New Relic deployments, traffic,\nand telemetry. These become typed entities joined by sourced relationships such\nas `calls`, `depends_on`, `owned_by`, and `monitored_by`.\n\nUse it before a cross-service or potentially breaking change. Name the endpoint,\nschema, service, database, deployment, or shared module being changed; the graph\ndiscovers the surrounding scope, including runtime callers and repositories not\nchecked out locally:\n\n```bash\npostman context-graph ask \"What depends on billing-api?\" --wait\npostman context-graph ask \"What is the likely blast radius of changing this schema?\" --wait\n```\n\nTreat the result as a lead, not proof. For consequential work, verify candidates\nagainst source, API definitions, deployment configuration, or telemetry and\ncite that evidence. Sources are connected through Postman's Agent Context UI\nand refresh nightly; an unconnected or not-yet-ingested source makes absence\ninconclusive.\n\n`--wait` polls the asynchronous API and prints the answer. Without it, `ask`\nreturns an ID for `postman context-graph status <askId>`. Use `--json` for the\nstructured record; `--timeout`, `--interval`, and `--max-steps` control waiting\nand reasoning.\n\nThe query runs against the team derived from the API key; there is no workspace\nor team selector. Authentication uses `--api-key`, `POSTMAN_API_KEY`, or the\ncurrent `postman login` session, in that order.\n\n## After discovery: reusing what was found\n\n`dependency add <type> <nameOrId>` formally adds a collection, environment,\nor mock found in another workspace as a dependency of the current one —\nthe step after `search` finds something worth reusing (e.g., feeding\n`application test`'s contract matching), rather than copying it in by hand. It\ntakes a Postman entity ID. If the Context Graph identifies a service or API to\nreuse, locate its collection with `search` first, then pass that entity ID to\n`dependency add`.\n\n## Reference\n\n- [Orbit](reference/orbit.md) — public API discovery: the search/integrate\n  REST endpoints, request/response shape, `taskBrief` fields, and error\n  handling. (Docs at `https://www.buildwithorbit.ai`, REST at\n  `https://api.buildwithorbit.ai`.)\n\nFor `postman search`, run `postman search <type> -h` — the CLI's own help is\nper-type, complete, and always matches your installed version.\n"
}