Connect your API

Gephyr needs a map of your API: which endpoints exist and what they take and return. You provide one of the sources below, and Gephyr turns it into a short list of clear actions that AI agents use well.

Availability: importing an OpenAPI (3.x), Swagger 2.0 or Postman collection file is live, in JSON or YAML: upload it, or paste a link to the file, your docs page or your website. Reading endpoints from written docs pages and HAR recordings are coming. Until then, add actions by hand in the Tools tab, or email hello@gephyr.ai and we’ll help.

Ways to bring in your API

APIs don’t list their own endpoints, so one of these is always needed. Gephyr never guesses addresses by trial and error.

From endpoints to actions

Agents work best with a short list of clear actions, not every endpoint. Gephyr’s AI:

1. Picks the endpoints a typical user would want an agent to use (up to 20), and leaves out admin, sign-in, webhook, internal and deprecated ones, and ones that need a file upload (agents in a chat have no file to send). The console lists what was left out and why.
2. Writes plain-language names and descriptions, for each action and its inputs. Rules in your docs that an agent needs to get a useful answer, like “set at least one of these”, “dates must be in the future” or “at most 31 days apart”, stay in the description: if the AI leaves one out, Gephyr adds it back from your docs. Agents read input descriptions to fill in each value, and API docs often write them for developers, so the AI rewrites the ones that are missing, unclear or full of developer notes: what goes there, in what form, with a short example where it helps (“The Pokémon’s number, such as 25 for Pikachu”), using only what your docs show. It only changes the words: an input’s name, type, limits and whether it’s required always come from your docs. Your docs’ example value (“Example: 2024-05-01”) and any rule in your docs’ description are kept, and a rule the input itself sets, like numbers only, a date as YYYY-MM-DD or at most 100, is added in words when the description doesn’t already say it.
3. Suggests access levels: looking things up is Read, normal changes are Write, and payments, cancellations and deletions are Confirm (shown as “Ask first”). Changes to sign-in details and account security are Confirm too, and actions that take a password start off (see account security). The AI can make an action more careful, never less careful than these rules.
4. Writes example requests for your setup page once you save your actions, like “Show my runs from last week”. You can edit them before you publish.

Every import tidies input descriptions, with or without the AI (once your monthly AI drafting is used up, Gephyr’s rules make the draft): links, code marks, quotes and other formatting become plain text, very long descriptions are shortened, and the input’s own rules are said in words, as above. Apps you saved before keep their descriptions; import again to update them, or edit any input’s description yourself on the Actions tab.

Each action calls exactly one endpoint, built from your file; the AI chooses and describes actions but never writes the API call itself. During import Gephyr doesn’t call your API at all.

You review the list: switch actions on or off and check each level, then confirm your API address. You can switch on more of your endpoints later; once more than 40 actions are on, agents search them instead of reading a long list (see apps with many actions). Rename and edit actions any time in the Tools tab before you publish.

Next, check your actions are easy for agents to use: see Make your API agent-ready.

What each action contains

• Name and description: what the assistant reads to decide when to use it. Clear descriptions matter more than anything else.
• Inputs: each with a type and limits (e.g. a date, a number from 1 to 50). Assistants can’t send anything that doesn’t match.
• The API call it makes: method, path and body, filled from the inputs.
• What comes back: which fields of your API’s response the assistant sees. You can hide fields such as internal IDs or other people’s data. On import, Gephyr already hides secrets (passwords, tokens, keys) and, on a user’s own data, owner IDs like user_id that no action needs. List actions page: when your docs show how an endpoint pages (a cursor, page number or offset, and a page size), Gephyr sets it up so agents get one page at a time. See what agents get back.
• Order: if your API can sort a list newest first (a sort option such as -created_at, or a Supabase table with a created_at column), imported list actions default to that, so “my latest workout” means the latest one.
• Access level: see Tools and access.

Limits

• Gephyr only calls your API over HTTPS, and only the hosts you list. It never follows redirects and never calls IP addresses or internal hostnames.
• Each call has a 15-second time limit and a 1 MB response limit.
• Values placed in a URL path are always encoded, so an input can’t change which endpoint is called.

When your API changes

Gephyr checks your API docs every day and tells you which actions a change affects. It can update those actions for you, keeping your own settings, but only when you ask, and it never publishes anything: you decide what goes live.

Set it up. When you import from a link, Gephyr keeps the link to your docs file and checks it daily from then on. Imported a file instead? On the Actions tab, under Keep up with your API, paste the link to your OpenAPI, Swagger or Postman file (the file itself, not a docs page). The link has to be public https://; Gephyr follows at most one redirect, and only to another public https:// address.

What it finds, for each action that’s on:

Gephyr only says a response field is gone where your docs list every field there; where they allow fields they don’t list, it says nothing. Response checks need OpenAPI or Swagger docs that describe responses.

Actions with something to look at show Your API changed on their row, and the card lists what changed, what may fail first. Mark as reviewed clears a finding until it changes (another choice gone from the same input asks again); saving your actions checks again straight away. With a very long list, the card shows the first 200 and counts the rest, which can’t be marked as reviewed until you fix some. New endpoints in your docs are listed too: add one with Add action, or import again to see Gephyr’s suggestions.

Update my actions. When the card lists changes, choose Update my actions. Gephyr reads your docs again and shows each change it can make, ticked:

Untick anything you’d rather do yourself, then choose Make these changes. Your names, descriptions, levels, input names, hidden fields, notes for agents and price check stay as they are. The changes are saved as a draft, like Save actions: nothing changes for your users until you publish. A gone response root, a deprecated endpoint and renamed text written by other people need a look by hand. Save or discard unsaved edits on the Actions tab first.

If Gephyr can’t read the docs (the link is down, or answers with a web page), the card says why, keeps what it found last time, and tries again the next day. Check now reads them straight away; Stop checking forgets the link.

No public link? Choose Check a file to compare a file now (nothing is saved), or check in your build with the CLI: gephyr import <app> openapi.json --check exits with 1 when something may fail, so a change to your API can’t ship without you knowing.

To start again from your docs instead, import them from the setup page, or with gephyr import <app> <file> --replace. A new import replaces the action list when you save it, so re-apply any renames. Published actions only change when you publish again.

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