octen-search

Octen Search

Octen's search skill. It provides real-time web search plus broad (multi-query) search (see Broad Search below). Image and video search live in the separate octen-image-search and octen-video-search skills.

Requires API Key: Get one at https://octen.ai Set it: export OCTEN_API_KEY=your-api-key

API Key Setup

Before searching, ensure `OCTEN_API_KEY` is set. If it is missing — or any call returns `401` — stop and do not retry blindly: tell the user a key is required, point them to https://octen.ai to get one, help them configure it for their agent (below), then continue once it's set.

Configure the key for the relevant agent/runtime:

• Claude Code — add { "env": { "OCTEN_API_KEY": "your-key" } } to ~/.claude/settings.json (a transient shell export will not persist)
• Cursor / Hermes / generic shell — export OCTEN_API_KEY="your-key" in ~/.zshrc or ~/.bashrc
• Codex — ~/.codex/config.toml → [shell_environment_policy], set = { OCTEN_API_KEY = "your-key" }
• OpenClaw — add OCTEN_API_KEY=your-key to ~/.openclaw/.env

See the README for full per-agent instructions.

Quick Start (cURL)

Basic Search

curl -s -X POST "https://api.octen.ai/search" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{"query": "latest AI research 2026", "count": 5}'

With Highlight and Time Filtering

curl -s -X POST "https://api.octen.ai/search" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{
    "query": "summary judgment",
    "count": 10,
    "time_basis": "published",
    "start_time": "2025-01-01T00:00:00Z",
    "end_time": "2026-01-01T00:00:00Z",
    "highlight": {"enable": true, "max_tokens": 300}
  }'

With Domain Filtering

curl -s -X POST "https://api.octen.ai/search" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{
    "query": "climate change policy",
    "count": 5,
    "include_domains": ["nature.com", "science.org"],
    "exclude_domains": ["spam.com"]
  }'

With Language Filtering

curl -s -X POST "https://api.octen.ai/search" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{
    "query": "climate change 2026",
    "count": 5,
    "language": ["ja", "zh"]
  }'

With Full Content

curl -s -X POST "https://api.octen.ai/search" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{
    "query": "latest WHO guidance on influenza vaccination",
    "count": 5,
    "full_content": {"enable": true, "max_tokens": 1000}
  }'

Endpoint

POST https://api.octen.ai/search

Authentication: X-Api-Key: <API_KEY> header

Content-Type: application/json

Parameters

| Parameter | Type | Required | Default | Description | |--|--|--|--|--| | query | string | Yes | - | Search query (max 500 chars) | | topic | string | No | general | Search vertical: general or news | | count | integer | No | 5 | Number of results (1–100) | | include_domains | string[] | No | - | Only include results from these domains (max 1200 domains, each max 60 chars) | | exclude_domains | string[] | No | - | Exclude results from these domains (max 1200 domains, each max 60 chars) | | include_text | string[] | No | - | Strings that must appear in result page text (max 5 items, each max 30 chars) | | exclude_text | string[] | No | - | Strings that must not appear in result page text (max 5 items, each max 30 chars) | | language | string[] | No | [] | Filter results to these languages, as ISO 639-1 codes (e.g. ["en", "ja"]). Supported: ar, de, en, es, fr, hi, id, it, ja, ko, nl, pl, pt, ru, th, tr, vi, zh. Empty = no language filter. See https://localizely.com/iso-639-1-list/ | | time_basis | string | No | auto | Time field used for filtering: auto, published, crawled | | start_time | string | No | - | Start time filter, ISO 8601 (e.g. 2025-01-01T00:00:00Z) | | end_time | string | No | - | End time filter, ISO 8601 (must be after start_time) | | highlight | object | No | {"enable": true} | Highlight options (see below) | | format | string | No | text | Output format for highlights: text or markdown | | safesearch | string | No | strict | Adult content filter: off or strict | | full_content | object | No | {"enable": false} | Full content options (see below) | | include_images | boolean | No | false | Return the page's cover image and in-body images per result (see Response Fields). For searching for images, use the octen-image-search skill instead |

Highlight Options

| Field | Type | Default | Description | |--|--|--|--| | enable | boolean | true | Return query-relevant highlights in each result | | max_tokens | integer | 512 | Max tokens per highlight (100–20000) |

Full Content Options

| Field | Type | Default | Description | |--|--|--|--| | enable | boolean | false | Return full raw page content for each result | | max_tokens | integer | 2048 | Max tokens per result (100–100000) |

Response Format

Response Fields

| Field | Type | Description | |--|--|--| | code | integer | Status code. 0 = success | | msg | string | Human-readable status message | | request_id | string | Unique request identifier | | data.query | string | The original query | | data.results[] | array | List of search results | | data.results[].title | string | Page title | | data.results[].url | string | Page URL | | data.results[].highlight | string? | Query-relevant snippets (when highlight.enable is true) | | data.results[].full_content | string? | Full page content (when full_content.enable is true) | | data.results[].authors | string? | Website name or author | | data.results[].time_published | string? | Publish time, ISO 8601 | | data.results[].time_last_crawled | string? | Last crawl time, ISO 8601 | | data.results[].favicon | string? | Favicon URL of the result site | | data.results[].cover_image | object? | Page cover image {url, description} (when include_images is true and the page has one) | | data.results[].images[] | array? | In-body images of the page as {url, description}, in order of appearance (when include_images is true) | | meta.usage.num_search_queries | integer | Number of search queries executed | | meta.usage.full_content_tokens | integer | Total tokens returned in full_content | | meta.latency | number | Response time in milliseconds | | meta.warning | string? | Warning message, if any |

JSON Example

{
  "code": 0,
  "msg": "success",
  "request_id": "req_abc123def456",
  "data": {
    "query": "latest WHO guidance on influenza vaccination",
    "results": [
      {
        "title": "Influenza (Seasonal) - World Health Organization (WHO)",
        "url": "https://www.who.int/news-room/fact-sheets/detail/influenza-(seasonal)",
        "highlight": "WHO recommends annual vaccination for high-risk groups\n\n...\n\nSeasonal influenza vaccination policies vary by region...",
        "authors": "World Health Organization",
        "time_published": "2024-10-15T00:00:00Z",
        "time_last_crawled": "2026-01-20T02:12:34Z"
      }
    ]
  },
  "meta": {
    "usage": {
      "num_search_queries": 1,
      "full_content_tokens": 0
    },
    "latency": 237,
    "warning": null
  }
}

Broad Search

Broad Search expands your query into several related sub-queries from different angles, searches them concurrently, and returns results grouped per sub-query (not deduplicated across groups) — ready to ground a complete answer.

Use it when a single /search only reaches a few of the relevant subtopics:

• Comparisons across many sources (pricing, products, vendors)
• Surveys / deeper research
• Multi-angle questions that have more than one facet

For a single focused lookup, use plain /search instead.

Pass the original query as-is — Octen generates the sub-queries for you, so do not rewrite or pre-split the question into multiple calls; to widen coverage, raise max_queries (default 5; up to 30 for surveys/research, lower for a tighter search).

Endpoint

POST https://api.octen.ai/broad-search

Example

curl -s -X POST "https://api.octen.ai/broad-search" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{
    "query": "compare cloud GPU pricing across major providers",
    "max_queries": 5,
    "search_options": {"count": 10, "highlight": {"enable": true}}
  }'

Parameters

| Parameter | Type | Required | Default | Description | |--|--|--|--|--| | query | string | Yes | - | Original search query (max 500 chars) | | max_queries | integer | No | 5 | Upper bound on the number of sub-queries generated (1–30); raise toward 30 for surveys/research, lower for a tighter search | | search_options | object | No | - | Options applied to each sub-query — same fields and defaults as the Parameters table above (topic, count, include_domains, language, time filters, highlight, full_content, include_images, …) |

Response

Same envelope (code, msg, request_id, meta) as Search. data contains:

| Field | Type | Description | |--|--|--| | data.query | string | The original query | | data.queries[] | string[] | The generated sub-queries | | data.search_results[] | array | One result group per sub-query | | data.search_results[].query | string | The sub-query for this group | | data.search_results[].results[] | array | Results for that sub-query (same shape as Search data.results[]) | | data.search_results[].latency | integer | Latency for that sub-query, in milliseconds |

Error Codes

| HTTP Status | Description | |--|--| | 400 | Missing or invalid parameter | | 401 | Invalid or missing API key | | 403 | Insufficient balance | | 429 | Rate limited | | 500 | Internal server error |

Security

• API key is sent only to the hardcoded endpoint https://api.octen.ai/search via HTTPS
• Authentication uses the standard X-Api-Key header
• No environment variables are sent to any other endpoints or external services

Notes

• Highlight is enabled by default — set "highlight": {"enable": false} to disable
• Full content is disabled by default — enable it to get raw page text for RAG/grounding
• Use include_domains / exclude_domains to scope results to trusted sources
• Use language (ISO 639-1 codes, e.g. ["ja", "zh"]) to filter results by language — on Broad Search set it inside `search_options`, not top-level
• Use start_time / end_time with time_basis to filter by publish or crawl time
• format: "markdown" returns highlights in markdown; format: "text" returns plain text