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

Request Parameters

⚠️ 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:

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