{"slug": "introducing-orbit-turn-any-task-into-the-right-api-calls", "title": "Introducing Orbit: Turn Any Task Into the Right API Calls", "summary": "Postman.ai launched Orbit, a free API discovery service for AI agents available as an MCP server or REST API, designed to help agents find and integrate the right APIs on the first attempt. Orbit provides two tools—search and integrate—that return graded endpoints and step-by-step integration instructions, with no sign-up or configuration required. The service aims to reduce token usage and costs by enabling agents to select and implement APIs accurately.", "body_md": "# Introducing Orbit: Turn Any Task Into the Right API Calls\n\nAgents get their capabilities from APIs. That’s the premise behind [Postman.ai](https://blog.postman.com/introducing-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.\n\nSo 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.\n\nToday we’re launching [Orbit](https://www.buildwithorbit.ai/) 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.\n\n## Two tools, two questions\n\nOrbit gives your agent two tools, and they answer the two questions you’d put to a colleague who already knew the API landscape.\n\n“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`\n\n. 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.\n\nOnce you have the right API, the next obvious question is “How do I integrate this API?” That runs `integrate`\n\n. 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.\n\nSearch 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.\n\n## Two ways to use Orbit\n\nBoth tools are available two ways, and they expose exactly the same capability. Pick based on who is doing the calling.\n\n| MCP server | REST API | |\n|---|---|---|\n| Use it when | You work in a coding agent like Claude Code or Cursor | You’re building your own agent or backend |\n| Setup | One command | None, send a request |\n| You get | `search` and `integrate` as agent tools |\n`POST /v1/search` and `POST /v1/integrate` |\n| Auth | None | None |\n\n### Option 1: the MCP server\n\nFor coding agents, connect the server once:\n\n```\nclaude mcp add --transport http orbit https://mcp.buildwithorbit.ai/mcp\n```\n\nThat’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](https://modelcontextprotocol.io/) over streamable HTTP, so any MCP client can reach it, and the docs also list it at `https://www.buildwithorbit.ai/_mcp/server`\n\nfor clients other than [Claude Code](https://docs.claude.com/en/docs/claude-code/mcp).\n\nAfter that you talk to your agent normally, and it calls the tools for you:\n\n```\nFind an API that sends invoices.\n```\n\nThen:\n\n```\nIntegrate the PayPal ones so I can create a draft invoice and send it to a customer.\n```\n\nIf 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](#if-your-agent-doesnt-reach-for-orbit-on-its-own) at the end of this post that fixes it.\n\n### Option 2: the REST API\n\nIf you’re building your own agent, skip MCP and call the two endpoints yourself. The base URL is `https://api.buildwithorbit.ai`\n\n, the content type is JSON, and there’s no auth.\n\n```\ncurl -s -X POST \"https://api.buildwithorbit.ai/v1/search?limit=6\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"q\": \"send an invoice to a customer with PayPal\"}'\n```\n\nEach result carries an `id`\n\n, `method`\n\n, `url`\n\n, and `evaluateGuide`\n\n. Treat the `id`\n\nas opaque, pass it back verbatim, and don’t parse or construct it:\n\n```\n{\n  \"data\": [\n    {\n      \"resourceType\": \"endpoint\",\n      \"id\": \"urn:orbit:endpoint:v1:1I63l4CEzQrXTBUYglUqCVt93MWk2gTAsdJpLE2JiU3uS5rjEary7fx0vxlV1:paypal:send-invoice\",\n      \"name\": \"Send invoice\",\n      \"method\": \"POST\",\n      \"url\": \"https://api-m.sandbox.paypal.com/v2/invoicing/invoices/:invoice_id/send\",\n      \"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\",\n      \"provider\": \"PayPal\",\n      \"product\": \"PayPal\"\n    }\n  ]\n}\n```\n\nThat `evaluateGuide`\n\nis 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.\n\nThen send the `id`\n\nand its `resourceType`\n\nto `/v1/integrate`\n\nalong with your task:\n\n```\ncurl -s -X POST \"https://api.buildwithorbit.ai/v1/integrate\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"task\": \"Create a draft invoice and send it to a customer\",\n    \"resources\": [\n      {\"id\": \"urn:orbit:endpoint:v1:...paypal:create-draft-invoice\", \"type\": \"endpoint\"},\n      {\"id\": \"urn:orbit:endpoint:v1:...paypal:send-invoice\", \"type\": \"endpoint\"}\n    ]\n  }'\n```\n\nWhat comes back is a task brief. This is a real response, trimmed to its structure:\n\n```\nCreate and send a PayPal draft invoice to a customer (PayPal Invoicing API)\n\nFIT\nFully. The first request creates a draft invoice and returns its ID, and the\nsecond sends that invoice to the customer.\n\nAUTH\nHeader: Authorization: Bearer <access_token>\n\nSTEPS\n1. POST /v2/invoicing/invoices\n   Returns 201 with id (example 'INV2-TKNW-LEZX-7NEF-Q4V2'), status 'DRAFT'.\n   Threading: None\n\n2. POST /v2/invoicing/invoices/{invoice_id}/send\n   Returns 202 with a payer-view link.\n   Threading: invoice_id from step 1\n```\n\nThe `Threading`\n\nline 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.\n\nA few limits worth knowing before you wire this into a loop:\n\n| Detail | Value |\n|---|---|\n`q` and `task` length |\n512 characters maximum |\n`limit` on search |\nDefault 10, maximum 25 |\n| Pagination | 40 results maximum. Pass the `meta.nextCursor` value from a response back as the `cursor` query parameter; omit it for the first page |\n| Endpoints per integrate call | Up to 10 |\n| Error codes | `400` invalid input, `429` rate limited, `500` server error, plus `404` on integrate when no IDs resolve |\n\nThe [OpenAPI specification](https://www.buildwithorbit.ai/openapi.json) is the complete reference — every query parameter, the full result and `meta`\n\nschemas, and each error response. It’s small enough to hand to an agent whole.\n\nBoth 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`\n\nwith exponential delay per the [HTTP semantics specification](https://www.rfc-editor.org/rfc/rfc9110.html#name-429-too-many-requests). One more thing: `integrate`\n\ngenerates prose, so identical requests can return differently worded briefs. Parse the brief with your agent instead of writing a string-matching test against it.\n\n## About twenty seconds, and 27x less context\n\nTwo 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.\n\nThe invoice example above takes about 17 seconds end to end: roughly 6s for `search`\n\n, roughly 11s for `integrate`\n\n. That’s a typical result rather than a lucky one. Measured across 16 different tasks — geocoding, SMS, refunds, transcription, flight lookup — the median `search`\n\nreturned in 7.6s and the median `integrate`\n\nin 9.2s, which puts the pair at 15 to 20 seconds for most tasks.\n\nSo budget about twenty seconds. The fastest pair we measured was 10.9s and the slowest 23.6s, and `integrate`\n\naccounts for nearly all of that spread because it writes prose rather than looking up rows; `search`\n\nstays 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.\n\nFor agents, cost is context, and the comparison is stark:\n\n| What your agent reads | Size | Approximate tokens |\n|---|---|---|\n| Orbit search response (6 endpoints, each evaluated) | 6,096 characters | ~1,500 |\n| Orbit task brief | 4,035 characters | ~1,000 |\nOrbit total |\n10,131 characters |\n~2,500 |\n|\n\n[PayPal’s Invoicing v2 documentation page](https://developer.paypal.com/docs/api/invoicing/v2/), 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.\n\nThe 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>`\n\ntags 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.\n\nReproduce the counts yourself. `wc -c`\n\nreports bytes, so what comes back is characters, not tokens:\n\n```\n# Orbit: the search response, then the brief for two PayPal endpoints it returned\ncurl -s -X POST \"https://api.buildwithorbit.ai/v1/search?limit=6\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"q\": \"send an invoice to a customer with PayPal\"}' -o orbit-search.json\n\ncurl -s -X POST \"https://api.buildwithorbit.ai/v1/integrate\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"task\": \"Create a draft invoice and send it to a customer\",\n       \"resources\": [\n         {\"id\": \"urn:orbit:endpoint:v1:...paypal:create-draft-invoice\", \"type\": \"endpoint\"},\n         {\"id\": \"urn:orbit:endpoint:v1:...paypal:send-invoice\", \"type\": \"endpoint\"}\n       ]}' -o orbit-brief.json\n\n# What your agent would read instead, straight from PayPal\ncurl -sL \"https://raw.githubusercontent.com/paypal/paypal-rest-api-specifications/main/openapi/invoicing_v2.json\" -o paypal-spec.json\ncurl -sL \"https://developer.paypal.com/docs/api/invoicing/v2/\" -o paypal-docs.html\n\n# characters, not tokens\nwc -c orbit-search.json orbit-brief.json paypal-spec.json paypal-docs.html\n6065 orbit-search.json\n    4141 orbit-brief.json\n  276617 paypal-spec.json\n  180724 paypal-docs.html\n  467547 total\n```\n\nThe 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.\n\nFewer 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.\n\nOrbit itself adds nothing to the bill. It’s free and there’s no metered tier, which you can confirm from the [OpenAPI specification](https://www.buildwithorbit.ai/openapi.json): it declares no security schemes at all, so there’s no key to bill against.\n\n## We built it to tell you no\n\nEvery task brief opens with a `FIT`\n\nverdict, 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.\n\nTake 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\"`\n\n:\n\n```\nFIT\n  Fully. The supplied request validates and standardizes a U.S. street address\n  and returns latitude and longitude when a candidate matches.\n```\n\nNow add a clause that endpoint can’t satisfy — `\"task\": \"Geocode a street address and email the coordinates to a customer\"`\n\n— and send the very same endpoint again:\n\n```\nFIT\n  Partially. The supplied request can validate and standardize the address and\n  return latitude/longitude, but no supplied request sends an email to a\n  customer. The request serves the address-geocoding portion of the task; email\n  the returned coordinates through a separate email service or endpoint.\n```\n\nSame 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.\n\nSo read `FIT`\n\nbefore you write anything. “Fully” means go. “Partially” means you’re one endpoint short, and the brief just told you which one.\n\n## Built on the Postman API Network\n\nOrbit reads from the public API corpus behind the [Postman API Network](https://www.postman.com/explore). 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.\n\nAnd because Orbit works entirely with publicly available APIs, there’s nothing private to connect and no catalog to populate before your agent starts looking.\n\n## Start building\n\nConnect the server to your coding agent:\n\n```\nclaude mcp add --transport http orbit https://mcp.buildwithorbit.ai/mcp\n```\n\nThat’s the only setup step. Now pick something you’ve been putting off and ask for it in two turns:\n\n```\nFind an API that can geocode a street address.\nIntegrate that one and write the request for me.\n```\n\nStop and read the candidates before you send the second prompt. That pause is the point of the split — the endpoint choice stays yours, and `FIT`\n\nwill tell you if the job actually needs more than one endpoint.\n\nBuilding your own agent rather than working inside one? Skip MCP and call [the two REST endpoints](#option-2-the-rest-api) directly. Same two steps in the same order, still no auth.\n\n[Every documentation page](https://www.buildwithorbit.ai/docs/get-started/welcome) serves clean Markdown when you append `.md`\n\nto the URL, and [llms.txt](https://www.buildwithorbit.ai/llms.txt) indexes the whole set, so point your agent at those rather than scraping HTML.\n\nOrbit is live now at [buildwithorbit.ai](https://www.buildwithorbit.ai/). It’s free, and it takes one command.\n\n## If your agent doesn’t reach for Orbit on its own\n\nAgents 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.\n\nIf yours does that, install a [Claude Code skill](https://docs.claude.com/en/docs/claude-code/skills) that tells it when to reach for Orbit. Save this as `.claude/skills/find-an-api/SKILL.md`\n\nin your project, or in `~/.claude/skills/find-an-api/SKILL.md`\n\nto get it everywhere:\n\n```\n---\nname: find-an-api\ndescription: 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.\nallowed-tools: [\"mcp__orbit__search\", \"mcp__orbit__integrate\", \"Read\", \"Write\", \"Edit\"]\n---\n\n# Find and integrate a public API\n\nDo not write third-party API integration code from memory. Endpoint paths, auth\nheader names, and required fields are exactly the details that get misremembered,\nand the failure arrives as a 400 at runtime instead of an error at author time.\nGet them from Orbit, which reads real request schemas.\n\nRun this flow whenever the task needs an API the project doesn't already call.\nThe user does not have to ask for Orbit by name.\n\n## Step 1: Search\n\nCall `search` with a plain-language description of the task, not a provider name.\n\n- Good: `send an invoice to a customer`\n- Worse: `PayPal`\n\nRead the `evaluateGuide` on every result before choosing. It has three parts:\nwhat the endpoint does, what to use it for, and what it does not support. That\nlast part is what stops you picking an endpoint that looks right and isn't.\n\n## Step 2: Show the candidates before choosing\n\nPresent a short table of the top results with provider, method, path, and the\none-line summary, then ask which to use. Do not pick silently. Endpoint selection\nis the decision most worth a human glance, and the \"Not supported\" clause often\nrules out the obvious first choice.\n\nIf no single endpoint can finish the task, say so and propose the set. Sending an\ninvoice, for example, requires creating one first.\n\n## Step 3: Integrate\n\nCall `integrate` once with the task description and every endpoint the task needs,\nup to 10. Pass each result's `id` verbatim and its `resourceType` as `type`. Never\nconstruct, shorten, or edit an `id`.\n\nRead the returned task brief before writing code, and respect these fields:\n\n- `FIT`: anything other than \"Fully\" means something is missing. Say what, before\n  you start. \"Partially\" usually means state, a trigger, or a value the schemas\n  don't connect.\n- `AUTH`: use the exact header name given. It is frequently not `Authorization`.\n- `Threading`: the data dependency between steps. If step 2 threads a value from\n  step 1, sequence the calls and pass that value through.\n- `GOTCHAS`: read every line. Content type, ordering, and idempotency traps live\n  here.\n\nThe brief is generated prose, so the wording changes between identical calls. Read\nit as context; never write a string-matching test against it.\n\n## Step 4: Write the code\n\nFollow the brief over your priors. Match the project's existing HTTP client and\nerror handling. Keep credentials in environment variables, never inline.\n\nIf the brief names a credential the user doesn't have yet, stop and tell them\nwhich one to get and which scope it needs.\n```\n\nThe `allowed-tools`\n\nnames follow the alias you used in `claude mcp add`\n\n, so keep it as `orbit`\n\nor adjust them to match. You can also delete that line entirely and the skill will inherit your usual tools.\n\n## Resources\n\n[Orbit documentation](https://www.buildwithorbit.ai/docs/get-started/welcome)[Orbit usage guide and MCP setup](https://www.buildwithorbit.ai/docs/get-started/usage-guide)[Search public endpoints reference](https://www.buildwithorbit.ai/api-reference/search-public-endpoints)[Integrate public endpoints reference](https://www.buildwithorbit.ai/api-reference/integrate-public-endpoints)[Orbit OpenAPI specification](https://www.buildwithorbit.ai/openapi.json)[Model Context Protocol specification](https://modelcontextprotocol.io/specification/2025-06-18)[Postman API Network](https://www.postman.com/explore)[Postman Docs: MCP servers](https://learning.postman.com/docs/postman-ai/mcp-servers/overview/)[Postman Vault secrets](https://learning.postman.com/docs/sending-requests/postman-vault/postman-vault-secrets/)[Introducing Postman.ai](https://blog.postman.com/introducing-postman-ai/)", "url": "https://wpnews.pro/news/introducing-orbit-turn-any-task-into-the-right-api-calls", "canonical_source": "https://blog.postman.com/introducing-orbit-turn-any-task-into-the-right-api-calls/", "published_at": "2026-08-27 16:00:00+00:00", "updated_at": "2026-08-27 16:50:13.398773+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools"], "entities": ["Postman.ai", "Orbit", "Claude Code", "Cursor", "Model Context Protocol"], "alternates": {"html": "https://wpnews.pro/news/introducing-orbit-turn-any-task-into-the-right-api-calls", "markdown": "https://wpnews.pro/news/introducing-orbit-turn-any-task-into-the-right-api-calls.md", "text": "https://wpnews.pro/news/introducing-orbit-turn-any-task-into-the-right-api-calls.txt", "jsonld": "https://wpnews.pro/news/introducing-orbit-turn-any-task-into-the-right-api-calls.jsonld"}}