Agents get their capabilities from APIs. That’s the premise behind Postman.ai, and the reason we expect agents to become the primary consumers of APIs. An agent that can reach the right API can send the invoice, pull the customer record, or page the on-call engineer. An agent that can’t is a chat window.
So the interesting question stopped being whether agents can call APIs. They can. The question is how they find the right one and integrate it correctly on the first attempt. Why? So the right outcome is achieved faster, the tokens spent are fewer, and your costs are lower.
Today we’re launching Orbit to close that gap. It’s API discovery for AI agents, available as an MCP server or a REST API, and it’s free with nothing to sign up for or configure.
Two tools, two questions #
Orbit gives your agent two tools, and they answer the two questions you’d put to a colleague who already knew the API landscape.
“Which API can do this?” This is a common question everyone — humans and agents alike — runs into when building an app. This will run search
. You describe the task in plain language and get back public endpoints that can do it, each one graded on how well it matches, including what it explicitly cannot do.
Once you have the right API, the next obvious question is “How do I integrate this API?” That runs integrate
. You pick the endpoint that fits and get back a task brief: the auth scheme, the base URL, the numbered request steps with real parameter names, the response codes to expect, the dependencies between steps, and the gotchas that usually surface as your first 400.
Search narrows the field and grades what it finds. Integrate turns your pick into instructions specific enough to write code against. Splitting it across two turns is deliberate, because choosing the endpoint is precisely the decision an agent working from memory gets wrong, and it’s the one worth keeping in your hands.
Two ways to use Orbit #
Both tools are available two ways, and they expose exactly the same capability. Pick based on who is doing the calling.
| MCP server | REST API | |
|---|---|---|
| Use it when | You work in a coding agent like Claude Code or Cursor | You’re building your own agent or backend |
| Setup | One command | None, send a request |
| You get | search and integrate as agent tools |
|
POST /v1/search and POST /v1/integrate |
||
| Auth | None | None |
Option 1: the MCP server
For coding agents, connect the server once:
claude mcp add --transport http orbit https://mcp.buildwithorbit.ai/mcp
That’s the entire setup. There’s no API key to obtain and no OAuth round trip to sit through. The server speaks Model Context Protocol over streamable HTTP, so any MCP client can reach it, and the docs also list it at https://www.buildwithorbit.ai/_mcp/server
for clients other than Claude Code.
After that you talk to your agent normally, and it calls the tools for you:
Find an API that sends invoices.
Then:
Integrate the PayPal ones so I can create a draft invoice and send it to a customer.
If your agent doesn’t reach for Orbit on its own when you ask it to add a capability, there’s a skill you can install at the end of this post that fixes it.
Option 2: the REST API
If you’re building your own agent, skip MCP and call the two endpoints yourself. The base URL is https://api.buildwithorbit.ai
, the content type is JSON, and there’s no auth.
curl -s -X POST "https://api.buildwithorbit.ai/v1/search?limit=6" \
-H "Content-Type: application/json" \
-d '{"q": "send an invoice to a customer with PayPal"}'
Each result carries an id
, method
, url
, and evaluateGuide
. Treat the id
as opaque, pass it back verbatim, and don’t parse or construct it:
{
"data": [
{
"resourceType": "endpoint",
"id": "urn:orbit:endpoint:v1:1I63l4CEzQrXTBUYglUqCVt93MWk2gTAsdJpLE2JiU3uS5rjEary7fx0vxlV1:paypal:send-invoice",
"name": "Send invoice",
"method": "POST",
"url": "https://api-m.sandbox.paypal.com/v2/invoicing/invoices/:invoice_id/send",
"evaluateGuide": "Sends an invoice immediately or schedules it according to the invoice issue date. The payload can control recipient and merchant notifications.\nUse for: send invoice, schedule invoice delivery, notify customer\nNot supported: creating invoices, editing invoice details, recording payment",
"provider": "PayPal",
"product": "PayPal"
}
]
}
That evaluateGuide
is worth reading closely. This endpoint sends an invoice but explicitly does not create one, so a task that starts from nothing needs two endpoints rather than one.
Then send the id
and its resourceType
to /v1/integrate
along with your task:
curl -s -X POST "https://api.buildwithorbit.ai/v1/integrate" \
-H "Content-Type: application/json" \
-d '{
"task": "Create a draft invoice and send it to a customer",
"resources": [
{"id": "urn:orbit:endpoint:v1:...paypal:create-draft-invoice", "type": "endpoint"},
{"id": "urn:orbit:endpoint:v1:...paypal:send-invoice", "type": "endpoint"}
]
}'
What comes back is a task brief. This is a real response, trimmed to its structure:
Create and send a PayPal draft invoice to a customer (PayPal Invoicing API)
FIT
Fully. The first request creates a draft invoice and returns its ID, and the
second sends that invoice to the customer.
AUTH
Header: Authorization: Bearer <access_token>
STEPS
1. POST /v2/invoicing/invoices
Returns 201 with id (example 'INV2-TKNW-LEZX-7NEF-Q4V2'), status 'DRAFT'.
Threading: None
2. POST /v2/invoicing/invoices/{invoice_id}/send
Returns 202 with a payer-view link.
Threading: invoice_id from step 1
The Threading
line is the one to notice. Step 1 returns an invoice ID and step 2 needs it as a path variable, so the brief states the dependency rather than leaving your agent to infer it. The full response also carries every body parameter with an example value, the required headers, and the 401 you get from a bad token.
A few limits worth knowing before you wire this into a loop:
| Detail | Value |
|---|---|
q and task length |
|
| 512 characters maximum | |
limit on search |
|
| Default 10, maximum 25 | |
| Pagination | 40 results maximum. Pass the meta.nextCursor value from a response back as the cursor query parameter; omit it for the first page |
| Endpoints per integrate call | Up to 10 |
| Error codes | 400 invalid input, 429 rate limited, 500 server error, plus 404 on integrate when no IDs resolve |
The OpenAPI specification is the complete reference — every query parameter, the full result and meta
schemas, and each error response. It’s small enough to hand to an agent whole.
Both endpoints are read-only, so retries are safe and no idempotency key is required. Free and unauthenticated doesn’t mean unlimited, so back off on 429
with exponential delay per the HTTP semantics specification. One more thing: integrate
generates prose, so identical requests can return differently worded briefs. Parse the brief with your agent instead of writing a string-matching test against it.
About twenty seconds, and 27x less context #
Two costs decide whether a discovery tool earns a place in your agent’s loop: how long it makes you wait, and what it does to your token bill.
The invoice example above takes about 17 seconds end to end: roughly 6s for search
, roughly 11s for integrate
. That’s a typical result rather than a lucky one. Measured across 16 different tasks — geocoding, SMS, refunds, transcription, flight lookup — the median search
returned in 7.6s and the median integrate
in 9.2s, which puts the pair at 15 to 20 seconds for most tasks.
So budget about twenty seconds. The fastest pair we measured was 10.9s and the slowest 23.6s, and integrate
accounts for nearly all of that spread because it writes prose rather than looking up rows; search
stays in a tight 6.5–9.9s band. These are client-side timings from a single location on a free tier, so treat them as the shape of the curve rather than a guarantee, and expect your own network to add to them. The path it replaces is finding a provider, reading the reference, working out the auth scheme, discovering that you can’t send an invoice you haven’t created, and still collecting a 400 or two before the first call succeeds.
For agents, cost is context, and the comparison is stark:
| What your agent reads | Size | Approximate tokens |
|---|---|---|
| Orbit search response (6 endpoints, each evaluated) | 6,096 characters | ~1,500 |
| Orbit task brief | 4,035 characters | ~1,000 |
| Orbit total | ||
| 10,131 characters | ||
| ~2,500 | ||
PayPal’s Invoicing v2 documentation page, fetched as HTMLThat’s roughly 27 times less context to answer the same questions, and the specification is the charitable comparison. It’s the clean machine-readable artifact.
The documentation page is the uncharitable one, and it’s worse than its size suggests. Fetching that URL returns 180 KB of HTML, but 60% of it is <script>
tags and only about 3,500 characters are readable text. The field-level reference an agent actually needs — parameter names, required flags, enum values — renders client-side and never arrives. So an agent that reaches for the human docs pays 45,000 tokens and still can’t tell you what to put in the request body. Token counts are estimated at four characters per token, so treat the ratios as an order of magnitude rather than precise figures.
Reproduce the counts yourself. wc -c
reports bytes, so what comes back is characters, not tokens:
curl -s -X POST "https://api.buildwithorbit.ai/v1/search?limit=6" \
-H "Content-Type: application/json" \
-d '{"q": "send an invoice to a customer with PayPal"}' -o orbit-search.json
curl -s -X POST "https://api.buildwithorbit.ai/v1/integrate" \
-H "Content-Type: application/json" \
-d '{"task": "Create a draft invoice and send it to a customer",
"resources": [
{"id": "urn:orbit:endpoint:v1:...paypal:create-draft-invoice", "type": "endpoint"},
{"id": "urn:orbit:endpoint:v1:...paypal:send-invoice", "type": "endpoint"}
]}' -o orbit-brief.json
curl -sL "https://raw.githubusercontent.com/paypal/paypal-rest-api-specifications/main/openapi/invoicing_v2.json" -o paypal-spec.json
curl -sL "https://developer.paypal.com/docs/api/invoicing/v2/" -o paypal-docs.html
wc -c orbit-search.json orbit-brief.json paypal-spec.json paypal-docs.html
6065 orbit-search.json
4141 orbit-brief.json
276617 paypal-spec.json
180724 paypal-docs.html
467547 total
The two PayPal artifacts are byte-stable, so they land on those figures every time. Orbit’s two drift by a few hundred characters per call, because the result set and the generated prose differ on every run. This run put the Orbit pair at 10,206 characters — about 2,600 tokens — against the specification’s 276,617, or roughly 69,000. That ratio is the 27x above.
Fewer tokens is not only cheaper. It’s faster, because time to first token scales with prompt size, and it’s more accurate, because an agent that loads a 69,000-token specification still has to locate the create-then-send dependency inside it. Orbit already did that and put it on one line.
Orbit itself adds nothing to the bill. It’s free and there’s no metered tier, which you can confirm from the OpenAPI specification: it declares no security schemes at all, so there’s no key to bill against.
We built it to tell you no #
Every task brief opens with a FIT
verdict, and that line is the part we care most about. A discovery tool that always finds something is worse than useless. It’s confidently wrong.
Take a single geocoding endpoint — one that validates a U.S. street address and returns coordinates. Send it a task it fully covers, "task": "Geocode a street address"
:
FIT
Fully. The supplied request validates and standardizes a U.S. street address
and returns latitude and longitude when a candidate matches.
Now add a clause that endpoint can’t satisfy — "task": "Geocode a street address and email the coordinates to a customer"
— and send the very same endpoint again:
FIT
Partially. The supplied request can validate and standardize the address and
return latitude/longitude, but no supplied request sends an email to a
customer. The request serves the address-geocoding portion of the task; email
the returned coordinates through a separate email service or endpoint.
Same endpoint, one extra clause in the task, and the verdict flips. That’s the whole feature. Orbit doesn’t pad the gap with a plausible-looking email call it doesn’t have, and it doesn’t quietly drop the half of your request it can’t cover. It names which part it can do, which part it can’t, and what to go find.
So read FIT
before you write anything. “Fully” means go. “Partially” means you’re one endpoint short, and the brief just told you which one.
Built on the Postman API Network #
Orbit reads from the public API corpus behind the Postman API Network. That’s why the PayPal brief earlier could name the exact auth header to send, and knew that step two needs the invoice ID step one returns. Those details aren’t inferred from prose documentation. They come from request schemas, saved response examples, and auth settings that real developers configured and ran against live endpoints.
And because Orbit works entirely with publicly available APIs, there’s nothing private to connect and no catalog to populate before your agent starts looking.
Start building #
Connect the server to your coding agent:
claude mcp add --transport http orbit https://mcp.buildwithorbit.ai/mcp
That’s the only setup step. Now pick something you’ve been putting off and ask for it in two turns:
Find an API that can geocode a street address.
Integrate that one and write the request for me.
Stop and read the candidates before you send the second prompt. That is the point of the split — the endpoint choice stays yours, and FIT
will tell you if the job actually needs more than one endpoint.
Building your own agent rather than working inside one? Skip MCP and call the two REST endpoints directly. Same two steps in the same order, still no auth.
Every documentation page serves clean Markdown when you append .md
to the URL, and llms.txt indexes the whole set, so point your agent at those rather than scraping HTML.
Orbit is live now at buildwithorbit.ai. It’s free, and it takes one command.
If your agent doesn’t reach for Orbit on its own #
Agents choose tools from the descriptions they can see, and one with dozens of tools connected won’t reliably pick Orbit when you ask it to “add invoicing to this app.” It’ll start writing code from memory instead, which is the failure mode Orbit exists to prevent.
If yours does that, install a Claude Code skill that tells it when to reach for Orbit. Save this as .claude/skills/find-an-api/SKILL.md
in your project, or in ~/.claude/skills/find-an-api/SKILL.md
to get it everywhere:
---
name: find-an-api
description: Find and integrate a public API using the Orbit MCP server. Use whenever the user wants to add a third-party capability (send an invoice, charge a card, send email, geocode an address, post to Slack) and no endpoint has been chosen yet, or when they name a provider but the request shape is unknown. Search Orbit before writing any integration code from memory, even when the user does not mention Orbit.
allowed-tools: ["mcp__orbit__search", "mcp__orbit__integrate", "Read", "Write", "Edit"]
---
Do not write third-party API integration code from memory. Endpoint paths, auth
header names, and required fields are exactly the details that get misremembered,
and the failure arrives as a 400 at runtime instead of an error at author time.
Get them from Orbit, which reads real request schemas.
Run this flow whenever the task needs an API the project doesn't already call.
The user does not have to ask for Orbit by name.
## Step 1: Search
Call `search` with a plain-language description of the task, not a provider name.
- Good: `send an invoice to a customer`
- Worse: `PayPal`
Read the `evaluateGuide` on every result before choosing. It has three parts:
what the endpoint does, what to use it for, and what it does not support. That
last part is what stops you picking an endpoint that looks right and isn't.
## Step 2: Show the candidates before choosing
Present a short table of the top results with provider, method, path, and the
one-line summary, then ask which to use. Do not pick silently. Endpoint selection
is the decision most worth a human glance, and the "Not supported" clause often
rules out the obvious first choice.
If no single endpoint can finish the task, say so and propose the set. Sending an
invoice, for example, requires creating one first.
## Step 3: Integrate
Call `integrate` once with the task description and every endpoint the task needs,
up to 10. Pass each result's `id` verbatim and its `resourceType` as `type`. Never
construct, shorten, or edit an `id`.
Read the returned task brief before writing code, and respect these fields:
- `FIT`: anything other than "Fully" means something is missing. Say what, before
you start. "Partially" usually means state, a trigger, or a value the schemas
don't connect.
- `AUTH`: use the exact header name given. It is frequently not `Authorization`.
- `Threading`: the data dependency between steps. If step 2 threads a value from
step 1, sequence the calls and pass that value through.
- `GOTCHAS`: read every line. Content type, ordering, and idempotency traps live
here.
The brief is generated prose, so the wording changes between identical calls. Read
it as context; never write a string-matching test against it.
## Step 4: Write the code
Follow the brief over your priors. Match the project's existing HTTP client and
error handling. Keep credentials in environment variables, never inline.
If the brief names a credential the user doesn't have yet, stop and tell them
which one to get and which scope it needs.
The allowed-tools
names follow the alias you used in claude mcp add
, so keep it as orbit
or adjust them to match. You can also delete that line entirely and the skill will inherit your usual tools.
Resources #
Orbit documentationOrbit usage guide and MCP setupSearch public endpoints referenceIntegrate public endpoints referenceOrbit OpenAPI specificationModel Context Protocol specificationPostman API NetworkPostman Docs: MCP serversPostman Vault secretsIntroducing Postman.ai