# Building with an AI agent If an AI agent is writing your integration, this page tells you what it can read and call today, what still needs a person, and what we have not built yet, so it does not waste an afternoon on something that is not there. ## What an agent can read today Every page in these docs is also served as plain Markdown. Add `?format=md` to the page address, or ask for it with an `Accept: text/markdown` header. There is also a short index of every page, in the `llms.txt` format. **cURL** ```bash curl "https://bynefit.com/docs/getting-started?format=md" curl "https://bynefit.com/docs?format=llms" ``` **JavaScript** ```javascript const page = await fetch('https://bynefit.com/docs/getting-started', { headers: { Accept: 'text/markdown' }, }); const markdown = await page.text(); ``` **Python** ```python import requests markdown = requests.get( 'https://bynefit.com/docs/getting-started', headers={'Accept': 'text/markdown'}, ).text ``` **PHP** ```php $ctx = stream_context_create(['http' => ['header' => "Accept: text/markdown\r\n"]]); $markdown = file_get_contents('https://bynefit.com/docs/getting-started', false, $ctx); ``` **Swift** ```swift var req = URLRequest(url: URL(string: "https://bynefit.com/docs/getting-started")!) req.setValue("text/markdown", forHTTPHeaderField: "Accept") let (data, _) = try await URLSession.shared.data(for: req) let markdown = String(decoding: data, as: UTF8.self) ``` ## What an agent needs, and where each piece stands | Surface | What the agent gets | State | | --- | --- | --- | | **llms.txt** | An index of the docs it should read, with a one-line note on each. The format is a community proposal, not a standard, so nothing here depends on it. | (Available) | | **Every page as Markdown** | Clean text with no navigation, by `?format=md` or the `Accept` header. | (Available) | | **[OpenAPI 3.1 spec](https://bynefit.com/docs?format=openapi)** | Every v1 endpoint with its permission, the error envelope and security schemes, generated from the code. | (Available) | | **[Agent skill and integration brief](https://bynefit.com/docs/agent-skill)** | An installable SKILL.md and a paste-in brief with the base URL, auth, every call, errors and what needs a person, generated from the same code as the spec. | (Available) | | **[Agent keys](https://bynefit.com/docs/agent-keys)** | A key made for an agent: read-only to start, named after it, short-lived, in test mode first, every call logged, and the owner approves anything more. | (Available) | | **[Docs MCP server](https://bynefit.com/docs/docs-mcp)** | Search and read these docs from inside an agent, read-only, no key needed. | (Available) | | **Test keys and a sandbox** | A `bapi_tk_test_` or `bapi_pk_test_` key that answers like the real API with sample data, so an agent can fail safely. Writes stay in a private sandbox. See [Test mode](https://bynefit.com/docs/test-mode). | (Available) | ## Hand this to your agent Paste this into your agent. It is written for you to hand over, so the rules about secrets and asking first come from you, not from a web page. If the agent will read your Space, make it an [agent key](https://bynefit.com/docs/agent-keys) first: the key comes with its own hand-off that also carries its limits and how to ask you for more. **Paste into your agent (text)** ``` Integrate this project with the Bynefit API. 1. Read https://bynefit.com/docs?format=llms, then https://bynefit.com/docs/getting-started?format=md. 2. Use the key in the environment variable BYNEFIT_API_KEY. Never print it, log it or commit it. 3. Build against a test key first. Every response from one says X-Bynefit-Mode: test and "livemode": false. 4. With a live key (X-Bynefit-Mode: live), make read calls only. Ask me before any call that creates, changes or deletes data. 5. Follow next_cursor until has_more is false. On a 429, wait for Retry-After. 6. If a response does not match the docs, stop and show me the request and the response. ``` ## What it will read **llms.txt (first lines)** ``` # Bynefit developer docs > Documentation for the Bynefit API, webhooks, embeds and Sign in with Bynefit. The Read API returns JSON and uses cursor paging; every request carries a bearer key. ## Start here - [Quickstart](https://bynefit.com/docs/getting-started?format=md) - [Integration surfaces](https://bynefit.com/docs/integration-surfaces?format=md) - [Building with an AI agent](https://bynefit.com/docs/ai-agents?format=md) - [Agent keys](https://bynefit.com/docs/agent-keys?format=md) - [Docs MCP server](https://bynefit.com/docs/docs-mcp?format=md) - [Agent skill and integration brief](https://bynefit.com/docs/agent-skill?format=md) - [No-code and automation tools](https://bynefit.com/docs/no-code?format=md) - [Authentication](https://bynefit.com/docs/authentication?format=md) - [Test mode](https://bynefit.com/docs/test-mode?format=md) - [Keys and review](https://bynefit.com/docs/keys?format=md) - [OAuth 2.0 / OpenID Connect](https://bynefit.com/docs/oauth?format=md) - [Migrating from the legacy endpoint](https://bynefit.com/docs/legacy-sunset?format=md) ... ``` ## What still needs a person - Creating a key. A Space manager or admin makes an agent key at [/dash/integrations/agent-keys](https://bynefit.com/dash/integrations/agent-keys); for the public directory alone, anyone signed in can make a developer key at [/dash/developers/keys](https://bynefit.com/dash/developers/keys). The full key is shown once. - Saying yes to more. An agent asks for member emails or directory changes through the API, and its owner approves or declines on the key page. Member emails are then reviewed by Bynefit. - Permission to change real data on a Space's behalf. A live key with it needs a review before it is released, and a Space manager or admin has to ask for it. A test key gets it straight away, because it only ever changes its own sandbox. - Copying a webhook's signing secret. It is shown once, to the person who created the endpoint. ## Give the agent its own key An [agent key](https://bynefit.com/docs/agent-keys) is made for this. It is named after the agent, reads only what you tick, runs out within 90 days, starts in test mode with a small units and daily ceiling, and lists every call it makes. Pause or revoke it in one click. > **Hand the agent a test key first.** It sees the same addresses, errors and paging as live, with sample data, and anything it writes stays in its own sandbox for a day. When the code works, swap in a live key. [How test mode works](https://bynefit.com/docs/test-mode). An agent key's own test mode is different: a smaller daily ceiling on your real information, not the sandbox. ## Editing a hosted site An agent with an approved `read:site-files` or `write:site-files` permission can list a Space's sites and read, replace and delete their files. Replacing needs the file's current hash, a secret scan runs on every text file, and every change is versioned and logged. See [Manage and edit a hosted site's files](https://bynefit.com/docs/manage-site-files). ## Creating and managing forms An agent with an approved `write:forms` permission can create forms for a Space, change their settings and fields, pause them and delete the ones that have no submissions. Registration forms and submissions stay with the owner, and every live change is limited and logged. See [Create and manage forms with an AI agent](https://bynefit.com/docs/manage-forms). ## Engagement types An agent with approved `read:engagement-types` and `write:engagement-types` permissions can read and manage a Space's engagement types and their stages. It never reads or changes an engagement or a client. See [Engagement types and stages](https://bynefit.com/docs/manage-engagement-types). ## What the API does for an agent today | Behavior | Today | Still to come | | --- | --- | --- | | Machine-readable errors | Exists. Errors carry a short `error` code and a `message`. Agent key refusals also carry a `request_id` and a `docs_url`. | A request id and a docs link on every error. | | Rate-limit headers | Exists. `X-RateLimit-*` on responses and `Retry-After` on a `429`. | Nothing planned. | | Cursor paging | Exists. `next_cursor` and `has_more`. | Nothing planned. | | Safe retries on writes | Exists on the v1 write endpoints. Send an `Idempotency-Key` and a retry within 24 hours gets the first answer back instead of a duplicate. See [Authentication](https://bynefit.com/docs/authentication#idempotency). | Nothing planned. | | Test mode | Exists. Test keys return sample data with `X-Bynefit-Mode: test` and `"livemode": false`; writes are checked like live and kept in a sandbox. An agent key's test mode is only a smaller daily ceiling on real data. | Nothing planned. | | Know its own limits | Exists for agent keys. `GET /dash/api/v1/agent` returns what it may read, its units and daily ceiling left, and its requests. | Nothing planned. | | Webhook testing | Exists. *Send test event* posts a signed sample, recent deliveries are logged, and a Space admin can replay a logged delivery. | Nothing planned. | ## What exists and what does not - [Read community resources](https://bynefit.com/docs/resources-read) - List and filter community resources with a developer key. JSON, cursor paging. (Available) - [Submit a resource for review](https://bynefit.com/docs/resources-submit) - Propose a new entry. A moderator reviews it before it goes live. (Available) - [Partner events](https://bynefit.com/docs/partner-events) - Partners send their own product events from a page, a server or an app, and read the totals back. Bynefit turns it on per partner. (By approval) - [Hosted sites runtime](https://bynefit.com/docs/sites-runtime-api) - Events, resources, media, forms and page views for a hosted site, with no key. (Available) - [Read and edit hosted site files](https://bynefit.com/docs/manage-site-files) - An agent key lists a Space's sites and reads, replaces and deletes their files, with versions, secret scanning and a daily write ceiling. The key owner approves the permission. (Available) - [Create and manage forms](https://bynefit.com/docs/manage-forms) - An agent key creates forms for a Space, changes their settings and fields, pauses them and deletes unanswered ones, with a daily write ceiling and a test mode. Registration forms and submissions stay out of reach. The key owner approves the permission. (Available) - [Engagement types and stages](https://bynefit.com/docs/manage-engagement-types) - A Space defines its own kinds of client work with ordered stages inside the existing statuses. Managers edit them on the Engagements page, and an agent key reads and manages them with a daily write budget and a test mode. The key owner approves the permissions. (Available) - [Client portal API](https://bynefit.com/docs/client-portal-api) - A signed-in client reads their own engagements, documents and messages; a practice manager runs the pipeline. (Available) - Engagements through an API key or a webhook - Read engagements from your own server, or hear about a change, without a person signed in. (Planned) - [Every docs page as Markdown](https://bynefit.com/docs/ai-agents) - Add ?format=md to any docs page, or send Accept: text/markdown. (Available) - [llms.txt index](https://bynefit.com/docs/ai-agents) - A short index of the docs for tools that read llms.txt, at /docs?format=llms. (Available) - [OpenAPI spec](https://bynefit.com/docs/ai-agents) - An OpenAPI 3.1 description of the v1 API, with the error envelope and security schemes, at /docs?format=openapi. (Available) - [Agent skill and integration brief](https://bynefit.com/docs/agent-skill) - An installable SKILL.md and a paste-in brief, generated from the same code as the spec. (Available) - [Agent keys](https://bynefit.com/docs/agent-keys) - A key made for an AI agent: read-only to start, short-lived, test mode first, every call logged, and the owner approves anything more. (Available) - Request id and docs link on every error - Every error body carries an id to quote to support and a link to the page that explains it. (Planned) - [Test keys and a sandbox](https://bynefit.com/docs/test-mode) - Keys that only touch sample data, ready at once with no review, so a first attempt cannot break anything. (Available) - [Idempotency-Key on writes](https://bynefit.com/docs/authentication) - Retry a v1 write without doing it twice: the first answer is replayed for 24 hours, per key. (Available) - [Status page](https://bynefit.com/docs/status) - Live state, 90-day uptime and incident history for the API, sign-in, webhook delivery, the widget, hosted sites and email. Atom and JSON feeds. (Available) - [Docs MCP server](https://bynefit.com/docs/docs-mcp) - Read-only search of these docs from an AI tool. (Available) --- Source: https://bynefit.com/docs/ai-agents Checked against the live API on October 10, 2026.