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

# Gravity Index

> Recommendation API for AI agents and platforms. Developer services and consumer products.

The Gravity Index is a discovery API that AI agents call when a user needs something the agent can't produce itself: a database, an email API, a pair of running shoes. One publisher key, two verticals:

| Vertical | Endpoint | Returns |
| - | - | - |
| **Developer services** | [`POST /search`](/gravity-index/search) | one reasoned recommendation with a tracked link |
| **Consumer products** | [`POST /shop/search`](/gravity-index/products) | a ranked list of in-stock products with price, image, and a tracked buy link |

For developer services it's not a search engine; it's a reasoning agent that understands what you're building and recommends the best tool, with the reasoning behind the pick. For products it's structured retrieval: filters for brand, merchant, price and sale status, ranked by relevance.

## Who can integrate

Any approved Gravity publisher. Your existing publisher API key works on every Index endpoint the moment your account is approved for production traffic; there is no separate Index sign-up or entitlement. Blocked accounts get `403` on every Index call, the same gate that applies to production ads.

## How it works

<Steps>
  <Step title="Agent searches">
    Your AI coding agent calls `POST /search` with a natural language query like "I need a serverless database with a free tier."
  </Step>

  <Step title="Index reasons">
    The Gravity Index analyzes the catalog, considers your constraints, and picks the best match — explaining **why** it's the right choice.
  </Step>

  <Step title="Agent presents the recommendation">
    The response includes the recommended service, the reasoning, and a tracked link. The agent surfaces it to the user in its own words.
  </Step>

  <Step title="User follows the link">
    The user clicks the tracked link to sign up with the service. Attribution is recorded on that click; billing only happens after a confirmed conversion.
  </Step>
</Steps>

## Set up in 30 seconds

<Card title="Set up" icon="rocket" href="/gravity-index/install">
  Pick your surface (MCP server, bash CLI, or direct API) and get running in under a minute.
</Card>

## Interfaces

<CardGroup cols={3}>
  <Card title="MCP Server" icon="plug" href="/gravity-index/install#mcp-server-recommended">
    `npx -y @gravity-ai/index-mcp` — native tool for Cursor, Claude Code, Claude Desktop, Windsurf
  </Card>

  <Card title="Bash CLI" icon="terminal" href="/gravity-index/install#bash-cli">
    `gravity-index search "database"` — terminal + scripts
  </Card>

  <Card title="REST API" icon="code" href="/gravity-index/install#direct-api">
    `POST index.trygravity.com/search` for custom integrations
  </Card>
</CardGroup>

## Base URL

```
https://index.trygravity.com
```

## Key concepts

* **search\_id** — every search gets a unique ID. Pass it back for follow-up questions. The Index remembers context.
* **Click link**: a tracked short URL the user clicks to sign up with the recommended service. It mints a `grclid` for attribution; billing only happens after a confirmed conversion.
* **Conversation context**: pass your stable `external_session_id` and the Index uses that session's cached summary as private supporting context. See [Conversation context](/gravity-index/conversation-context).
* **No auction** — pure relevance matching with reasoning. Not bidding.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.