truth-search

Search the web using Cloudsways TruthSearch API. Returns highly relevant results with dynamic summaries, snippets, and optional full-text content. Use when y...

Security Scan

The skill's requirements, instructions, and included script are consistent with a web-search integration for the Cloudsways TruthSearch API and do not request unrelated privileges or secrets.

Purpose & Capability

The name/description match the implementation: the script and SKILL.md call the Cloudsways TruthSearch API at truthapi.cloudsway.net and require a single access key (CLOUDSWAYS_AK). Declared binaries (curl, jq) are the exact tools used by the script.

Instruction Scope

The SKILL.md and script only read the provided JSON argument and the one declared env var, then call the documented API endpoint. They do not reference unrelated files, other environment variables, or unexpected external endpoints. Note: enabling content extraction returns full webpage text (expected for this purpose) which may include sensitive or copyrighted content.

Install Mechanism

This is an instruction-only skill with a small included shell script; there is no installer, no archive downloads, and nothing written to disk beyond the provided script. Risk from installation is low.

Credentials

Only a single API key (CLOUDSWAYS_AK) is required, which is proportionate for an external-search API. The script uses that key only in the Authorization header and does not request other credentials or secret paths.

Persistence & Privilege

The skill does not request permanent/always-on presence and does not modify other skills or system settings. It runs on demand and only performs network requests to the documented API.

Assessment

This skill appears coherent and limited to calling the Cloudsways TruthSearch API. Before installing, verify you obtained CLOUDSWAYS_AK from the official Cloudsways site (https://truth.cloudsway.net), store that key securely, and only grant the key the minimal permissions needed. Be aware that if you enable content extraction (enableContent/mainText) the API can return full webpage text which may include sensitive or copyrighted material — avoid sending private queries you wouldn't want shared with the external service. Ensure curl and jq are available in the runtime environment. If you have concerns about sending queries to an external vendor, test with a throwaway API key and inspect returned results/logs first.

Cloudsways TruthSearch Skill

Search the web and extract intelligent fragments or full-text content directly into the LLM context.

Quick Setup

1. Get your Access Key: Sign up at Cloudsways
2. Set environment variable:

export CLOUDSWAYS_AK="your-access-key"

That's it! The skill is ready to use.

---

Quick Start

Method 1: Using the Script

cd ~/scripts/search
./scripts/search.sh '{"q": "your search query"}'

Examples:

# Basic search
./scripts/search.sh '{"q": "latest AI developments"}'

# Search with time filter and pagination
./scripts/search.sh '{"q": "OpenAI news", "freshness": "Week", "count": 20}'

# Deep research (extracts full content and dynamic key fragments)
./scripts/search.sh '{"q": "Agentic AI architecture", "enableContent": true, "mainText": true}'

Method 2: Direct API Call (Recommended for Windows)

If the script has issues, use curl directly:

curl -s -G \
  --url "https://truthapi.cloudsway.net/api/search/smart" \
  --header "Authorization:  ${CLOUDSWAYS_AK}" \
  --data-urlencode "q=your search query" \
  --data-urlencode "count=20" \
  --data-urlencode "freshness=Week"

Real-world example:

curl -s -G \
  --url "https://truthapi.cloudsway.net/api/search/smart" \
  --header "Authorization:  ${CLOUDSWAYS_AK}" \
  --data-urlencode "q=latest AI news February 2026" \
  --data-urlencode "count=20" \
  --data-urlencode "freshness=Week" \
  --data-urlencode "enableContent=true" \
  --data-urlencode "mainText=true"

---

API Reference

Endpoint

GET https://truthapi.cloudsway.net/api/search/smart

Headers

Header	Type	Value	Description
Authorization	String	{YOUR_AK}	Your assigned AccessKey

Request Parameters

Parameter	Required	Type	Default	Description
q	Yes	String	-	Search query term (cannot be empty)
count	No	Integer	10	Number of results. MUST be one of: 10, 20, 30, 40, or 50
freshness	No	String	null	Time filter: Day (24hrs), Week, or Month
offset	No	Integer	0	Pagination offset (skip N results)
enableContent	No	Boolean	false	Extract full text content
contentType	No	String	TEXT	Format: HTML, MARKDOWN, or TEXT
contentTimeout	No	Float	3.0	Timeout in seconds (max: 10.0, min: 0.1)
mainText	No	Boolean	false	Return dynamic summary fragments (requires enableContent: true)

⚠️ Important Notes:

• count must be exactly 10, 20, 30, 40, or 50 - other values will cause errors
• mainText only works when enableContent is set to true
• For real-time news/stock data, results are cached for 10 minutes by default

Response Format

The API returns JSON with the following structure:

{
  "queryContext": {
    "originalQuery": "your search query"
  },
  "webPages": {
    "value": [
      {
        "name": "Article Title",
        "url": "https://example.com/article",
        "datePublished": "2026-02-27T15:46:11.0000000",
        "snippet": "Short summary of the webpage...",
        "mainText": "Dynamic summary fragments relevant to your query...",
        "content": "Full webpage text content...",
        "score": 0.85
      }
    ]
  }
}

Field Descriptions:

• name: Page title
• url: Full URL to the source
• datePublished: Publication timestamp
• snippet: Always included - short content summary
• mainText: Only if enableContent=true + mainText=true - smart query-relevant excerpts
• content: Only if enableContent=true - full page text
• score: Relevance score (0-1)

---

Content Strategy

Choose the right field based on your needs:

Field	Latency	Token Cost	Use Case
snippet	⚡ Fastest	💰 Low	Quick overviews, browsing results
mainText	⚡⚡ Medium	💰💰 Medium	Precise answers, focused research
content	⚡⚡⚡ Slower	💰💰💰 High	Deep analysis, full context needed

Recommended Settings by Use Case

Quick Research (default)

{"q": "topic", "count": 10}

Returns snippet only - fast and efficient.

Focused Research (recommended)

{"q": "topic", "count": 20, "freshness": "Week", "enableContent": true, "mainText": true}

Returns snippet + smart excerpts - best balance of speed, cost, and relevance.

Deep Research (comprehensive)

{"q": "topic", "count": 20, "enableContent": true, "contentType": "MARKDOWN"}

Returns full content - most comprehensive but highest token usage.

---

Troubleshooting

Script JSON Parsing Errors

If you get "Invalid JSON input" errors on Windows, use the direct curl method instead:

curl -s -G \
  --url "https://truthapi.cloudsway.net/api/search/smart" \
  --header "Authorization:  ${CLOUDSWAYS_AK}" \
  --data-urlencode "q=your query here"

SSL/Connection Issues

Do not use the -k flag in curl. Ensure that SSL verification is enabled for security.

Count Parameter Error

If you see error about count parameter, ensure it's exactly 10, 20, 30, 40, or 50:

# ❌ Wrong: count=15
# ✅ Correct: count=20

Environment Variable Not Set

Check if your AK is configured:

echo $CLOUDSWAYS_AK

If empty, set it:

export CLOUDSWAYS_AK="your-access-key"

---

Quick Reference

Common Commands

# Basic search
curl -s -G --url "https://truthapi.cloudsway.net/api/search/smart" \
  --header "Authorization:  ${CLOUDSWAYS_AK}" \
  --data-urlencode "q=your query"

# Recent news (past week)
curl -s -G --url "https://truthapi.cloudsway.net/api/search/smart" \
  --header "Authorization:  ${CLOUDSWAYS_AK}" \
  --data-urlencode "q=your query" \
  --data-urlencode "freshness=Week" \
  --data-urlencode "count=20"

# Deep research with excerpts
curl -s -G --url "https://truthapi.cloudsway.net/api/search/smart" \
  --header "Authorization:  ${CLOUDSWAYS_AK}" \
  --data-urlencode "q=your query" \
  --data-urlencode "enableContent=true" \
  --data-urlencode "mainText=true" \
  --data-urlencode "count=20"

Parameter Cheat Sheet

• count: 10, 20, 30, 40, or 50 only
• freshness: Day, Week, or Month
• contentType: TEXT, HTML, or MARKDOWN
• contentTimeout: 0.1 to 10.0 seconds

Support

• Documentation: Cloudsways Docs
• Sign up: Cloudsways Sign Up
• Issues: Report in Claude Code skill repository

---

Last Updated: 2026-02-28

---