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

# Search

> Find the best tool for a development task

The core endpoint for **developer services**. An AI reasoning agent analyzes your query against the catalog and returns the single best match with an explanation of why it fits.

Every matched response includes the **reasoning** and a **tracked click link** (when the recommended service has a destination URL) that the agent can hand to the user. Pass your `external_session_id` so the Index can use the conversation as private supporting context; see [Conversation context](/gravity-index/conversation-context).

<Note>
  Looking for physical products (shoes, cookware, electronics)? That is a different vertical with a
  ranked-list response; use [`POST /shop/search`](/gravity-index/products). Sending a shopping
  query here returns no match.
</Note>

## Authentication

Send your publisher key as the `X-API-Key` header or as the `platform_api_key` body field. One of the
two is required.

<ParamField header="X-API-Key" type="string">
  Publisher API key. Alternative to the `platform_api_key` body field.
</ParamField>

## Request

<ParamField body="query" type="string" required>
  What you need. Natural language — e.g. "serverless database with free tier" or "auth for Next.js with SSO"
</ParamField>

<ParamField body="search_id" type="string">
  Pass a `search_id` from a previous response to ask a follow-up question. The Index maintains conversation context.
</ParamField>

<ParamField body="context" type="object">
  Additional project context the reasoning agent should weigh, e.g. `{"framework": "nextjs",
      "language": "typescript", "constraints": ["free tier", "EU region"]}`. Free-form; anything the
  user already told you about their stack belongs here rather than stuffed into `query`.
</ParamField>

<ParamField body="platform_api_key" type="string">
  Publisher API key for attribution. Alternative to the `X-API-Key` header — send one or the other.
</ParamField>

<ParamField body="external_session_id" type="string">
  Your stable chat/session ID. Send it by default: when Gravity has a summary of that conversation,
  Index uses it as private supporting context for the recommendation (see
  [Conversation context](/gravity-index/conversation-context)). Also used for attribution and payout
  matching. Never returned in the response.
</ParamField>

<ParamField body="external_user_id_hash" type="string">
  Hash of your user ID. Prefer this over sending a raw user identifier.
</ParamField>

<ParamField body="external_user_id" type="string">
  Optional raw user ID. Gravity stores only a SHA-256 hash.
</ParamField>

<ParamField body="hashed_email" type="string">
  SHA-256 of the user's normalized email (`email.strip().lower()`), when available. This is the canonical field and matches the [ad request](/ai-platforms/request-ads) convention. The legacy `email_hash` field is still accepted as an alias.
</ParamField>

<ParamField body="metadata" type="object">
  Non-sensitive publisher metadata such as surface, workspace, plan, or placement. Stored with the search for attribution/debugging; not used in the LLM prompt.
</ParamField>

<ParamField body="monetization" type="object">
  Optional private publisher ranking controls. Requires `platform_api_key`. Supported mode: `boost_cpa` — relevance-first ranking that gives a small boost to services with an active CPA campaign. Omit (or use `off`) for pure relevance. Economics are not returned in the response.
</ParamField>

## Response

<ResponseField name="search_id" type="string">
  Unique ID for this search. Pass it back for follow-ups.
</ResponseField>

<ResponseField name="recommendation" type="object">
  The recommended service.

  <Expandable>
    <ResponseField name="name" type="string">Service name</ResponseField>
    <ResponseField name="slug" type="string">URL-safe identifier</ResponseField>
    <ResponseField name="category" type="string">e.g. Database, Auth, AI</ResponseField>
    <ResponseField name="description" type="string">What it does</ResponseField>
    <ResponseField name="website_url" type="string">Service website</ResponseField>
    <ResponseField name="docs_url" type="string">Documentation link</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="reasoning" type="string">
  Why this tool is the best fit for your specific query. Natural language explanation.
</ResponseField>

<ResponseField name="install" type="object">
  Optional structured setup details for the recommended service. Present when the catalog has them; agents may ignore this and simply present the recommendation.

  <Expandable>
    <ResponseField name="summary" type="string">One-line install description</ResponseField>
    <ResponseField name="steps" type="array">Ordered install steps with commands, files, and user actions</ResponseField>
    <ResponseField name="env_vars" type="array">Environment variables needed</ResponseField>
    <ResponseField name="notes" type="string">Context-specific configuration notes</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="credential_request" type="object">
  Explicit handoff instructions for credentials the human user must fetch.

  <Expandable>
    <ResponseField name="setup_url" type="string">Tracked setup link the user opens</ResponseField>
    <ResponseField name="required_env_vars" type="array">Environment variables the user should paste back</ResponseField>
    <ResponseField name="user_message" type="string">User-facing instruction to show verbatim</ResponseField>
    <ResponseField name="agent_instruction" type="string">Agent-facing instruction for pausing/resuming setup</ResponseField>
    <ResponseField name="grclid" type="string">Gravity click ID for attribution</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="click_url" type="string">
  Tracked short link the user visits to sign up with the recommended service.
</ResponseField>

<ResponseField name="grclid" type="string">
  Gravity Index click ID minted for the tracked click link.
</ResponseField>

## Examples

### Basic search

```bash theme={null}
curl -X POST https://index.trygravity.com/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $GRAVITY_PUBLISHER_KEY" \
  -d '{
    "query": "I need a serverless database with a free tier",
    "external_session_id": "session_123",
    "external_user_id_hash": "sha256_user_id",
    "hashed_email": "sha256_email",
    "metadata": {"surface": "chat"}
  }'
```

```json theme={null}
{
  "search_id": "238c2e03-347b-438e-8b52-f9cacee31ebe",
  "recommendation": {
    "name": "Neon",
    "slug": "neon",
    "category": "Database",
    "description": "Serverless Postgres with branching, autoscaling, and bottomless storage.",
    "website_url": "https://neon.tech"
  },
  "reasoning": "Neon is the best fit because it's serverless Postgres with a generous free tier, supports edge functions, and has database branching for preview deployments.",
  "install": {
    "summary": "Provision a serverless Postgres database",
    "steps": [
      {"step": 1, "action": "Install the Neon driver", "command": "npm install @neondatabase/serverless"},
      {"step": 2, "action": "Create a db client", "file": "lib/db.ts"},
      {"step": 3, "action": "Add connection string", "file": ".env.local"},
      {"step": 4, "action": "Get credentials", "user_action": "Go to https://console.neon.tech → Connection Details"}
    ],
    "env_vars": ["DATABASE_URL"]
  },
  "credential_request": {
    "setup_url": "https://index.trygravity.ai/go/xKHR2xqP9z",
    "required_env_vars": ["DATABASE_URL"],
    "user_message": "Open the setup link for Neon, create or find the required credentials, then paste the values for `DATABASE_URL` back into the agent so it can finish the integration.",
    "agent_instruction": "Pause for any missing credentials, ask the user to open setup_url, then continue once they paste values back.",
    "grclid": "xKHR2xqP9z"
  },
  "click_url": "https://index.trygravity.ai/go/xKHR2xqP9z",
  "grclid": "xKHR2xqP9z"
}
```

### Follow-up question

```bash theme={null}
curl -X POST https://index.trygravity.com/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $GRAVITY_PUBLISHER_KEY" \
  -d '{
    "search_id": "238c2e03-347b-438e-8b52-f9cacee31ebe",
    "query": "Does it support database branching for preview deploys?"
  }'
```

The Index remembers the previous conversation and answers in context.


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