Skip to main content
POST
/
search
Search
curl --request POST \
  --url https://index.trygravity.ai/search \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>",
  "search_id": "<string>",
  "context": {},
  "platform_api_key": "<string>",
  "external_session_id": "<string>",
  "external_user_id_hash": "<string>",
  "external_user_id": "<string>",
  "email_hash": "<string>",
  "metadata": {},
  "monetization": {}
}
'
{
  "search_id": "<string>",
  "recommendation": {
    "name": "<string>",
    "slug": "<string>",
    "category": "<string>",
    "description": "<string>",
    "website_url": "<string>",
    "docs_url": "<string>"
  },
  "reasoning": "<string>",
  "install": {
    "summary": "<string>",
    "steps": [
      {}
    ],
    "env_vars": [
      {}
    ],
    "notes": "<string>"
  },
  "credential_request": {
    "setup_url": "<string>",
    "required_env_vars": [
      {}
    ],
    "user_message": "<string>",
    "agent_instruction": "<string>",
    "grclid": "<string>"
  },
  "click_url": "<string>",
  "grclid": "<string>"
}

​
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

​
query
string
required
What you need. Natural language — e.g. “serverless database with free tier” or “auth for Next.js with SSO”
​
search_id
string
Pass a search_id from a previous response to ask a follow-up question. The Index maintains conversation context.
​
context
object
Additional project context. Framework, language, constraints, etc.
​
platform_api_key
string
required
Publisher API key for attribution.
​
external_session_id
string
Your stable chat/session ID. Stored for attribution and payout matching; not used for recommendation reasoning.
​
external_user_id_hash
string
Hash of your user ID. Prefer this over sending a raw user identifier.
​
external_user_id
string
Optional raw user ID. Gravity stores only a SHA-256 hash.
​
email_hash
string
Hash of the user’s normalized email, when available.
​
metadata
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.
​
monetization
object
Optional private publisher ranking controls. Requires platform_api_key. Supported modes: boost_cpa, cpa_only, and cpa_desc. Economics are not returned in the response.

​
Response

​
search_id
string
Unique ID for this search. Pass it back for follow-ups.
​
recommendation
object
The recommended service.
​
reasoning
string
Why this tool is the best fit for your specific query. Natural language explanation.
​
install
object
Structured install instructions the agent can execute.
​
credential_request
object
Explicit handoff instructions for credentials the human user must fetch.
​
click_url
string
Tracked short link the user visits to get their API credentials.
​
grclid
string
Gravity Index click ID minted for the tracked click link.

​
Examples

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",
    "email_hash": "sha256_email",
    "metadata": {"surface": "chat"}
  }'

{
  "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

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.