Discover the APIs an agent will call before you build

The agent project has a kickoff date and a model picked out. In week three someone asks which service returns the order status the bot is supposed to quote. The architecture diagram shows a box labeled Orders. The box has no owner, no OpenAPI file, and a base URL that only works on one VPN. The public registry search returns nothing under that name. The project stops there, not on the prompt.

This post is how you find that surface before you write the agent: what a registry search can see, and what only your own logs can see.

Start from calls you already make

An agent can only call an API you can name. Naming starts with evidence, not with a whiteboard. Pull a week of outbound calls from the gateway, the service mesh, or the HTTP client logs in the repo that does this job today. Group them by host and path. You want the list a person would have to click through to answer the same question the agent will answer.

Three places usually hold the truth when the wiki is stale:

• The gateway or mesh access log, grouped by host
• fetch, axios, or HttpClient usages in the repo that owns the workflow
• The on-call channel, where people paste the curl that still works

If a host shows up in the log and in nobody's catalog, that is the shadow API. Write the host, the method, and who last changed the client. That row is the scope. A model cannot discover it by guessing a URL. Anything that returns customer fields still has to pass the checklist before company data before you enable it.

What a registry search returns

swy search looks at the remote registry. swy discover searches integrations you already downloaded. Neither one crawls your VPC. If the order service is an internal app with no public bundle, search returns nothing. That empty result is correct. It is not a broken command.

swy search <name>
swy discover "<description>"
swy get <name from swy search>
swy list methods

Use the name search actually printed. swy get downloads the bundle and does not enable tools. swy list methods shows what is local. swy add is a later decision, after you know the call is in scope. The integrations CLI docs describe search, get, and bootstrap. Do not treat a download as permission to run every method in the bundle.

When search is empty, you have an internal service to document or a provider the registry does not carry. Business and Enterprise can bring your own provider. That is a build, with an owner and a schema, not a flag you flip on Friday. Free and Pro stay on what the registry already has. Say that in the kickoff so the date does not assume a bundle that is not there.

Write the inventory before anyone opens an editor

A useful inventory is short. One row per operation the agent might need, not one row per vendor.

The registry column is a fact you just checked, not a hope. The owner column is a person. A row with no owner does not go into the agent. You will not get a policy reviewed for a service nobody admits to running.

API governance tools are where this list should land once it is real. A gateway catalog that was last edited two years ago will not mention the shadow host. Update it from the log, or keep the table in the repo next to tooling.json so the agent scope and the gateway catalog can be compared in one pull request.

Cut the list to what the first release answers

Discovery finds more operations than the first release should enable. Keep the ones required to answer the question you sold. Park the rest as "known, not in v1." An undocumented write is a reason to delay, not a reason to let the model try the path and see what happens.

If the status call depends on a shadow host, name that host and find an owner. Then wrap it as your own provider, or change the product so the agent does not need it. Prompt work does not remove the dependency.

Run swy search for every public provider on the list, and build the internal rows from logs before you schedule the build. An empty search on an internal host means the scope is still open.

Related reading

• API compliance for agent integrations. What to attach once a row has an owner.
• Policy as code for agent calls. Where an operation goes after you decide it is in v1.
• Human approval for a tool call. What a write on that list needs before it can wait for a person.
• Log every API call an agent makes. How you confirm the agent stayed on the rows you allowed.

FAQ

Will swy search find an internal service that has no public docs?

No. swy search queries the remote registry. swy discover only sees bundles you already downloaded. An internal host shows up in your logs, not in that search.

What should I do when the registry has the provider but not the one path I need?

Copy the method list from swy list methods and mark the path missing. Do not invent an ID. If the path is required, treat it like a missing provider and scope a bring-your-own provider on Business or Enterprise, or cut it from v1.

Is a gateway catalog enough as the inventory?

Only if someone updated it from traffic. Compare it to a week of access logs. Hosts in the log and absent from the catalog are the ones that stall the agent later.

Can I point the agent at the base URL from the log and skip the inventory?

You can, and the first person to review it will stop the launch. A base URL without an owner, a method list, and a read or write label is not a scope. It is the stall you already have, moved into production.