Ryze API for agents

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

The agent sends your email:

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:

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:

{
  "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:

curl https://reports.get-ryze.ai/api/v1/tools \
  -H "Authorization: Bearer rk_live_..."

Call one by name. Arguments go inside args:

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.

{ "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.

Getting Started

MCP

Connect Your Platforms

Agent

Billing

Workspaces & Team

White Label

Security & Compliance

2. Verify

3. Call tools

MCP

REST

4. Subscription

5. Connect ad accounts

Errors

Manage keys

​1. Sign up

​2. Verify

​3. Call tools

​MCP

​REST

​4. Subscription

​5. Connect ad accounts

​Errors

​Manage keys

1. Sign up

2. Verify

3. Call tools

MCP

REST

4. Subscription

5. Connect ad accounts

Errors

Manage keys