AI visibility data for agents and applications.

What the API measures

BuyerOS tests whether search-assisted AI models mention, recommend and directly cite a target brand. Each audit creates 15 grounded buyer questions, runs them across the selected models and returns summary metrics plus prompt-level evidence.

Agent quickstart

1. Connect the agent to https://api.buyeros.ai/mcp/enroll.
2. Call start_user_signup and show the returned claim URL to the user.
3. Poll get_signup_status. The agent token is returned once after approval.
4. Reconnect to https://api.buyeros.ai/mcp with Authorization: Bearer br_agent_….
5. Call create_brand and poll get_brand until the profile is ready.
6. Call generate_brand_questions, review the tracked questions, then call run_visibility_audit.
7. Poll get_visibility_audit before fetching results.

MCP enrollment endpoint: https://api.buyeros.ai/mcp/enroll
Authenticated MCP endpoint: https://api.buyeros.ai/mcp
Authorization: Bearer br_agent_…

The MCP server advertises tool descriptions and input schemas. Request audits:cancel during enrollment if the agent must cancel audits.

REST quickstart

1. Start enrollment

curl -X POST https://api.buyeros.ai/v1/enrollments \
  -H 'Content-Type: application/json' \
  -d '{"agentName":"My agent","scopes":["audits:create","audits:read"]}'

Open the returned claimUrl. After the user signs in and approves access, poll the enrollment with its private poll token.

curl https://api.buyeros.ai/v1/enrollments/{enrollmentId} \
  -H 'Authorization: Bearer br_enroll_…'

2. Create a brand

curl -X POST https://api.buyeros.ai/v1/brands \
  -H 'Authorization: Bearer br_agent_…' \
  -H 'Content-Type: application/json' \
  -d '{"website":"https://example.com","country":"United Kingdom","language":"English"}'

3. Generate tracked questions

curl -X POST https://api.buyeros.ai/v1/brands/{brandId}/questions/generate \
  -H 'Authorization: Bearer br_agent_…' \
  -H 'Content-Type: application/json' \
  -d '{}'

4. Run the audit

curl -X POST https://api.buyeros.ai/v1/brands/{brandId}/audits \
  -H 'Authorization: Bearer br_agent_…' \
  -H 'Idempotency-Key: customer-123-2026-10-01' \
  -H 'Content-Type: application/json' \
  -d '{"config":{"repetitions":1,"maxCostUsd":5}}'

5. Poll and fetch results

curl https://api.buyeros.ai/v1/audits/{auditId} -H 'Authorization: Bearer br_agent_…'
curl https://api.buyeros.ai/v1/audits/{auditId}/results -H 'Authorization: Bearer br_agent_…'
curl https://api.buyeros.ai/v1/audits/{auditId}/runs -H 'Authorization: Bearer br_agent_…'

Asynchronous by design

Terminal statuses are completed, partial, cancelled, and failed. Poll conservatively, such as every 10 to 20 seconds. A partial audit can still contain valid results from completed model runs.

Summary and evidence

The results endpoint returns the sourced business profile, aggregate metrics and every completed observation.

• unbrandedMentionRate: target-brand mentions in non-branded questions.
• unbrandedRecommendationRate: supported recommendations in non-branded questions.
• brandedRecognitionRate: target-brand recognition in branded questions.
• brandedDirectCitationRate: branded answers directly citing the target domain.
• byCategory / byModel: totals, mentions and recommendations grouped for comparison.

Use /runs for stored requests, raw model responses, citations, search execution, evaluations and per-run costs.

Endpoints and schemas

Errors and paid-call recovery

Errors use {"error":{"code":"…","message":"…"}}. Common codes include invalid_request, unauthorized, forbidden, not_found, not_ready, and rate_limited.

Planning and answer requests are recorded before dispatch. An uncertain paid request is not automatically replayed. Completed work is preserved and may be returned as a partial audit. Reusing the same idempotency key safely returns the existing audit.