skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
octen-team/octen-skills75 installs

octen-search

USE FOR web search, news, company or person lookup, and fast URL lookup. Real-time web search for AI agents powered by Octen, with dedicated endpoints for news (returns storylines, not just articles), business lookup (returns company and person cards), and pulse (predicts the URL a query means in ~10ms, for docs and known sites). Fast, fresh, and relevant — returns ranked results with highlights, full content, domain filtering, and time filtering. Average response under 80ms with minute-level index freshness. Also supports broad (multi-query) search that fans one question into several sub-queries for comprehensive coverage.

How do I install this agent skill?

npx skills add https://github.com/octen-team/octen-skills --skill octen-search
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    The octen-search skill is a legitimate tool providing real-time web, news, and business search capabilities via the Octen API. It follows standard security practices for API authentication and uses encrypted HTTPS for all external communications to the vendor's domain.

  • Socketpass

    No alerts

  • Snykwarn

    Risk: MEDIUM · 1 issue

What does this agent skill do?

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

ParameterTypeRequiredDefaultDescription
querystringYes-Search query (max 500 chars)
countintegerNo5Number of results (1–100)
include_domainsstring[]No-Only include results from these domains (max 1200 domains, each max 60 chars)
exclude_domainsstring[]No-Exclude results from these domains (max 1200 domains, each max 60 chars)
include_textstring[]No-Strings that must appear in result page text (max 5 items, each max 30 chars)
exclude_textstring[]No-Strings that must not appear in result page text (max 5 items, each max 30 chars)
languagestring[]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_basisstringNoautoTime field used for filtering: auto, published, crawled
start_timestringNo-Start time filter, ISO 8601 (e.g. 2025-01-01T00:00:00Z)
end_timestringNo-End time filter, ISO 8601 (must be after start_time)
highlightobjectNo{"enable": true}Highlight options (see below)
formatstringNotextOutput format for highlights: text or markdown
safesearchstringNostrictAdult content filter: off or strict
full_contentobjectNo{"enable": false}Full content options (see below)
include_imagesbooleanNofalseReturn 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

FieldTypeDefaultDescription
enablebooleantrueReturn query-relevant highlights in each result
max_tokensinteger512Max tokens per highlight (100–20000)

Full Content Options

FieldTypeDefaultDescription
enablebooleanfalseReturn full raw page content for each result
max_tokensinteger2048Max tokens per result (100–100000)

Response Format

Response Fields

FieldTypeDescription
codeintegerStatus code. 0 = success
msgstringHuman-readable status message
request_idstringUnique request identifier
data.querystringThe original query
data.results[]arrayList of search results
data.results[].titlestringPage title
data.results[].urlstringPage URL
data.results[].highlightstring?Query-relevant snippets (when highlight.enable is true)
data.results[].full_contentstring?Full page content (when full_content.enable is true)
data.results[].authorsstring?Website name or author
data.results[].time_publishedstring?Publish time, ISO 8601
data.results[].time_last_crawledstring?Last crawl time, ISO 8601
data.results[].faviconstring?Favicon URL of the result site
data.results[].cover_imageobject?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_queriesintegerNumber of search queries executed
meta.usage.full_content_tokensintegerTotal tokens returned in full_content
meta.latencynumberResponse time in milliseconds
meta.warningstring?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

ParameterTypeRequiredDefaultDescription
querystringYes-Original search query (max 500 chars)
max_queriesintegerNo5Upper bound on the number of sub-queries generated (1–30); raise toward 30 for surveys/research, lower for a tighter search
search_optionsobjectNo-Options applied to each sub-query — same fields and defaults as the Parameters table above (count, include_domains, language, time filters, highlight, full_content, include_images, …)

Response

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

FieldTypeDescription
data.querystringThe original query
data.queries[]string[]The generated sub-queries
data.search_results[]arrayOne result group per sub-query
data.search_results[].querystringThe sub-query for this group
data.search_results[].results[]arrayResults for that sub-query (same shape as Search data.results[])
data.search_results[].latencyintegerLatency for that sub-query, in milliseconds

News Search

News Search is its own endpoint, not /search with a flag. Alongside ranked articles it returns subjects: the coverage grouped into storylines, each with a summary and the span it covers — so "what happened with X" is answerable without reading every article. Read the storylines first; the articles are the evidence behind them.

include_domains / exclude_domains filter data.results only — never data.subjects. The storylines are built from the open web regardless, so a question that restricts its sources ("what is Reuters reporting on X") has to be answered from data.results. Answering it from the storylines cites outlets the caller excluded.

Use it for what is being reported right now: breaking events, announcements, coverage of a company or person over the last days or weeks. For a company or person profile — financials, key people, career history — use Business Search below, which returns that as structured cards instead of articles.

Endpoint

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

Example

curl -s -X POST "https://api.octen.ai/news-search" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{
    "query": "EU AI Act enforcement",
    "count": 10,
    "time_range": "week",
    "subjects": {"count": 3}
  }'

Parameters

Same fields and defaults as the Parameters table above except include_text / exclude_text, format, safesearch and include_images, which this endpoint does not take — plus:

ParameterTypeRequiredDefaultDescription
subjectsobjectNoon{enable, count (def 2, 1–5), max_sub_news (def 5, 1–20)} — group the coverage into storylines. Omit to take the server default.

Response

Same envelope (code, msg, request_id, meta) as Search. data.results[] has the same shape as Search's, plus:

FieldTypeDescription
data.subjects[]arrayOne per storyline; present only when subjects.enable and at least one was found. Not subject to include_domains / exclude_domains — see above
data.subjects[].namestringThe storyline
data.subjects[].summarystringWhat it amounts to
data.subjects[].time_start / .time_lateststringThe span it covers
data.subjects[].top_newsobjectThe lead article, with its own summary
data.subjects[].sub_news[]arraySupporting articles

Business Search

Business Search returns the companies and people behind a query as entity cards — profile, identifiers, financial and stock metrics, key people, career history, recent announcements — alongside the ranked sources. Name two companies in one query and each gets a card with the same fields, ready to compare.

The cards are the point. They carry what a model would otherwise assemble by reading a dozen pages, so a company question costs a fraction of the context.

Use it for questions about a business or the people in one: what a company does, due diligence, who runs it, how two compare, what they have announced lately. For breaking coverage of an event use News Search; for general web pages use plain /search. Set entities.enable to false for a plain ranked list.

Endpoint

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

Example

curl -s -X POST "https://api.octen.ai/business-search" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{
    "query": "compare Stripe and Adyen payment processing",
    "count": 10,
    "entities": {"count": 2, "max_news": 5}
  }'

Parameters

Same fields and defaults as the Parameters table above except include_text / exclude_text, format, safesearch and include_images, which this endpoint does not take — plus:

ParameterTypeRequiredDefaultDescription
entitiesobjectNoon{enable, count (def 2, 1–20), max_activities (def 5, 1–20), max_news (def 5, 1–20)}. Omit to take the server default.

The domain, time and language filters narrow the ranked results only — never the entity cards.

Response

Same envelope (code, msg, request_id, meta) as Search. data.results[] has the same shape as Search's, plus:

FieldTypeDescription
data.entities[]arrayOne card per company or person
data.entities[] (company)objectname, summary, aliases, identifiers, attributes, metrics, key_people, logo, activities, news
data.entities[] (person)objectname, summary, linkedin_url, current_position, career, photo, activities, news

Pulse Search

Pulse Search predicts the URL a query most likely means instead of searching for it. One inference replaces query understanding, recall and ranking, so it answers in roughly 10ms for a fraction of the cost.

Use it for reaching a page you could almost name: official docs and API references, help centres, a site you know exists.

  • "github docs" → the docs site
  • "python list methods" → the reference page
  • "how do I return an amazon order" → the help page
  • "youtube" → the destination

Do not reach for it instead of /search. It sees no fresh content and takes no filters — no include_domains, no language, no time window. News, recent events, anything needing freshness: use News Search. A question that needs real retrieval across the open web: use Search. Pulse is not a cheaper substitute for either; it answers a different question.

Endpoint

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

Example

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

Parameters

A different set from the Parameters table above — none of the domain, text, time or language filters apply here.

ParameterTypeRequiredDefaultDescription
querystringYes-What to find the destination for (max 500 chars)
modestringNolitelite or standard — see below
countintegerNo5Results (1–10, not 1–100)
safesearchstringNostrictoff / strict
include_imagesbooleanNofalseNo effect in lite
highlightobjectNo-{enable (def true), max_tokens (def 512, 100–20000)}. No effect in lite
full_contentobjectNo-{enable (def false), max_tokens (def 2048, 100–100000)}. No effect in lite

lite vs standard

lite (default)standard
Returnstitle + URLadds highlight, full content, images, authors, timestamps, favicon
Latency~10ms P50~23ms P50
Use whena URL and a title are enoughthe page content itself is needed

⚠️ In lite the URL comes back without a scheme — github.com/docs, not https://github.com/docs. Prepend https:// before fetching or passing it to Extract.

The first result's full content per search is free; further results are billed.

Response

Same envelope (code, msg, request_id, meta) as Search. data.results[] has the Search result shape, except that in lite only title and url are populated. meta.usage adds billed_mode (lite or standard).

Error Codes

HTTP StatusDescription
400Missing or invalid parameter
401Invalid or missing API key
403Insufficient balance
429Rate limited
500Internal 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

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/octen-team/octen-skills/octen-search">View octen-search on skillZs</a>