ragora

Ragora Skill for OpenClaw

Use this skill to answer questions with Ragora data. You have two integration paths: MCP (Model Context Protocol) — preferred when your client supports MCP tool binding. REST API — use directly via HTTP when MCP is unavailable or when you need fine-grained control. Both paths share the same authentication, data model, and search capabilities.

Source of Truth Docs

Consult these docs first when behavior differs across environments: MCP guide: https://ragora.app/docs?section=mcp-guide Getting started: https://ragora.app/docs?section=getting-started API overview: https://ragora.app/docs?section=api-overview Retrieve API: https://ragora.app/docs?section=api-retrieve Errors and limits: https://ragora.app/docs?section=api-errors Billing API: https://ragora.app/docs?section=api-billing

Core Concepts

Before using any tools, understand the Ragora data model.

Collections

A collection is a knowledge base — a curated set of documents indexed for semantic search. Each collection has: Name — human-readable label (e.g., "Employee Handbook"). Slug — URL-safe identifier used in dynamic tools and API paths (e.g., employee_handbook). Description — what the collection contains and when to use it. Stats — document count, chunk count, last updated timestamp.

Documents & Chunks

Each collection contains documents (files, pages, articles). Documents are split into chunks — small passages optimized for semantic retrieval. When you search, results are returned at the chunk level with metadata pointing back to the source document.

Versions

Some collections support versioned documentation (e.g., API docs v1.0, v2.0). Use list_versions_{slug}() or the API to discover available versions, then pass a version parameter to scope your search.

Tags & Filters

Collections may support: Custom tags — string labels attached to documents (e.g., ["legal", "msa", "2024"]). Pass as custom_tags to narrow results. Filters — key-value metadata filters (e.g., {"region": "US", "department": "engineering"}). Pass as filters to constrain results.

Credits & Billing

Own collections and subscriptions — free MCP/API access, no credit cost. Marketplace products (pay-per-use) — each retrieval deducts credits based on seller pricing. Credits are measured in USD. Check with check_balance() or GET /v1/billing/balance. Top up at https://app.ragora.app/settings/billing.

Authentication

All requests (MCP and REST) require a Ragora API key. Format: sk_live_<uuid> (e.g., sk_live_a1b2c3d4-e5f6-7890-abcd-ef1234567890) Create one: https://app.ragora.app/settings/api-keys Shown once — copy and store it securely at creation time. Hashed on server — SHA-256 + bcrypt. Ragora cannot recover a lost key; generate a new one.

Security rules

Never pass API keys in URL query parameters. Never print full API keys in logs, outputs, or final answers. If the key is missing or invalid, stop and ask the user for a valid key. Mask keys in any debug output: sk_live_****....

MCP endpoint

URL: https://mcp.ragora.app/mcp Auth header: Authorization: Bearer <RAGORA_API_KEY> OpenClaw config (YAML): name: ragora type: http url: https://mcp.ragora.app/mcp headers: Authorization: Bearer ${RAGORA_API_KEY} Claude Desktop / Cursor / VS Code config (JSON): { "mcpServers": { "ragora": { "type": "http", "url": "https://mcp.ragora.app/mcp", "headers": { "Authorization": "Bearer ${RAGORA_API_KEY}" } } } } Security note: Set RAGORA_API_KEY as an environment variable in your OS or secret manager. Never hardcode the raw sk_live_* value in config files that may be committed to version control.

REST API base URL

Base: https://api.ragora.app/v1 Auth header: Authorization: Bearer <RAGORA_API_KEY> Content-Type: application/json for all POST/PUT requests.

Via MCP

Confirm server health: curl -s https://mcp.ragora.app/health Call discover_collections(). If it returns collections, you're connected. If empty — user may need to access a knowledge base: https://ragora.app/marketplace If credits are low — call check_balance() and tell user to top up at https://app.ragora.app/settings/billing.

Via REST API

Confirm server health: curl -s https://api.ragora.app/v1/health List collections: curl https://api.ragora.app/v1/collections \ -H "Authorization: Bearer <RAGORA_API_KEY>" If the response is 401 or 403, the API key is invalid or expired. Ask the user to generate a new one.

Operating Rules

Start with discover_collections() (MCP) or GET /v1/collections (API) before targeted retrieval, unless the user explicitly names a known collection. Prefer targeted collection search over global search once you know the likely collections. Use global search for broad exploration only — ambiguity, unknown source, or discovery pass. Keep retrieval iterative: run multiple focused queries instead of one long query. Include source attribution from returned results in final answers. Call out uncertainty when evidence is partial, conflicting, or missing. If credits are low or errors mention billing limits, check balance and report constraints. Choose MCP tools when available; fall back to REST API when MCP binding fails or when you need features not exposed via MCP (e.g., pagination, collection metadata).

Static tools (always available)

ToolParametersDescriptiondiscover_collections()noneList all accessible knowledge bases with descriptions, stats, available operations, and usage examples.search(query, top_k?)query (required), top_k (1-20, default 5)Search across ALL accessible collections at once.search_collection(collection_name, query, top_k?, custom_tags?, filters?)collection_name (required), query (required), top_k (1-20, default 5), custom_tags (list of strings), filters (object)Search a specific collection by name or slug.check_balance()noneCredits remaining and estimated USD value.

Dynamic tools (per-collection, returned in manifest)

The Gateway generates these tools for each collection you have access to. The {slug} is the collection's URL-safe name (e.g., employee_handbook, k8s_troubleshooting). ToolParametersDescriptionsearch_{slug}(query, top_k?, version?, custom_tags?, filters?)query (required), top_k (1-20, default 5), version (optional string), custom_tags (list of strings), filters (object)Semantic search within the collection.get_topic_{slug}(topic)topic (required string)Retrieve information about a specific topic from the collection.list_versions_{slug}()noneList all available documentation versions for the collection.

MCP Resources

URIDescriptionragora://collectionsLists all accessible collections with metadata, stats, and available operations.

MCP Prompts

PromptParametersDescriptionsearch_collection_promptcollection_name, queryPre-built prompt for searching a specific collection.summarize_collectioncollection_namePre-built prompt for summarizing an entire collection.compare_sourcescollection_names, questionPre-built prompt for comparing information across multiple collections.

REST API Reference

Use these endpoints when MCP tool binding is unavailable, or when you need direct HTTP control. All endpoints require: Authorization: Bearer <RAGORA_API_KEY>

Health check

GET https://api.ragora.app/v1/health Response: 200 OK with {"status": "ok"} if the service is up.

List collections

GET https://api.ragora.app/v1/collections Returns all collections accessible to the authenticated user. Response: { "collections": [ { "name": "Employee Handbook", "slug": "employee_handbook", "description": "Company policies, benefits, and procedures", "stats": { "document_count": 45, "chunk_count": 1230, "last_updated": "2025-11-15T08:30:00Z" }, "supported_features": ["search", "get_topic", "versions", "filters"] } ] }

Search across all collections

POST https://api.ragora.app/v1/search Request: { "query": "vacation policy for remote employees", "top_k": 5 } Response: { "results": [ { "content": "Remote employees are entitled to 20 days of paid vacation per year...", "score": 0.94, "source": { "collection": "employee_handbook", "document": "benefits-guide.md", "chunk_id": "ch_abc123" }, "metadata": {} } ], "usage": { "cost_usd": 0.0, "balance_remaining_usd": 99.95 } }

Search a specific collection

POST https://api.ragora.app/v1/collections/{slug}/search Request: { "query": "log retention duration and deletion policy", "top_k": 5, "version": "2.0", "custom_tags": ["compliance", "soc2"], "filters": { "region": "US" } } Response: same structure as global search, but scoped to the named collection.

Get topic from a collection

POST https://api.ragora.app/v1/collections/{slug}/topic Request: { "topic": "remote work policy" } Response: { "content": "Detailed information about the remote work policy...", "source": { "collection": "employee_handbook", "document": "remote-work.md" }, "usage": { "cost_usd": 0.0, "balance_remaining_usd": 99.95 } }

List versions for a collection

GET https://api.ragora.app/v1/collections/{slug}/versions Response: { "versions": [ {"version": "2.0", "label": "v2.0 (latest)", "is_default": true}, {"version": "1.5", "label": "v1.5", "is_default": false}, {"version": "1.0", "label": "v1.0 (legacy)", "is_default": false} ] }

Check balance

GET https://api.ragora.app/v1/billing/balance Response: { "credits_remaining": 9950, "estimated_usd": 99.50, "currency": "USD" }

MCP Gateway endpoints (tool proxy)

If you need to call MCP tools via REST (e.g., dynamic tools like search_employee_handbook): Get manifest — lists all available MCP tools for your account: GET https://api.ragora.app/v1/mcp/manifest Execute a tool — call any MCP tool by name: POST https://api.ragora.app/v1/mcp/execute Request: { "tool": "search_employee_handbook", "arguments": { "query": "vacation policy", "top_k": 5 } } Response: { "content": [ { "type": "text", "text": "Found 5 results:\n\n1. **Vacation Policy** (score: 0.95)\n Remote employees are entitled to...\n Source: benefits-guide.md" } ], "usage": { "cost_usd": 0.0, "balance_remaining_usd": 99.95 } }

HTTP status codes

StatusMeaningAgent action200SuccessProcess results normally.400Bad request — malformed query, missing required paramCheck request format. Fix the query and retry.401Unauthorized — missing or invalid API keyStop. Ask the user to provide a valid sk_live_ key.403Forbidden — key is valid but lacks access to this collectionInform user they need to purchase/subscribe to this collection at the marketplace.404Not found — collection slug or endpoint doesn't existCheck the slug with discover_collections() or GET /v1/collections.422Validation error — params are present but invalid (e.g., top_k=50)Read the error message, fix the parameter, and retry.429Rate limited — too many requestsWait and retry with exponential backoff (see Rate Limiting below).402Payment required — insufficient creditsCall check_balance(). Tell user to top up at billing page.500Server errorRetry once after 2 seconds. If it persists, inform user of a temporary service issue.503Service unavailableRetry once after 5 seconds. If it persists, inform user.

Error response format

{ "error": { "code": "insufficient_credits", "message": "Your balance is too low to complete this search. Current balance: $0.05.", "details": {} } }

Common error codes in response body

CodeDescriptionAgent actioninvalid_api_keyKey format wrong or key revokedAsk user for a new key.expired_api_keyKey has expiredAsk user to generate a new key at dashboard.insufficient_creditsNot enough credits for this retrievalReport balance and link to billing.collection_not_foundSlug doesn't match any collectionRe-run discovery, check spelling.collection_access_deniedUser hasn't purchased accessLink user to the marketplace.rate_limit_exceededToo many requests in windowBack off and retry.invalid_queryQuery is empty or too longFix and retry with a shorter, clearer query.version_not_foundRequested version doesn't existCall list_versions_{slug}() to see valid versions.

Limits

MCP tools: 60 calls per minute per API key. REST API: 120 requests per minute per API key. Rate limit headers are returned on every response: X-RateLimit-Limit — max requests in the window. X-RateLimit-Remaining — requests left in the current window. X-RateLimit-Reset — Unix timestamp when the window resets.

Retry strategy

When you receive a 429 response: Read the Retry-After header (seconds to wait) if present. If no Retry-After, use exponential backoff: wait 1s, then 2s, then 4s. Maximum 3 retries before giving up and informing the user. Never retry 401 or 403 — these require user action, not waiting.

Best practices to avoid rate limits

Batch your queries logically: 3-5 focused queries per task, not 20 rapid-fire calls. Use top_k=10-15 instead of making multiple top_k=3 calls for the same question. Cache discover_collections() results within a session — collection lists rarely change mid-conversation.

Authentication Troubleshooting

SymptomLikely causeFix401 Unauthorized on every callMissing or malformed Authorization headerEnsure header is exactly Authorization: Bearer sk_live_xxxxx. No extra spaces, no quotes around the token.401 but key looks correctKey was revoked or regeneratedAsk user to check active keys at https://app.ragora.app/settings/api-keys.401 with invalid_api_key codeKey format is wrong (e.g., missing sk_live_ prefix)Verify format: must start with sk_live_ followed by a UUID.401 with expired_api_key codeKey has an expiration and it passedGenerate a new key from the dashboard.403 ForbiddenKey is valid but doesn't have access to the requested collectionUser needs to purchase or subscribe to the collection.MCP tools not appearingMCP server not configured or wrong URLVerify MCP URL is https://mcp.ragora.app/mcp and header is set. Run health check.MCP tools appear but return errorsKey in MCP config is a placeholderReplace sk_live_xxx with the actual key.ECONNREFUSED or timeoutNetwork issue or service outageCheck https://mcp.ragora.app/health. If down, fall back to REST API or wait.

1. Understand intent

Classify request type: factual lookup, summary, comparison, extraction, or verification. Identify likely domains/collections from user wording.

2. Discover scope

Run discover_collections() (MCP) or GET /v1/collections (API). Select 1-3 collections most relevant to the question. If no relevant collection exists, state that explicitly and stop.

3. Retrieve evidence

First pass: one targeted query per selected collection. Second pass: refine with specific sub-queries (dates, entities, claims, thresholds). Tune top_k based on task: top_k=3-5 for direct factual questions. top_k=8-12 for comparisons or comprehensive summaries. top_k=15-20 for exhaustive research or due diligence.

4. Synthesize

Merge evidence by claim, not by source order. Resolve conflicts by preferring direct passages and recency cues in content. Distinguish facts from inferences.

5. Respond

Give a concise answer first. Then provide evidence bullets with collection/source references. End with gaps, caveats, or suggested follow-up queries when confidence is not high.

Research a topic across multiple collections

Scenario: User asks "What is our data retention policy and how does it compare to SOC 2 requirements?" discover_collections() → find security_handbook, compliance_docs, soc2_guide search_collection("security_handbook", "data retention policy duration", top_k=5) search_collection("compliance_docs", "SOC 2 data retention requirements", top_k=5) search_collection("soc2_guide", "retention controls audit evidence", top_k=5) Synthesize: compare internal policy against SOC 2 requirements, note gaps. Respond with findings, citing each collection.

Compare two vendor contracts

Scenario: User asks "Compare the SLA terms between Vendor A and Vendor B." discover_collections() → find vendor_a_contract, vendor_b_contract search_collection("vendor_a_contract", "SLA uptime guarantees penalties", top_k=8) search_collection("vendor_b_contract", "SLA uptime guarantees penalties", top_k=8) Second pass for specifics: search_collection("vendor_a_contract", "termination notice period remedies", top_k=5) search_collection("vendor_b_contract", "termination notice period remedies", top_k=5) Build comparison table: uptime %, penalty structure, notice periods, exclusions. Highlight key differences and risks.

Due diligence deep dive

Scenario: User asks "Summarize everything we know about Company X's security posture." search("Company X security audit penetration test vulnerability", top_k=15) — broad discovery pass. Identify which collections returned results (e.g., due_diligence_reports, vendor_assessments). Targeted follow-up: search_collection("due_diligence_reports", "Company X SOC 2 ISO 27001 certifications", top_k=10) search_collection("vendor_assessments", "Company X data encryption access controls", top_k=10) search_collection("due_diligence_reports", "Company X incident history breach", top_k=5) Organize findings by category: certifications, technical controls, incident history, gaps. Present with confidence levels and note areas with no data.

Versioned documentation lookup

Scenario: User asks "What changed in the authentication flow between API v1 and v2?" list_versions_api_docs() → returns ["1.0", "2.0"] search_api_docs(query="authentication flow token exchange", version="1.0", top_k=5) search_api_docs(query="authentication flow token exchange", version="2.0", top_k=5) Diff the results: what was added, changed, or removed. Present a clear changelog-style summary.

REST API workflow (no MCP)

Scenario: MCP binding is unavailable. User asks "Find our vacation policy." Health check: curl -s https://api.ragora.app/v1/health List collections: curl https://api.ragora.app/v1/collections \ -H "Authorization: Bearer $RAGORA_API_KEY" Search the relevant collection: curl -X POST https://api.ragora.app/v1/collections/employee_handbook/search \ -H "Authorization: Bearer $RAGORA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "vacation policy paid time off", "top_k": 5}' Parse the results array, extract content and source fields, and compose the answer.

Query Patterns

Use short, specific queries. Prefer multiple passes over one monolithic query.

By task type

TaskQuery patternExampleFactual lookup"<entity> <metric/attribute> <time period>""ACME Corp revenue 2024 Q3"Policy/requirements"<policy type> eligibility criteria exceptions""parental leave eligibility criteria exceptions"ComparisonRun same query across each collection"pricing limits SLA exclusions" × 2 collectionsValidationFirst "<claim>", then "counterexample exception to <claim>""all employees get 20 vacation days" then "exceptions to vacation day policy"Extraction"<entity> <specific data point>""ACME Corp CEO contact information"Timeline"<entity> <event type> chronological""product launches timeline 2023 2024"

Query refinement strategy

Start broad: "data retention policy" — see what's available. Narrow by entity: "customer data retention policy" — scope to a specific domain. Narrow by attribute: "customer data retention duration deletion schedule" — get specifics. Add constraints: Use filters and custom_tags if results are noisy.

Discover collections

MCP: discover_collections() API: curl https://api.ragora.app/v1/collections \ -H "Authorization: Bearer $RAGORA_API_KEY"

Broad search when unsure

MCP: search(query="SOC 2 retention policy for customer logs", top_k=8) API: curl -X POST https://api.ragora.app/v1/search \ -H "Authorization: Bearer $RAGORA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "SOC 2 retention policy for customer logs", "top_k": 8}'

Targeted collection search

MCP: search_collection( collection_name="security-handbook", query="log retention duration and deletion policy", top_k=5 ) API: curl -X POST https://api.ragora.app/v1/collections/security_handbook/search \ -H "Authorization: Bearer $RAGORA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "log retention duration and deletion policy", "top_k": 5}'

Search with version

MCP: search_api_docs( query="authentication flow changes", version="2.0", top_k=5 ) API: curl -X POST https://api.ragora.app/v1/collections/api_docs/search \ -H "Authorization: Bearer $RAGORA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "authentication flow changes", "version": "2.0", "top_k": 5}'

Get topic from a collection

MCP: get_topic_employee_handbook(topic="remote work policy") API: curl -X POST https://api.ragora.app/v1/collections/employee_handbook/topic \ -H "Authorization: Bearer $RAGORA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"topic": "remote work policy"}'

Filtered search

MCP: search_collection( collection_name="contracts", query="termination for convenience notice period", top_k=10, custom_tags=["msa", "legal"], filters={"region": "US"} ) API: curl -X POST https://api.ragora.app/v1/collections/contracts/search \ -H "Authorization: Bearer $RAGORA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "termination for convenience notice period", "top_k": 10, "custom_tags": ["msa", "legal"], "filters": {"region": "US"}}'

Credit check

MCP: check_balance() API: curl https://api.ragora.app/v1/billing/balance \ -H "Authorization: Bearer $RAGORA_API_KEY"

Compare across collections

MCP prompt: compare_sources( collection_names=["vendor-a-docs", "vendor-b-docs"], question="What are the SLA differences?" ) API (manual — run two searches and compare): # Search vendor A curl -X POST https://api.ragora.app/v1/collections/vendor_a_docs/search \ -H "Authorization: Bearer $RAGORA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "SLA uptime guarantees penalties", "top_k": 8}' # Search vendor B curl -X POST https://api.ragora.app/v1/collections/vendor_b_docs/search \ -H "Authorization: Bearer $RAGORA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "SLA uptime guarantees penalties", "top_k": 8}'

Choosing top_k

ScenarioRecommended top_kRationaleSimple factual question3-5Few precise results keep context small.Multi-facet question5-8Need coverage across sub-topics.Comparison across collections8-12 per collectionNeed enough evidence from each side.Exhaustive research / due diligence15-20Comprehensive coverage at the cost of more context.Quick validation of a claim2-3Just need to confirm or deny.

Managing context window size

Prefer targeted searches over global searches. search_collection() returns fewer, more relevant results than search(). Summarize as you go. After retrieving results, extract the key facts before moving to the next query. Don't accumulate raw results. Use multi-pass retrieval. First pass: broad query with top_k=5. Read results. Second pass: specific follow-up queries targeting gaps. Drop low-relevance results. If a result has a low relevance score or doesn't relate to the question, ignore it. Don't retrieve what you already know. If a previous query already answered part of the question, don't re-query for it.

When results are too large

If a single query returns more text than is useful: Reduce top_k to 3. Add custom_tags or filters to narrow scope. Use a more specific query instead of a broad one. Focus on the highest-scoring results and discard the rest.

When results are insufficient

If a query returns no results or irrelevant results: Broaden the query: remove specific terms, use synonyms. Try global search() instead of collection-specific. Check if the collection exists with discover_collections(). Try a different collection if multiple are available. If still empty, tell the user that no relevant data was found.

Standard response structure

• **Answer**: <2-6 sentence direct answer>
• **Evidence**:
• <claim> — *<collection_name> / <source_document>*
• <claim> — *<collection_name> / <source_document>*
• <claim> — *<collection_name> / <source_document>*
• **Caveats**:
• <what is missing, uncertain, or conflicting>
• **Suggested follow-ups** (if applicable):
• <exact query the user could ask next>

Source citation rules

Always cite the collection name and source document for every claim. Format: — *Collection Name / document-name.md* If multiple results support the same claim, cite the highest-scoring one. If results conflict, cite both and note the conflict.

Confidence indicators

High confidence: multiple results agree, high relevance scores (>0.85), from authoritative collections. Medium confidence: single result or moderate scores (0.6-0.85). Note: "Based on a single source." Low confidence: low scores (<0.6), tangential results, or inferred conclusions. Note: "This is inferred and may need verification."

Comparison format

When comparing across collections, use a table: | Aspect | Vendor A | Vendor B | |--------|----------|----------| | Uptime SLA | 99.9% | 99.95% | | Penalty | 5% credit per hour | 10% credit per hour | | Notice period | 30 days | 60 days | *Sources: vendor_a_contract/sla.md, vendor_b_contract/sla.md*

Failure Handling

FailureAgent actionNo resultsBroaden wording, remove overly specific constraints, retry with search(). If still empty, inform user.Too many noisy resultsConstrain by collection, add custom_tags/filters, use narrower entity/date terms.Conflicting evidencePresent both sides, note the conflict, cite both sources, and propose a follow-up query to resolve.Access denied (403)Explain that collection access may need to be purchased. Link to marketplace.Credit errors (402)Run check_balance(), report the balance, and link to billing page.Rate limited (429)Wait per Retry-After header or use exponential backoff. Max 3 retries.Server error (500/503)Retry once after 2-5 seconds. If it persists, inform user of a temporary issue.MCP connection failureFall back to REST API endpoints. Inform user of the switch.TimeoutReduce top_k, simplify the query, and retry.Invalid collection slugRe-run discover_collections() and check available slugs.

Quality Bar

Never fabricate unseen facts — all claims must come from retrieved evidence. Always ground claims in retrieved evidence with source citations. Prefer precise wording over broad generalization. Keep final responses concise, decision-oriented, and source-backed. Distinguish between directly stated facts and inferred conclusions. When evidence is incomplete, explicitly state what is missing rather than guessing. If a question cannot be answered from available collections, say so directly.