Make your API agent-ready

An AI agent reads your actions once, picks one, fills in the inputs and acts on the answer. It can’t read your docs site, ask a colleague or try things out the way a developer does. So the small gaps people work around without noticing become dead ends for agents.

We found the common ones by connecting public APIs to real AI apps and asking ordinary questions. This page lists them, what Gephyr does about each one automatically, and what you can do in your API docs to help. Most of it takes minutes.

Inputs agents can’t fill in

What goes wrong. An input called provider or filter, with no description, leaves the agent guessing. It sends “Google” when your API wants googleapis.com, and the call fails.

What Gephyr does.

Each input keeps its description from your docs, and the example value if your docs give one (“Example: googleapis.com”).
On import, every input’s description is tidied into plain words, and Gephyr AI rewrites the ones that are missing, unclear or written for developers, saying what goes there and in what form, using only what your docs show. Any rule your docs give for an input is kept. Once imported, the descriptions are yours: edit any of them on the Actions tab.
Types, allowed values (enums) and ranges (minimum, maximum) from your docs are checked before your API is called, so the agent hears “latitude: 200 is greater than 90” straight away.

What you can do. Give every parameter a one-line description and an example. List allowed values as an enum, and give numbers a minimum and maximum. You can also edit any input in the action editor on the Actions tab.

Rules hidden in your docs

What goes wrong. Some endpoints only give a useful answer if the request follows a rule, like “ask for at least one of these fields” or “dates at most 31 days apart”. If the agent doesn’t know the rule, it gets an empty answer and can’t tell why.

What Gephyr does. On import, Gephyr AI keeps rules like these in the action’s description. If it leaves one out, Gephyr adds the sentence back from your docs. The same happens when Gephyr AI suggests a clearer description later.

What you can do. Put each rule in one plain sentence in the endpoint’s description: “You must set at least one of daily, hourly or current.” If there’s a sensible default, set it as the parameter’s default. Gephyr sends it when the agent leaves the input out.

Errors that don’t say what to fix

What goes wrong. “400 Bad Request” tells an agent nothing. It tries the same thing again, or gives up.

What Gephyr does. When your API refuses a call (a 4xx other than 401), the agent gets your API’s own reason: “Upstream returned 400. The API said: “Invalid timezone”“. A 404 with no reason tells the agent nothing was found for what it sent, and to check ids and names against an action that lists them. Sign-in failures, server errors and HTML error pages give the agent the status only, so stack traces and sign-in details never reach it. After a server error or a timeout the agent is told to try a look-up once more, and to check a change before repeating it. See When your API refuses a call.

What you can do. Return 4xx errors as JSON with a message written for the person fixing the request: what was wrong and what’s allowed. Leave internal details out of 4xx messages.

Answers that are too big

What goes wrong. An endpoint that returns everything, like every record or a whole catalogue, can be megabytes. Agents work best with a page of results.

What Gephyr does. Lists are cut to fit (40,000 characters by default) and the agent is told how much it saw and how to get the rest. Paging gives every list limit and cursor inputs, whatever your API does underneath. An answer over 1 MB is never passed on. After a look-up, the agent is told to ask for less; after a change, it’s told the change may already have been made and to check before doing it again. See What agents get back.

What you can do. Turn on paging for list actions, hide fields agents don’t need, and switch off actions that only return everything at once.

Changes that might happen twice

What goes wrong. If a change times out or the answer is lost, an agent may simply try again, and book the class twice.

What Gephyr does. A 10-second duplicate guard stops the same change being sent twice in a row. Actions set to Ask first are single-use: a retry after success gets the first result back rather than running again, and if Gephyr can’t tell whether a change happened, it says so and never repeats it on its own. See How Confirm works.

What you can do. Set anything involving money, cancelling, deleting or sending to Ask first. If your API supports idempotency keys, use them.

What goes wrong. Gephyr assumes an endpoint acts as the signed-in user unless your docs say it needs no sign-in. A public API then asks people to sign in for nothing.

What Gephyr does. Endpoints your docs mark with security: [] need no sign-in. An app whose actions all need no sign-in publishes without a login.

What you can do. Mark public endpoints with security: [] in your docs, or set the action to No user (public data) in the action editor.

Check before you publish

Test with AI sends realistic requests to real AI models and shows where they pick the wrong action or fill inputs wrongly. Add requests that need exact values, like a provider name or a date range.
Try it yourself. Add your connector to your own AI app and ask what your users would ask.
After launch, Gephyr suggests points out actions agents keep calling with inputs they get wrong, answers that keep being cut short, and actions that keep failing.

Checklist

Every parameter has a one-line description and an example.
Allowed values are an enum; numbers have a minimum and maximum.
Rules are one plain sentence in the endpoint’s description.
Sensible defaults are set as default.
4xx errors are JSON with a message a person can act on.
Lists page, and nothing returns everything at once.
Money, cancelling, deleting and sending are Ask first.
Public endpoints are marked security: [].

Something missing or wrong? Email hello@gephyr.ai.