API REFERENCE

Web Search

On this page

POST/api/research/web

Search the web for real-time information. Returns ranked results with titles, URLs, and content snippets. Use for narrative context, press coverage, and cultural research that structured data endpoints don't cover.

Authentication

See the authentication guide for API key and account access requirements.

Request

cURL

curl --request POST \
  --url 'https://api.recoupable.dev/api/research/web' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "query": "string"
}'

Request body required

application/json

querystringrequired

The search query — what you want to find on the web.

max_resultsinteger

Maximum number of results to return.

Default: 10

minimum: 1 · maximum: 20

countrystring

ISO country code for regional results (e.g., 'US', 'GB').

minLength: 2 · maxLength: 2

Responses

200Web search results

application/json

statusstring

resultsarray<object>

Ranked web search results.

Item properties

titlestring

urlstring

snippetstring

Content snippet from the search result.

datestringnullable

Publication date if available.

last_updatedstringnullable

Last updated date if available.

formattedstring

Results formatted as markdown for easy reading.

400Validation error

application/json

statusstring · enumrequired

Values: "error"

errorstringrequired

Human-readable error message describing what went wrong.

401Authentication failed — invalid or missing API key

application/json

statusstring · enumrequired

Values: "error"

errorstringrequired

Human-readable error message describing what went wrong.

501The configured research data source does not support this endpoint or data shape.

application/json

statusstring · enumrequired

Values: "error"

errorstringrequired

Human-readable error message describing what went wrong.

501 example

{
  "status": "error",
  "error": "Request failed with status 501"
}

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download research.json

View operation source

json

{
  "description": "Search the web for real-time information. Returns ranked results with titles, URLs, and content snippets. Use for narrative context, press coverage, and cultural research that structured data endpoints don't cover.",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ResearchWebRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Web search results",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchWebResponse"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchErrorResponse"
          }
        }
      }
    },
    "401": {
      "description": "Authentication failed — invalid or missing API key",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchErrorResponse"
          }
        }
      }
    },
    "501": {
      "$ref": "#/components/responses/ResearchDataSourceUnsupported"
    }
  }
}