API Discovery: Find the APIs You Already Run

Overview

Most organisations run more APIs than any one list shows. Some live in a gateway, some in a repository, some only in the traffic of an application. API Discovery reads the places where APIs are declared and used, and keeps one inventory of them.

Each row in the inventory tells you three things:

• Where it came from. Every source that reported the operation is listed as evidence.
• How sure we are that it exists. Each row is Confirmed, Observed or Inferred, with the reasons written out. There is no single bare score.
• Whether it can be tested. Each row is Ready to test or Not ready to test, and each blocker is named in a sentence.

When you are ready, you accept an operation into a project. It then becomes an ordinary endpoint you can generate tests for.

Discovery finds APIs. It does not create tests from traffic, and with the default settings it sends no request to the APIs it finds. The one exception is the desktop-only Scan for APIs, which asks programs on your own computer for their public pages after you agree.

Before you begin

• Your licence includes the API Discovery add-on, or you are on a Trial.
• You can sign in with a role that has View API inventory. To add sources you also need Manage discovery sources.
• Open Discovery from the header. If you do not see the tab, open your account menu and tick Discovery under the header tabs. Each person chooses their own header tabs.

The Discovery tabs

A tab you are not allowed to open is not shown at all.

Step 1 — Choose a way in

An empty inventory offers these starting points:

• Scan for APIs looks at the computer you work on. Desktop app only. See Scan for APIs on this computer.
• Read what is already imported turns every specification already imported into a project into a source. Those operations arrive confirmed and already in their project.
• Add a source opens the setup wizard (Step 2).
• Try it with example data loads a made-up set of eight operations so you can see what each screen shows before you connect anything real. It is a sample, not a source of your own.

Step 2 — Add a source

Go to Sources, then Add a source. The wizard walks through six questions:

1. What to read. Each kind of source says what it reads and what it keeps before you choose it.
2. Name and environment. The environment is part of every operation's identity. The same path on staging and on production is two deployments of one service. Tick This is a production environment for production.
3. What it needs. A file to upload, an address to read, or the fields that kind of source asks for. Required fields are checked before you move on.
4. A secret, if any. Give either a reference to where the secret is kept or the secret itself. A pasted secret is sealed on the server and never shown again. A secret is never accepted inside an address or a field.
5. When it runs. Only when someone presses Run now, or every 1 to 720 hours. The default is every 24 hours.
6. Where it runs. On the server, or on an approved agent inside your network.

Select Create and run. Discovery creates the source, reads it, and shows what it found. The first run of a source is a baseline, so it does not report anything as new.

If a source cannot be read, for example because its address is on a private network the server may not reach, the wizard shows the reason on the step it belongs to. Your plan sets how many sources you can have. Adding one past the limit is refused, and the message names the limit.

What you can read

Bitbucket Data Center is not supported. These sources have been built and tested against recorded answers. They have not yet been validated against live Postman, GitHub, GitLab, SwaggerHub, Datadog, Splunk or Elasticsearch systems, so check the first run on your own setup.

Step 3 — Read an inventory row

Open Inventory. Every row carries these labels.

How sure we are it exists

Can it be tested? Ready to test or Not ready to test. A blocker can be a missing project, contract, environment or sign-in, an unsupported protocol, or a pending approval.

Specification says Specification, No specification or Specification not known.

Lifecycle is Active, Not seen lately, Missing from its sources or Retired. Being quiet for a while never retires an API on its own.

Quality evidence appears for rows that are already in a project. It shows chips for tests, security, mock and load, and it opens the API page.

Two switches help with a long list: Group by domain and Search by meaning. Search by meaning appears only when an embedding model is available, and otherwise search falls back to words and says why.

Rows that differ only by the name of a path parameter, such as /orders/{id} and /orders/{orderId}, are shown as one row.

Step 4 — Review what was found

Open Review to confirm or dismiss operations nobody has looked at. Your choices are Confirmed by a person, Dismissed and Suppressed. A dismissal always carries a reason. Operations that were never reviewed show Not reviewed.

Step 5 — Bring an API into a project

1. In Inventory, find the operation.
2. Select Accept into project… and choose the project.

Accepting hands the operation to the normal importer, so you get the same endpoints as from an import. No tests are created and nothing is sent to the API. For SOAP and GraphQL the whole stored WSDL or schema is imported.

gRPC, messaging, raw WebSocket, webhooks and AI realtime interfaces are kept as inventory only. They cannot be accepted into a project, and Shift-Left API does not test gRPC.

Add an API by hand

When nothing reports an API, select Add an API by hand. It joins the same inventory, is recorded in the audit log, and sends nothing to the API.

Step 6 — Watch for change

The Changes tab lists new, changed and missing operations, authentication changes, schema drift and sources that stopped reading well. Drift compares what is documented but never seen with what is seen but undocumented, and it states the time window it used.

A source that is stale, has an expired credential or is unhealthy is never read as "zero APIs". Two alert metrics exist for this: unhealthy_discovery_sources and open_discovery_changes.

For what a specification change touches, see Review a specification change.

Applications

An application is a named group of APIs that a person keeps, such as "the Payments app". Go to Applications to make one. Only a person makes one, and no AI is involved.

• It holds pointers, not copies. Deleting an application changes no API.
• It reads like "9 of 12 APIs have passing tests", then failing, not run lately, no tests and not in a project yet.
• An application holds up to 200 APIs, and a workspace holds up to 500 applications.
• After a capture of one application, Discovery can offer to make a group from it. Nothing is made until you accept.
• When an API changes, the change review names the applications that use it.

Making or changing an application needs Review discovered APIs. Reading one needs View API inventory.

Customer-side agents

An agent reads sources inside your network and sends only what the inventory needs. It only calls out, so nothing connects in. Go to Agents to approve one. In the desktop app, Offer this computer can start the installed Engine as an agent. A Studio install that talks to a cloud server cannot offer itself.

Agents prove who they are with a secret that you can rotate and revoke. Short-lived enrolment tokens and mutual TLS are not available. Discovery assumes one backend process, so do not plan a clustered Discovery.

Suggestions from AI

Discovery can suggest service names, owners, a business domain, a purpose and duplicates. Every suggestion is labelled as suggested and is never applied without a person. Duplicates are found by rules, not by a model. The suggestions need an AI provider or a local model that your organisation's AI policy allows. They have not been measured against a labelled set yet, so treat them as hints.

What is kept

Open the Discovery settings to set Keep evidence for (days), from 7 to 365 days. The default is 90 days. The inventory, specifications, change history and project links are kept until you remove them.

For a source you have two choices:

• Remove… stops the source and keeps what it found.
• Forget… erases what that source read. Evidence is deleted and removed from every row, and rows that no other source reports are deleted. It cannot be undone, and it is recorded in the audit log. Forgetting needs the add-on to be active.

When the add-on ends

The inventory stays readable and the assistant still answers. Every write is refused: no source runs, agents get no new work, and sources cannot be removed or forgotten. A licence change is picked up within 4 hours, or at once if you choose Refresh on the License page.

Source code

A repository source can also read routes out of code as text. It never runs, compiles or clones your code. Supported are Express, Fastify, NestJS, Spring (Java and Kotlin), ASP.NET Core, FastAPI, Flask, Django and Go projects.

• You tick a box on each source to confirm that it reads customer source code.
• APIs found this way show as Inferred, with the file and line as evidence, and stay No specification until a specification or traffic agrees.
• A route whose method or path is computed is counted as "not listed", with the reason. It is never invented.
• A run reads at most 300 files of up to 400 KB each.

Other languages and frameworks are not supported yet.

Not included

• Discovery does not generate tests from traffic.
• Pushes to a repository do not trigger an immediate read. Sources run on their schedule or when you press Run now.
• Reachability checks are not available from a screen.
• Discovery is not a live network sniffer. Only the opt-in desktop capture of calls on your own computer records anything.
• There is no overall score for an API or an inventory.

Troubleshooting

• The Discovery tab is missing. Tick it in your account menu. If the tab is still missing, your licence does not include the add-on.
• A source shows an error. Open Coverage to see what it could not read. Check the address, the credential and the environment.
• A row says Not ready to test. The row names every blocker. Most are a missing project, specification, environment or sign-in.
• An operation cannot be accepted. It is probably gRPC, messaging, a raw WebSocket, a webhook or an AI realtime interface.

Related articles

• Scan for APIs on this computer
• The API page: quality evidence for one API
• API dependencies
• Import and discover endpoints