API Documentation Guide

Programmatically access Share Of Model visibility and perception data — auth, modules and core concepts.

The Share Of Model API exposes the same AI visibility and perception data available in the platform, so you can integrate it into your tools, dashboards and workflows.

Rather than relying solely on the UI, the API lets you operationalise insights at scale, automate reporting, and connect AI signals to your internal analytics and activation systems.

Modules currently exposed

Search Visibility

AI-driven visibility signals across answer engines — how brands, products and categories surface in AI-generated answers, and which sources contribute to that visibility.

Brand Perception

How AI models describe and interpret a brand — attributes, narratives and associations inferred by AI systems.

Who the API is for

• Product and data teams building internal dashboards.
• Marketing and brand teams centralising AI signals in BI tools.
• Technical teams integrating Share Of Model into proprietary platforms.

What you can do with the API

• Access visibility and citation data across AI answer engines.
• Retrieve brand-perception signals generated by AI models.
• Extract insights at product and category level for reporting or analysis.

All responses are structured for programmatic consumption.

Prerequisites

Generate an API key with the appropriate access privileges before calling the API.

Creating and Managing API Keys

Step-by-step guide for user, workspace and organisation keys.

API keys are scoped to your workspace and must be treated as confidential credentials.

Making your first call

The API documentation is split between two distinct APIs, listed as two groups in the API Reference tab:

Group	Base URL
Core API	https://api.shareofmodel.ai/
Search API	https://api.shareofsearch.jplus.io/

Both use the same /v1/ versioning and are scoped the same way — /v1/organizations/{organization_id}/workspaces/{workspace_id}/…. Only the host changes.

Authentication flow

1. Generate your API key

   See Creating and Managing API Keys.

2. Exchange the key for a JWT

   POST /v1/auth/token with {"secret_key": "<YOUR_API_KEY>"}. The response is {"token": "..."}.

3. Authenticate every request

   Pass the JWT as a Bearer token in the Authorization header on every subsequent request.

See Authentication for token refresh and key scopes.

First test call

A quick way to validate your setup is to call GET /v1/organizations, which lists the organisations you have access to. For other endpoints, follow the parameters described in the API Reference.

How the Search API works

The Search Visibility API is structured around Projects and Collects.

Projects

Projects can only be created through the UI. During setup you define:

• a website,
• a brand,
• a locale (country and language),
• a list of thematics and sub-topics,
• a list of search queries (prompts) — each can include funnel stage, thematic, topic, persona and more,
• a collection frequency (once, daily, weekly, or monthly),
• a list of engines to monitor — see the engine list.

In the API, projects are addressed as analyses: list them with GET /v1/organizations/{organization_id}/workspaces/{workspace_id}/search/analyses, and pass the one you want as the {project_id} path parameter on metric endpoints.

Collects

A collect is automatically created and associated with a project each time the platform gathers metrics.

Frequency	Behaviour
Once	One collect total.
Daily	One collect per day.
Weekly	One collect per week.
Monthly	One collect per month.

List them with GET …/analyses/{project_id}/search/collects. Statuses you may encounter:

Status	Metrics available?
IN_PROGRESS	Not yet — collection is running.
IN_PROGRESS_WITH_ERRORS	Not yet — running, with some failures already recorded.
FINISHED	Yes — complete.
FINISHED_WITH_ERRORS	Yes, but partial — some sources failed, so treat totals as incomplete.
CANCELED	No.
ERROR_INSUFFICIENT_CREDITS	No — the workspace ran out of Search credits before the collect could complete.

Filter on FINISHED when you need complete data. If you accept FINISHED_WITH_ERRORS as well, be aware that comparisons against a fully finished collect are not like-for-like.

Selecting a period

Metric endpoints are driven by a date range, not by collect IDs. Every collect whose date falls in the range is aggregated into the result.

Parameter	Required	Purpose
date_start	Yes	Start of the period to aggregate.
date_end	No	End of the period. Defaults to the most recent data.
period	No	Ask for the current or the previous period, so you can compare the two.

To build an evolution, call the endpoint twice — once with period=current and once with period=previous — and compare the results.

Earlier versions of this API selected data with collect_ids and prev_collect_ids. Those parameters no longer exist; use date_start / date_end / period instead.

Narrowing the results

Most metric endpoints accept the same optional filters, which narrow the aggregation:

Filter	Narrows by
sources	Engines (SearchGPT, Gemini, Google AI Mode…).
thematics, topic_ids	Thematics and sub-topics defined on the project.
keyword_type	Type of search query.
funnel_stages	Funnel stage assigned to the query.
persona_ids	Target personas.
strength_ids, weakness_ids	Strengths and weaknesses.

This structure supports performance snapshots, trends and evolutions over time.

Support

Our support team is available — reach out from the in-app chat for any API question.

What’s next

Quickstart

From zero to your first authenticated call in minutes.

MCP Server Setup

Connect AI assistants to your data.