DocumentationGuidesAPI Reference

Search SERP results

Run a Ray9 SERP query (currently `engine: google` only). Debits credits via the standard identity → plan → credits → rate-limit chain. Only `engine: google` is wired in v1 (`engine: bing` returns 501 `not_implemented`).

POST
/v1/serp/search

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "http://api.ray9.localhost:1355/v1/serp/search" \  -H "Content-Type: application/json" \  -d '{    "keyword": "string"  }'
{
  "requestId": "string",
  "query": {
    "keyword": "string",
    "engine": "string",
    "location": "string",
    "language": "string",
    "device": "string",
    "depth": 0,
    "targetDomain": "string"
  },
  "creditsCharged": 0,
  "creditsRemaining": 0,
  "totalResultsCount": 0,
  "results": [
    {
      "type": "string",
      "rank": 0,
      "title": "string",
      "url": "http://example.com",
      "domain": "string",
      "breadcrumb": "string",
      "description": "string",
      "richSnippet": {
        "top": [
          "string"
        ],
        "bottom": [
          "string"
        ]
      },
      "siteLinks": [
        {
          "title": "string",
          "url": "http://example.com",
          "description": "string"
        }
      ]
    }
  ]
}
{
  "requestId": "string",
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}
{
  "requestId": "string",
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}
{
  "requestId": "string",
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}
{
  "requestId": "string",
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}
{
  "requestId": "string",
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}
{
  "requestId": "string",
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}
{
  "requestId": "string",
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}
{
  "requestId": "string",
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}
{
  "requestId": "string",
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}

API Reference

HTTP API for Ray9 — base URL, authentication, errors, snippets, retry policy, and a per-endpoint reference generated from the OpenAPI spec.

Read credit balance and plan GET

Returns the authenticated organization's current Ray9 credit balance (in mils, 1/1000 USD) and active plan. Read-only — no credits charged, no rate limit beyond per-org inbound. Used by the MCP `usage.get` tool and the Ray9 web app's billing surface.