{"schema_version":"2026-06-13","name":"OSPEA Agent Entry Point","provider":"OSPEA","website":"https://ospea.io","purpose":"Machine-readable entry point for AI visibility monitoring, agent-readiness reporting, first-party AI citation imports, and workspace-scoped optimization workflows.","ideal_users":["AI optimization teams","SEO and GEO agencies","growth teams tracking AI answer visibility","agents acting for authenticated OSPEA workspace owners"],"support":{"contact_url":"https://ospea.io/contact","docs_url":"https://ospea.io/docs","docs_status":"public documentation index is live; deeper product guides are being expanded","api_reference_url":"https://ospea.io/api-reference","api_reference_status":"public API reference for agent/report endpoints is live; full interactive API docs are being expanded","status_url":"https://ospea.io/agents/policies.json"},"auth":{"type":"bearer","workspace_scope":"workspace_id path parameter","permissions":"Workspace data endpoints require authenticated OSPEA access. Agents must act on behalf of an authorized workspace user.","note":"Read report endpoints before write actions. Mutations may consume provider credits or alter workspace tracking setup."},"canonical_entities":[{"type":"workspace","id_format":"uuid","description":"Tenant boundary for prompts, brands, competitors, scans, reports, imports, and costs."},{"type":"brand","id_format":"uuid","description":"Primary entity measured against AI answers and competitor entities."},{"type":"saved_prompt","id_format":"uuid","description":"Exact prompt text used for repeatable AI visibility observations."},{"type":"competitor","id_format":"uuid","description":"Tracked competitor entity used for share-of-voice comparison."}],"observation_schema":{"required_fields":["provider/platform","exact_prompt","model_version","timestamp","full_answer_text","citation_urls","normalized_citation_domains","source_class","brand_mentioned","brand_cited","mention_position","competitors_mentioned","competitors_cited","prompt_cluster","run_type","cost_cents","latency_ms","scan_status"],"run_types":["api-grounded","browser/manual","first-party-feed"],"scan_status_values":["ok","error","timeout"]},"model_defaults":{"selection_policy":"Use the default model for recurring visibility scans unless the workspace owner explicitly requests a premium or experimental model.","providers":[{"provider":"openai","platform":"chatgpt","default_model":"gpt-5.4-mini","premium_model":"gpt-5.5","required_configuration":"OPENAI_API_KEY"},{"provider":"anthropic","platform":"claude","default_model":"claude-sonnet-4-6","premium_model":"claude-opus-4-8","required_configuration":"ANTHROPIC_API_KEY"},{"provider":"google","platform":"gemini","default_model":"gemini-3.5-flash","required_configuration":"GEMINI_USE_VERTEX with GCP project/location credentials, or GEMINI_API_KEY fallback"},{"provider":"perplexity","platform":"perplexity","default_model":"sonar-pro","required_configuration":"PERPLEXITY_API_KEY"},{"provider":"deepseek","platform":"deepseek","default_model":"deepseek-v4-flash","premium_model":"deepseek-v4-pro","required_configuration":"DEEPSEEK_API_KEY"}]},"capability_boundaries":{"available_now":["workspace-scoped AI visibility share-of-voice reports","weekly AIO report and CSV/JSON export","SavedPrompt library and competitor tracking","manual visibility scans when provider credentials and budget are configured","Bing Webmaster Tools AI Performance export import","durable landing page creation, rendering, publishing, and view tracking"],"not_available_until_durable_storage":[{"surface":"editorial backlink marketplace","endpoints":["/backlinks/editorial/*"],"reason":"publisher, placement, attribution, and consent storage is not enabled"},{"surface":"managed link exchange workflows","endpoints":["/backlinks/exchange/sites","/backlinks/exchange/matches","/backlinks/exchange/initiate"],"reason":"exchange site, match, consent, and rate-limit storage is not enabled"},{"surface":"landing page form submissions","endpoints":["/landing-pages/{page_id}/submissions","/landing-pages/{page_id}/submit"],"reason":"durable lead submission storage is not enabled"},{"surface":"batch SERP scraping","endpoints":["/api/v1/serp/scrape/batch"],"reason":"durable job persistence and progress tracking are not enabled"},{"surface":"legacy onboarding website scan jobs","endpoints":["/workspaces/{workspace_id}/onboarding/scan","/workspaces/{workspace_id}/onboarding/scan/{job_id}"],"reason":"durable scan job storage and progress tracking are not enabled"}]},"capabilities":[{"id":"ai_visibility_share_of_voice","status":"available","method":"GET","endpoint":"https://api.ospea.io/api/v1/workspaces/{workspace_id}/monitoring/share-of-voice","input_schema":{"days":"integer 1..365","start_date":"YYYY-MM-DD optional","end_date":"YYYY-MM-DD optional","platforms":"repeatable string query parameter optional","prompt_clusters":"repeatable string query parameter optional"},"output":"Weekly entity share-of-voice by platform, prompt cluster, source class, citation class, success count, failure count, mentions, citations, and visibility score.","safe_for_agents":true,"mutates_state":false},{"id":"weekly_aio_report","status":"available","method":"GET","endpoint":"https://api.ospea.io/api/v1/workspaces/{workspace_id}/monitoring/weekly-aio-report","input_schema":{"days":"integer 1..365","start_date":"YYYY-MM-DD optional","end_date":"YYYY-MM-DD optional"},"output":"Unified weekly AIO report joining OSPEA AI scans, Google Search Console, and Bing AI Performance imports.","safe_for_agents":true,"mutates_state":false},{"id":"weekly_aio_report_export","status":"available","method":"GET","endpoint":"https://api.ospea.io/api/v1/workspaces/{workspace_id}/monitoring/weekly-aio-report/export","input_schema":{"format":"csv or json","days":"integer 1..365","start_date":"YYYY-MM-DD optional","end_date":"YYYY-MM-DD optional"},"output":"Downloadable weekly AIO report export.","safe_for_agents":true,"mutates_state":false},{"id":"prompt_library","status":"available","method":"GET/POST/PATCH/DELETE","endpoint":"https://api.ospea.io/api/v1/workspaces/{workspace_id}/monitoring/library","output":"SavedPrompt rows used by repeatable OSPEA AI visibility scans.","safe_for_agents":"read endpoints are safe; writes require user authorization","mutates_state":"POST/PATCH/DELETE"},{"id":"competitor_tracking","status":"available","method":"GET/POST/PATCH/DELETE","endpoint":"https://api.ospea.io/api/v1/workspaces/{workspace_id}/monitoring/competitors","output":"Tracked competitor entities used in AI visibility scans and share-of-voice reporting.","safe_for_agents":"read endpoints are safe; writes require user authorization","mutates_state":"POST/PATCH/DELETE"},{"id":"manual_visibility_scan","status":"available","method":"POST","endpoint":"https://api.ospea.io/api/v1/workspaces/{workspace_id}/monitoring/scan","output":"Queues a workspace visibility scan using enabled providers. Claude web-search scans are opt-in because they consume higher provider budget.","safe_for_agents":false,"mutates_state":true,"guardrails":["respect scan cadence","confirm workspace owner approval","check scan/status before retrying"]},{"id":"visibility_scan_status","status":"available","method":"GET","endpoint":"https://api.ospea.io/api/v1/workspaces/{workspace_id}/monitoring/scan/status","output":"Refresh-safe scan progress with expected snapshot total, latest update, and progress percentage.","safe_for_agents":true,"mutates_state":false},{"id":"bing_ai_performance_import","status":"available","method":"POST","endpoint":"https://api.ospea.io/api/v1/workspaces/{workspace_id}/monitoring/first-party/bing-ai-performance/import","output":"Imports exported Bing Webmaster Tools AI Performance rows as first-party citation data for weekly AIO reporting.","safe_for_agents":false,"mutates_state":true,"guardrails":["validate row dates","preserve source filename","do not fabricate first-party metrics"]},{"id":"geo_audit","status":"available","method":"GET","endpoint":"https://api.ospea.io/api/v1/aio/geo-audit","input_schema":{"url":"website URL to audit, e.g. https://example.com"},"output":"Public agent-readiness and GEO audit checks for a website.","safe_for_agents":true,"mutates_state":false}],"source_classes":["own-domain","competitor-owned","review","video","social-forum","directory","marketplace","earned-media","docs","unknown","none"],"policies":{"sandbox":"Use read-only report endpoints before write actions where available. Manual scans consume provider budget.","data_access":"Agents may only access workspace-scoped data authorized by the user.","mutation_receipts":"Write actions should persist audit metadata through OSPEA workspace records.","rate_limits":"Respect authenticated account limits, scan cadence, enabled providers, and provider budget approvals.","truthfulness":"Provider failures must be represented as scan_status error or timeout, not as ordinary zero-visibility answers.","first_party_data":"GSC and Bing AI Performance data must come from connected accounts or explicit exports; agents must not fabricate first-party metrics."},"pricing":{"public_pricing_url":"https://ospea.io/pricing","billing_model":"subscription plus plan entitlements, provider-cost tracking, and opt-in expensive-provider scans","notes":["Private workspace limits are enforced by authenticated entitlements.","Agents should inspect billing or entitlement endpoints inside the user workspace before triggering costly actions.","Claude web-search scans are disabled from default bulk scans unless CLAUDE_SCANS_ENABLED is explicitly enabled for an approved audit run."]},"trust":{"report_integrity":"AI visibility reports distinguish successful observations from failed provider attempts and expose model, latency, cost, citation, and source-class metadata where available.","citation_integrity":"Citation domains are normalized and classified as own-domain, competitor-owned, review, video, social-forum, directory, marketplace, earned-media, docs, unknown, or none.","deployment_note":"Production API endpoints require OSPEA authentication and workspace authorization."},"examples":[{"task":"Read Ripli weekly share of voice","method":"GET","endpoint":"https://api.ospea.io/api/v1/workspaces/{workspace_id}/monitoring/share-of-voice?days=7","expected_use":"Summarize brand visibility, competitor share, source classes, and failed provider attempts."},{"task":"Export a weekly AIO report","method":"GET","endpoint":"https://api.ospea.io/api/v1/workspaces/{workspace_id}/monitoring/weekly-aio-report/export?format=csv&days=7","expected_use":"Download report evidence for a weekly client update."},{"task":"Check whether a scan is still running","method":"GET","endpoint":"https://api.ospea.io/api/v1/workspaces/{workspace_id}/monitoring/scan/status","expected_use":"Poll before triggering another scan."}],"not_supported":["unauthenticated access to private workspace reports","UI scraping as a substitute for official API/report endpoints","fabricated first-party GSC or Bing AI Performance metrics","unapproved provider-budget-consuming scans"],"mcp":{"status":"planned","description":"OSPEA should expose MCP tools for report retrieval, prompt library operations, scan status, and first-party import validation."},"machine_readable_urls":["https://ospea.io/agents","https://ospea.io/agents/manifest.json","https://ospea.io/agents/capabilities.json","https://ospea.io/agents/pricing.json","https://ospea.io/agents/policies.json","https://ospea.io/agents/tools.json","https://ospea.io/.well-known/ospea-agent.json","https://ospea.io/docs","https://ospea.io/api-reference","https://ospea.io/llms.txt","https://ospea.io/robots.txt","https://ospea.io/sitemap.xml"]}