> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shareofmodel.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<CardGroup cols={2}>
  <Card title="Search Visibility" icon="magnifying-glass" href="/platform/search/overview-what-how-purpose">
    AI-driven visibility signals across answer engines — how brands, products and categories surface in AI-generated answers, and which sources contribute to that visibility.
  </Card>

  <Card title="Brand Perception" icon="eye" href="/platform/models/brand-analysis-starter-kit">
    How AI models describe and interpret a brand — attributes, narratives and associations inferred by AI systems.
  </Card>
</CardGroup>

## 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.

<Card title="Creating and Managing API Keys" icon="key" href="/platform/getting-started/creating-and-managing-api-keys">
  Step-by-step guide for user, workspace and organisation keys.
</Card>

<Warning>
  API keys are scoped to your workspace and must be treated as confidential credentials.
</Warning>

## 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

<Steps>
  <Step title="Generate your API key">
    See [Creating and Managing API Keys](/platform/getting-started/creating-and-managing-api-keys).
  </Step>

  <Step title="Exchange the key for a JWT">
    `POST /v1/auth/token` with `{"secret_key": "<YOUR_API_KEY>"}`. The response is `{"token": "..."}`.
  </Step>

  <Step title="Authenticate every request">
    Pass the JWT as a **Bearer token** in the `Authorization` header on every subsequent request.
  </Step>
</Steps>

See [Authentication](/api-reference/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](/api-reference/introduction).

## 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](/platform/getting-started/models-list-of-llms-models-apis#search-visibility).

<Note>
  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.
</Note>

### 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. |

<Tip>
  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.
</Tip>

### 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.

<Warning>
  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.
</Warning>

### 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

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

## What's next

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/api-reference/quickstart">
    From zero to your first authenticated call in minutes.
  </Card>

  <Card title="MCP Server Setup" icon="plug" href="/platform/getting-started/get-started-with-share-of-model-mcp">
    Connect AI assistants to your data.
  </Card>
</CardGroup>