跳转到主要内容
POST
/
v1
/
searches
curl --request POST \
  --url https://api.olostep.com/v1/searches \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "Best Answer Engine Optimization startups"
}
'
{
  "id": "search_9bi0sbj9xa",
  "object": "search",
  "created": 1760327323,
  "metadata": {},
  "query": "Best Answer Engine Optimization startups",
  "credits_consumed": 10,
  "result": {
    "json_content": "<string>",
    "json_hosted_url": "<string>",
    "links": [
      {
        "url": "<string>",
        "title": "<string>",
        "description": "<string>",
        "markdown_content": "<string>",
        "html_content": "<string>"
      }
    ],
    "size_exceeded": true,
    "credits_consumed": 123
  }
}

​
创建搜索

使用此端点来创建新的搜索请求。

​
请求

路径 POST /v1/searches 请求体 请求体必须是一个包含以下属性的 JSON 对象：
  • query (字符串): 要搜索的查询字符串。
  • filters (对象): 可选的过滤器对象，用于限制搜索结果。
  • sort (字符串): 可选的排序参数，定义结果的排序方式。

​
响应

成功的响应将返回一个包含搜索结果的 JSON 对象。

​
示例

POST /v1/searches HTTP/1.1
Content-Type: application/json

{
  "query": "Olostep",
  "filters": {
    "category": "technology"
  },
  "sort": "relevance"
}

​
响应示例

HTTP/1.1 200 OK
Content-Type: application/json

{
  "results": [
    {
      "id": "123",
      "title": "Olostep Technology Overview",
      "snippet": "Learn more about Olostep's innovative technology solutions..."
    }
  ],
  "total": 1
}

​
错误

如果请求无效，服务器将返回一个错误响应。常见的错误包括：
  • 400 Bad Request: 请求体格式不正确或缺少必需的字段。
  • 401 Unauthorized: 缺少有效的身份验证凭据。
  • 500 Internal Server Error: 服务器遇到意外错误。
确保你的请求符合 API 规范，以避免这些错误。

授权

​
Authorization
string
header
必填

Bearer认证头格式为Bearer ，其中是你的认证令牌。

请求体

application/json
​
query
string
必填

自然语言的搜索查询。

示例:

"What's going on with OpenAI's Sora shutting down?"

​
limit
integer
默认值:12

去重后返回的最大链接数量。

必填范围: 1 <= x <= 25
示例:

10

​
include_domains
string[]

将结果限制在这些域名内。仅限裸主机——开头的 http(s):// 和结尾的斜杠会自动去除。

示例:
["nytimes.com", "wsj.com"]
​
exclude_domains
string[]

排除来自这些域名的结果。仅限裸主机——开头的 http(s):// 和结尾的斜杠会自动去除。

示例:
["reddit.com"]
​
scrape_options
object

可选。当提供时，每个返回的链接也会被抓取，其内容嵌入到响应中。每页抓取的费用会通过底层的 /v1/scrapes 端点自动计费。

响应

成功响应并返回搜索结果。

​
id
string
示例:

"search_9bi0sbj9xa"

​
object
string
示例:

"search"

​
created
integer
示例:

1760327323

​
metadata
object
​
query
string
示例:

"Best Answer Engine Optimization startups"

​
credits_consumed
integer

此请求消耗的总积分：5 个基础搜索积分 + 使用 scrape_options 时每页抓取积分的总和。

示例:

10

​
result
object