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

# Search

> Find the best tool for a development task

# Search the Index

The core endpoint. An AI reasoning agent analyzes your query against the catalog and returns the best match with an explanation and install instructions.

Every matched response is **complete and actionable** — install steps, env vars, and a tracked click link are included when the recommended service has a destination URL.

## 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. Framework, language, constraints, etc.
</ParamField>

<ParamField body="platform_api_key" type="string" required>
  Publisher API key for attribution.
</ParamField>

<ParamField body="external_session_id" type="string">
  Your stable chat/session ID. Stored for attribution and payout matching; not used for recommendation reasoning.
</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">
  Structured install instructions the agent can execute.

  <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 get their API credentials.
</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.ai/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.ai/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.