> ## Documentation Index > Fetch the complete documentation index at: https://help.get-ryze.ai/llms.txt > Use this file to discover all available pages before exploring further. # Ryze API for agents > Let your AI agent sign up for Ryze, get an API key, and call every Ryze tool over MCP or REST. Your agent can create a Ryze account, get an API key and start working without you opening the app. You step in three times: * read the code from the email * pay, when the agent sends you the payment link * click the link to connect an ad platform ## 1. Sign up The agent sends your email: ```bash theme={null} curl -X POST https://reports.get-ryze.ai/api/v1/agent/signup \ -H "Content-Type: application/json" \ -d '{ "email": "you@company.com" }' ``` Ryze emails an 8-digit code with the subject **"… is your Ryze code"**. It is valid for 1 hour. The email tells the user to share it only with their own agent. Calling signup again sends a new code; use the newest one. ## 2. Verify You give the agent the code. The agent sends it back with your website: ```bash theme={null} curl -X POST https://reports.get-ryze.ai/api/v1/agent/verify \ -H "Content-Type: application/json" \ -d '{ "email": "you@company.com", "code": "12345678", "domain": "company.com", "name": "My agent" }' ``` * `domain` is the business website. Free email domains such as gmail.com are refused. * `name` is optional and labels the key in your settings. The response carries the key. It is shown once, so the agent should store it: ```json theme={null} { "api_key": "rk_live_...", "workspace_id": "...", "mcp_url": "https://connector.get-ryze.ai/mcp", "api_url": "https://reports.get-ryze.ai/api/v1", "docs_url": "https://help.get-ryze.ai/agent-api" } ``` * A new email gets a new account with a workspace for the domain. * An email that already has a Ryze account gets a key for every workspace it can open. `workspace_id` is the one whose website matches `domain`, or `null` when none or several match; `native__get_workspaces` lists them all. * Lost the response? Run signup and verify again. An existing account just gets another key, and old keys keep working until revoked. ## 3. Call tools The key works the same way over MCP and REST. Both expose the same tools. ### MCP Connect your MCP client to `https://connector.get-ryze.ai/mcp` with the header `Authorization: Bearer rk_live_...`. Keys work on `/mcp` only, not on `/sse`. After a platform is connected, its tools come with the next tool list; a client that caches the list may need to reload the connector. ### REST List the tools with their descriptions and input schemas: ```bash theme={null} curl https://reports.get-ryze.ai/api/v1/tools \ -H "Authorization: Bearer rk_live_..." ``` Call one by name. Arguments go inside `args`: ```bash theme={null} curl -X POST https://reports.get-ryze.ai/api/v1/tools/native__list_connections \ -H "Authorization: Bearer rk_live_..." \ -H "Content-Type: application/json" \ -d '{ "args": {} }' ``` When the key covers several workspaces, pass `"workspace"` inside `args`: a name from `native__get_workspaces`. ## 4. Subscription A new account has no subscription yet. Tools whose entry in `GET /api/v1/tools` has `requires_plan: false` work without one: today `native__get_workspaces`, `native__list_connections`, `native__create_connection_link` and `native__get_connection_link`, so the agent can connect platforms right away. Every other tool answers `subscription_required`; its `message` holds the link to start or fix the plan: send it to the user and retry after they do. ## 5. Connect ad accounts Connect a platform in 3 steps: * call `native__create_connection_link` with the provider, for example `meta_ads` * send the returned `url` to the user: it opens the platform's sign-in or a page for its API key, then they pick the accounts Ryze should use * poll `native__get_connection_link` with the returned `link_id` and the same `workspace` every \~30 seconds until `status` is `connected`; the platform's tools then appear in `GET /api/v1/tools` `status` is `waiting` until the user signs in, `connected` once the platform is connected (the user may still be picking accounts for a minute), and `expired` when the link is gone (check `native__list_connections` then). In Claude and ChatGPT the link shows as a card with a Connect button that turns green by itself once the platform is connected (after 20 minutes it stops checking and offers a Check again button). The link works once and expires after 24 hours; a sign-in started in its last 15 minutes still gets 15 minutes to finish. It never signs anyone in to Ryze: whoever opens it can only connect a platform to that workspace. Links work for every platform Ryze connects except GitHub, custom MCP servers and Ryze Sites, which are set up in the Ryze app. OAuth platforms open their sign-in (Microsoft Ads with a Microsoft account; Shopify asks for the store domain first). Platforms connected with an API key, such as Klaviyo, Semrush or WordPress, open a page where the user pastes it. If a platform that allows one connection per workspace is already connected, the link is refused so it never replaces it. ## Errors A tool that ran but refused answers HTTP 200 with a `status`: | `status` | Meaning | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `invalid_arguments` | Wrong or missing arguments, or a request that can't be done as asked (for example the platform is already connected). `message` says why. Tool arguments go inside `args`, never next to it. | | `subscription_required` | No active plan, or its payment failed. `message` holds the link to fix it. | | `out_of_credits` | The plan's credits are used up. | | `not_allowed` | The platform refused the action. | | `not_found` | The object, the tool or the provider does not exist. | | `not_connected` | The platform is not connected. Use a connection link. | ```json theme={null} { "status": "subscription_required", "message": "... https://reports.get-ryze.ai/pay/..." } ``` Problems with the request itself answer with an HTTP error and `{ "error": "..." }`: | HTTP | When | | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | 400 | Invalid signup or verify body, wrong code | | 401 | Missing, invalid or revoked key | | 403 | The key is valid but its user has no workspace | | 404 | The path is not an endpoint. The API is `POST /api/v1/agent/signup`, `POST /api/v1/agent/verify`, `GET /api/v1/tools` and `POST /api/v1/tools/{name}`. | | 429 | The code email could not be sent right now. Wait a minute and call signup again. | ## Manage keys Your keys are listed in the app under **Settings → Profile → API keys**. * **Create key** makes a key without the signup flow: name it, copy it, give it to your agent. It is shown once. * **Revoke** deletes a key and stops it at once.