# ako.tools AI visibility audit: agent integration guide

Tool page: https://www.ako.tools/ai-visibility
All ako.tools tools: https://www.ako.tools/llms.txt
Canonical documentation: https://www.ako.tools/developers
As Markdown: https://www.ako.tools/developers.md (any website page: add .md, or send Accept: text/markdown)
API origin: https://api.ako.tools (formerly https://api.buyeros.ai, which keeps serving connections and tokens made there; new connections use https://api.ako.tools)

## Quickstart: connect your assistant and run your first free preview

1. Connect. Add https://api.ako.tools/mcp to your assistant and approve access in the browser.
2. Ask for the website. Ask the person which website to check. Nothing is spent yet.
3. Check the cost. Call estimate_agent_readiness_audit with the website and preview true. It is free. Tell the person the cost: a preview fits the $5 free credit of a new account.
4. Run the preview. Once the person agrees, call run_agent_readiness_audit with the website, preview true and a new idempotencyKey.
5. Wait. Call get_agent_readiness_audit about every 30 seconds until its status is completed, partial or failed.
6. Show the report. Call get_agent_readiness_results. Show the person what it found, the recommended actions, what ako.tools assumed about the business (brand.profile) and dashboardUrl, where they can open the report. Fix a wrong assumption with update_brand_market or update_brand_profile.
7. Offer the full audit. Say what it adds and what it costs (upgrade.fullAudit). Run it only if the person says yes, with run_visibility_audit and generateReport true. If upgrade.fullAudit.canStart is false, call create_credit_top_up and share the link: a person always pays.

Brand, estimate, audit and results responses include nextStep, which says what to do, whether to wait and what the person must approve. Follow it.

Every assistant that can add a remote MCP server connects the same way, including Claude, Claude Code, ChatGPT and Cursor. Some call it a custom MCP server or a custom connector: ChatGPT does, and it needs a paid plan. In Claude Code: claude mcp add --transport http ako-tools https://api.ako.tools/mcp, then /mcp and Authenticate.

## Other ways to connect

Use these only when your assistant cannot add https://api.ako.tools/mcp with OAuth. For a headless or scheduled agent, a person creates a scoped API key at https://www.ako.tools/agents (sign in, name the agent, choose permissions, create the key and copy it once) and the agent sends it as "Authorization: Bearer br_agent_…". If the agent has neither, use enrollment: start_user_signup (MCP at https://api.ako.tools/mcp/enroll) or POST https://api.ako.tools/v1/enrollments, show the claimUrl to the person, wait for approval with get_signup_status waitSeconds 25 (REST: GET /v1/enrollments/{id}?wait=25), and store the returned agentToken in secret settings. Every enrollment response includes nextSteps saying what to do.

An MCP client without OAuth that accepts headers: use an API key as "Authorization: Bearer br_agent_…". A chat or hosted agent with no MCP client: enrollment, where the agent starts it, shows the person the approval link and collects its own key; or the person creates an API key and gives it to the agent. Scripts, scheduled jobs, CI and automation tools: an API key over REST or MCP, stored as a secret. A person always approves an enrollment, creates an API key and pays for credit; credit belongs to the account, so every route spends the same balance.

To check a connection works, call get_credit_balance (GET /v1/billing). It returns the balance and the free credit every new account gets.

## Run each step yourself

The quickstart runs everything in one call. For finer control, such as reviewing the brand and its questions before spending:

1. Set up a brand. Call create_brand with the website and wait until the profile is ready. Show the person what ako.tools found (get_brand): the market (profile.country and profile.language) and what it understood the business does (profile.description and offers), and ask whether that is right. Fix it before spending credit: update_brand_market for the market (it also writes and charges for questions for the new market, so confirm that with the person first) and update_brand_profile for what the business does and its offers. The person can make the same corrections on their dashboard. Competitors are not set up front: each audit reports the other brands AI assistants offer the buyer (namedBrands). Then call generate_brand_questions, which uses the brand's market, and wait until the questions are ready.
2. Estimate, then run. To choose the questions yourself, start with a preview: call estimate_visibility_audit with preview true, then run_visibility_audit with preview true. It asks three questions (discovery, comparison and a customer need) of every AI assistant and writes the recommended actions, for a fraction of a full audit, and fits the free credit. When it finishes, read get_brand_visibility, show the person what it found, then say what the full audit adds (every tracked question and the cost in upgrade.fullAudit) and gently ask whether they would like to run it. If upgrade.fullAudit.canStart is false, call create_credit_top_up and share the checkout link; do not run the full audit without their yes. For a full audit, call estimate_visibility_audit (POST /v1/audits/estimate) for the cost, which is free. If canStart is false, ask the person to add credit with create_credit_top_up and share the link. Then call run_visibility_audit, poll get_visibility_audit until it finishes and read get_brand_visibility: the scores, the other brands and sites AI names, a table of every tracked question, and a verdict with recommended actions if a report has been written. get_visibility_runs has the underlying answers. Recommended actions are written only on request: pass generateReport true to run_visibility_audit, or call generate_visibility_report for a finished audit. Otherwise plan from the evidence yourself.

## Preferred connection: OAuth

Add https://api.ako.tools/mcp to an OAuth-capable MCP client. The client discovers the authorization server (Clerk), opens the browser for sign-in and approval, and securely stores credentials. An OAuth connection has full access to the account. Do not call start_user_signup when the client supports OAuth. Authentication belongs to the client connection and survives individual model runs.

The client must use authorization code with S256 PKCE and resource=https://api.ako.tools/mcp, and request profile email offline_access; the connection is granted audits:read, audits:create and audits:cancel. Access tokens last one day; refresh tokens rotate on each use. Reconnect through the client if renewal fails; no demo is required.

The same access token can call REST with Authorization: Bearer <access_token>. REST and MCP share owners, scopes, quotas and service operations. Add the MCP resource parameter when obtaining a token for either surface.

Manage connections and create scoped API keys for headless agents at https://www.ako.tools/agents. Keys are shown once, must be stored in secret settings, and work through MCP and REST. Revoking a key disables it. Disconnecting an OAuth client refuses its tokens, including renewed ones, until the person allows it again on that page. Reconnecting uses the existing account.

## Enrollment: clients without OAuth

Creating an enrollment sends no email. Share the returned claimUrl as a clickable link in the current conversation. The user opens it, signs in (with a code emailed to them, or Google), then clicks Approve agent access. If already signed in, they can approve directly. Keep pollToken private and wait for approval with get_signup_status and waitSeconds 25 (REST: GET /v1/enrollments/{id}?wait=25), which returns as soon as the user approves, instead of polling. Save enrollmentId and pollToken in persistent private storage before sharing the link; later runs can resume the same request. Do not tell the user to check email before they enter their address on that page.

Sign-in is by Clerk: the person enters their email on the claim page and types the code it sends, or continues with Google. The agent name is not in that email. Enrollment expires after one hour. If the link expired, call refresh_signup_link (REST: POST /v1/enrollments/{id}/refresh) with the same pollToken to get a new claimUrl without starting over.

Optional restriction: only the account with this email can approve the enrollment. It does not send an invitation or sign-in email. Omit unless the user has specified the approving email address.

## Start without a demo

The AI Visibility API is available to agents through MCP and REST. Booking a demo is not required. Prefer a saved OAuth connection to https://api.ako.tools/mcp. Only clients without OAuth should use enrollment at https://api.ako.tools/mcp/enroll (start_user_signup) or POST https://api.ako.tools/v1/enrollments. Retain the enrollmentId and pollToken and resume the same enrollment after approval. See https://www.ako.tools/developers for both quickstarts.

Use the AI Visibility API to test brand mentions, recommendations and citations across AI assistants, using the consumer app where possible and the API where not. ako.tools also offers a demo-led managed readiness service (https://www.ako.tools/managed); that is separate from API enrollment.

## Connection endpoints

- Enrollment MCP: https://api.ako.tools/mcp/enroll
- Authenticated MCP: https://api.ako.tools/mcp
- REST base: https://api.ako.tools/v1
- Service metadata: https://api.ako.tools/
- Earlier host: https://api.buyeros.ai keeps serving the same API, MCP and OAuth for connections made there. New connections use https://api.ako.tools.

## Important behaviour

Access always needs a person's approval: through OAuth, an API key they create, or enrollment. Audits are asynchronous and cost-controlled. Results contain aggregate visibility metrics and prompt-level evidence. ChatGPT, Gemini and Google AI Mode are measured through their consumer apps and the other engines through search-assisted APIs. Neither claims to reproduce a signed-in or personalised assistant.

## Purpose

ako.tools creates a grounded brand profile, maintains a stable bank of tracked buyer questions and repeatedly tests those same questions across AI assistants. Stable question IDs make results comparable over time.

## Enrollment steps for clients without OAuth

1. Connect to https://api.ako.tools/mcp/enroll.
2. Call start_user_signup, show claimUrl to the human and retain the private pollToken.
3. Call get_signup_status with waitSeconds 25, repeating while status is pending, to retrieve the br_agent token; retry with the same enrollmentId and pollToken for up to 24 hours after approval if a response is missed.
4. Connect to https://api.ako.tools/mcp with Authorization: Bearer br_agent_…
5. Call create_brand with website (country and language only when the person chose a market; otherwise the brand takes the one its site serves). Poll get_brand until profileStatus is ready, then show the person the market and profile and correct them with update_brand_market and update_brand_profile.
6. Call generate_brand_questions. Poll get_brand until questionStatus is ready, then inspect list_brand_questions.
7. Optionally call add_brand_question or set_brand_question_active. Never replace question text when longitudinal comparability matters.
8. Call run_visibility_audit with brandId and a stable idempotencyKey.
9. Poll get_visibility_audit until completed, partial, cancelled or failed.
10. Call get_brand_visibility for how the brand appears in AI answers, who is named instead and why, and the recommended actions. Call get_visibility_results for the same scores of one audit, or get_visibility_runs for question-level evidence.
11. Call generate_visibility_report to write a verdict and recommended actions for a finished audit, or to write them again.

MCP also exposes list_brands, refresh_brand_profile, list_visibility_audits and cancel_visibility_audit.

## REST workflow

All brand and audit routes require Authorization: Bearer br_agent_…

- POST /v1/brands creates or reuses a brand and queues profile research.
- GET /v1/brands and GET /v1/brands/{brandId} return brands and profile status.
- PATCH /v1/brands/{brandId} corrects the market (country, language), the description and the offers. A changed market queues question generation for it and returns it as questionGeneration.
- POST /v1/brands/{brandId}/refresh refreshes the profile without replacing questions.
- POST /v1/brands/{brandId}/questions/generate generates the initial tracked set.
- GET /v1/brands/{brandId}/questions lists tracked questions.
- POST /v1/brands/{brandId}/questions adds a custom question.
- PATCH /v1/brands/{brandId}/questions/{questionId} activates or deactivates a question.
- POST /v1/audits/estimate returns the cost of an audit without starting it (free; same body as POST /v1/audits, no Idempotency-Key). Call it first.
- POST /v1/brands/{brandId}/audits runs the active questions. Idempotency-Key is required.
- GET /v1/audits lists audits and accepts an optional brandId filter.
- GET /v1/audits/{id} returns audit status, progress, cost and errors.
- GET /v1/audits/{id}/results returns aggregate results.
- GET /v1/audits/{id}/runs returns every answer with the sites it cited and how it was judged. Raw model requests, provider usage and per-run costs are not returned.
- POST /v1/audits/{id}/cancel requests cancellation.

## Data and measurement

Generated questions cover discovery, customer need, purchase constraint, comparison and branded intent. Only branded questions may name the target brand. Profile refreshes do not regenerate questions. Each audit snapshots the currently active questions, so later additions or deactivations do not alter historical results.

By default an audit tests ChatGPT, Gemini and Google AI Mode as their consumer apps (engines app/chatgpt, app/gemini and app/google-ai-mode) and Claude, Grok, Meta Muse Spark 1.3 and Perplexity Sonar through APIs, once. The apps show few sources, so cited-source counts lean on the API engines. Supply config.models to replace the default panel with 1–7 model IDs. Use maxCostUsd and the smallest useful model set for automated audits. Muse coverage measures the model API, not the consumer Muse agent.

## Reliability

Use one idempotency key per logical audit. Reusing it returns the existing audit. Paid calls are recorded before dispatch. Raw model payloads stay private; each run's answer, citations and evaluation are the evidence. REST errors use {"error":{"code":"…","message":"…"}}.

## Usage limits

REST and MCP share account quotas: reads 60/minute, custom-question writes/cancellation 30/minute, new audits 5/hour and 10/day, one active audit, profiling 5/hour, question generation 5/hour. Enrollment creation is 10/hour per requester IP and polling is 6/minute per enrollment. Limits use fixed UTC-aligned windows and may be configured by the operator. Audit idempotency retries consume no extra audit allowance. Errors expose retryAfterSeconds; REST also returns HTTP 429 and Retry-After. MCP returns the same structured error with isError=true. Obey retry timing instead of repeatedly retrying. Every REST response carries an X-Request-Id header (yours if you sent one, otherwise assigned), every error body repeats it as requestId, and every MCP tool result includes requestId; quote it when reporting a problem, because it identifies the request, the work it queued and every model call made for it.


Credit and pricing: work is paid from prepaid credit in US dollars, with no subscription or seats, at the same price for people, REST and MCP. Only work that succeeds is charged: a failed call, a failed technical audit or an audit run that produces no result costs nothing. Technical audits are priced per page; a new account gets $5 free. Call get_credit_balance (GET /v1/billing) for the balance, the per-page technical audit price and the top-up limits, list_credit_transactions for history and create_credit_top_up (POST /v1/billing/top-ups) for a Stripe checkout link a person opens to pay. A paid operation the account cannot cover returns 402 insufficient_credits with requiredUsd and availableUsd and queues nothing; an audit that runs out of credit stops with status partial and the results so far. Audits report costUsd and estimatedCostUsd. What an audit costs depends on the engines, questions and repetitions chosen, and its estimate is returned when it is accepted; choose fewer engines to cost less. Always call the free estimate first: it is the price of model work, including the report when generateReport is true.

Technical audit capability: audit public-site technical eligibility through POST /v1/technical-audits or run_technical_audit, then poll get_technical_audit and read get_technical_results. Audits up to 50 pages by default (maximum 500) discovered through sitemaps and raw links. Supply website, brandId, or both; brandId links the audit to an owned brand, supplies its website, and filters list_technical_audits. Options: maxPages, maxRenderedPages (maximum 50), vertical. Browser sample defaults to 10 key/template pages. Results schemaVersion 2 includes explicit coverage, grouped fixes and page evidence paginated with offset/limit. Existing audit scopes apply. Technical eligibility is separate from AI visibility outcomes. Browser rendering sends public URLs to Cloudflare; optional compressed evidence is private. See https://www.ako.tools/developers and OpenAPI for contracts and limits.
Agent readiness audit capability: assess whether a website is agent ready in one operation with POST /v1/agent-readiness-audits or run_agent_readiness_audit (website or brandId, idempotency key), then poll get_agent_readiness_audit and read get_agent_readiness_results. It creates or reuses the brand, runs the technical audit, generates tracked questions automatically and runs the AI visibility audit. Pass preview true for a first look: three questions of every engine and a written report, which fits a new account's free credit; results then include the report in visibility.results.report, upgrade and dashboardUrl. The market is the one the brand's site serves by default; country and language narrow the visibility audit to one market (the technical audit is market-independent). Results are data only, with no score. Existing audit scopes apply. See https://www.ako.tools/developers and OpenAPI.

Structured outputs are schema-validated with at most one output retry. A final profile failure stops the readiness audit and cancels active child work; start a new audit to rerun. Readiness costUsd reports what the account paid by stage. Model diagnostics remain private.

Visibility audit creation, status and list responses report costUsd, what the audit has cost the account so far (never including work that failed), and estimatedCostUsd.