# api-discovery

Helps agents find public APIs to integrate, search Postman resources, and trace which services depend on a given API.

Skill by Postman. Category: Agent craft.

## Install

Project (for this project only):

```sh
npx skills add postmanlabs/postman-plugin --skill api-discovery
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add postmanlabs/postman-plugin --skill api-discovery -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Warn

Installs: 1. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/postmanlabs/postman-plugin/api-discovery)

## Source

[Open the source](https://github.com/postmanlabs/postman-plugin/tree/HEAD/skills/api-discovery). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
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.
---

# API Discovery

## Overview

Use this guide for any task that involves discovering an API — whether it
lives on the public web or inside Postman as a workspace, collection, request,
spec, mock, document, or flow. You can find entities across every surface: your
own private work, anything your team or organization shares, and resources
owned by external organizations. Beyond finding entities, this guide also
covers understanding how they relate to one another — for example, "which
services consume this API?"

Each discovery option serves a distinct purpose:

- **Orbit** → discovers and integrates **public third-party APIs**. No signup
  or API key, and it uses ~27× less context than loading a vendor OpenAPI spec.
  Search returns matching endpoints — including what each one
  *cannot* do — and integrate returns a task brief specific enough to write
  code against. It accepts both keyword and natural-language queries. Reach for
  it instead of writing a third-party integration from memory.
- **`search`** → **finds any Postman entity**, for tasks like "update the tests
  in my collection and run them" or "where is the documentation for our
  access-control API?"
- **`context-graph ask`** → answers organization-wide relationship and impact
  questions such as "what depends on billing-api?" or "what could this schema
  change break?"

These three draw on different data sources, so a miss in one is not proof of a
miss in the others. `search` locates a known Postman resource; the Context
Graph discovers relationships around a known starting point. Use both when a
task needs the resource itself and its wider impact.

## Orbit — Public API Discovery

Orbit finds public third-party APIs. It's free, needs no signup or API key, and
works entirely against publicly available APIs. REST base:
`https://api.buildwithorbit.ai`. Docs: `https://www.buildwithorbit.ai`.

Reach for Orbit whenever a task needs an external capability — weather,
payments, invoicing, messaging, geocoding, calendar, and so on — even when the
user already named a provider. Rather than writing integration code from
memory, let Orbit hand you the details that matter: paths, auth header names,
required fields, and the rest. It works in two steps, search then integrate,
and a typical round trip runs ~2,500 tokens and ~15–20s end to end — against
~69,000 tokens for a full vendor OpenAPI spec.

Two REST calls, both `POST`:

1. **Search** (`POST /v1/search`) — describe the task, e.g.
   `{ "q": "send email via SMTP" }`. Returns candidate endpoints, each with an
   `id` and `resourceType` (pass both back verbatim) and an `evaluateGuide`
   grading its fit.
2. **Integrate** (`POST /v1/integrate`) — send the task plus the chosen
   resources (up to 10). Returns a `taskBrief` with `FIT`, `AUTH`, `BASE URL`,
   `STEPS`, and `GOTCHAS` — read the GOTCHAS before writing the client.

Full endpoint schemas, request/response shapes, `taskBrief` fields, and error
handling: [reference/orbit.md](reference/orbit.md).

## `search`

`postman search <type> <query>` finds any Postman entity, searching across
`requests`, `collections`, `workspaces`, `flows`, `specs`, `mocks`,
`environments`, or `documents`. The query can be a keyword or natural language,
and is optional (omit it to list or filter a type outright). Narrow with
`--ownership` and `--filter`, and add `-o json` for the enriched payload. An
empty default-scope result is not proof nothing exists — retry with
`--ownership all` before reporting that.

```bash
postman search requests "where do we validate a user's email?"
postman search collections "payments" --ownership external --filter "visibility=public"
```

Use `postman search <type> -h` for more details — ownership modes, the
`--filter` / `--filter-json` syntax, filter fields per type, and the exact
installed-version flags.

## `context-graph`

The Context Graph is a private, authenticated map of an API ecosystem. It
reconciles Postman specifications, collections, monitors, and mocks; GitHub
repositories, definitions, and call sites; and New Relic deployments, traffic,
and telemetry. These become typed entities joined by sourced relationships such
as `calls`, `depends_on`, `owned_by`, and `monitored_by`.

Use it before a cross-service or potentially breaking change. Name the endpoint,
schema, service, database, deployment, or shared module being changed; the graph
discovers the surrounding scope, including runtime callers and repositories not
checked out locally:

```bash
postman context-graph ask "What depends on billing-api?" --wait
postman context-graph ask "What is the likely blast radius of changing this schema?" --wait
```

Treat the result as a lead, not proof. For consequential work, verify candidates
against source, API definitions, deployment configuration, or telemetry and
cite that evidence. Sources are connected through Postman's Agent Context UI
and refresh nightly; an unconnected or not-yet-ingested source makes absence
inconclusive.

`--wait` polls the asynchronous API and prints the answer. Without it, `ask`
returns an ID for `postman context-graph status <askId>`. Use `--json` for the
structured record; `--timeout`, `--interval`, and `--max-steps` control waiting
and reasoning.

The query runs against the team derived from the API key; there is no workspace
or team selector. Authentication uses `--api-key`, `POSTMAN_API_KEY`, or the
current `postman login` session, in that order.

## After discovery: reusing what was found

Finding another service's workspace does not make it the workspace for the
current repository. `workspace pull` is for working on the service that owns
that workspace, from that service's repository. If the service is only a
dependency, or the user only wants to inspect one of its resources, keep the
current repository connected to its own workspace and use the dependency
feature instead.

Use `postman dependency add <type> <name-or-id>` to declare and download the
selected resource rather than copying it by hand or pulling the other
service's entire workspace. Supported types are `collection`, `environment`,
and `mock`. Pass the entity ID returned by `search`, or use the entity name;
when resolving a name in a specific workspace, add `--workspace
<workspace-id>`. If the Context Graph identifies only a service or API, locate
the concrete entity with `search` first.

Dependencies are recorded in `.postman/resources.yaml` and downloaded under
`postman/.dependencies/`, so the copy works locally straight away. Use
`postman dependency list` to inspect declarations, `postman dependency
install` to download declared dependencies after a clone or in CI, `postman
dependency update` to refresh them from Postman, and `postman dependency
remove <name-or-id>` to delete a declaration and its downloaded files. The
`list`, `install`, `update`, and `remove` commands accept `--type <type>`;
`install` and `update` can also target one declared dependency by name.

## Reference

- [Orbit](reference/orbit.md) — public API discovery: the search/integrate
  REST endpoints, request/response shape, `taskBrief` fields, and error
  handling. (Docs at `https://www.buildwithorbit.ai`, REST at
  `https://api.buildwithorbit.ai`.)

For `postman search`, run `postman search <type> -h` — the CLI's own help is
per-type, complete, and always matches your installed version.
````

- Previous: [collection-schema-v3](https://syn4pse.dev/terminal/postman-collection-schema-v3.md)
- Next: [api-documentation](https://syn4pse.dev/terminal/postman-api-documentation.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
