A2A Protocol v0.3.0

RagSphere API Docs

RagSphere is an Agent-to-Agent (A2A) compliant service that lets you ingest documents and query them using hybrid RAG — combining vector search, knowledge graphs, and optional live web intelligence.

📄
PDF, Excel, YouTube, Web
Ingest generic URLs, PDFs, spreadsheets, or videos.
🔀
Hybrid RAG
Answers combine vector, graph, and web search results.
🔐
Per-User API Keys
Each key is scoped to your account — fully isolated.
1

Get Your API Key

Every request to RagSphere must include your personal API key. Sign in to your dashboard to generate one.

Sign in to get your free API key

Create a free account and generate your key in the dashboard.

Get API Key →

Include key in every request header

http
x-a2a-key: YOUR_API_KEY
2

Ingest a Document

Send a URL pointing to a Website, PDF, Excel file, or YouTube video. RagSphere will download, parse, embed, and index it — then return a document_id you'll use for querying.

ℹ️
Using a local file? Your agent should temporarily host it at a public URL and pass that link to RagSphere. This keeps the A2A protocol clean — JSON only, no binary uploads needed.

Request

bash
curl -X POST https://ragsphere.vercel.app/api/a2a/tasks \
  -H "x-a2a-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "skill": "ingest",
    "input": {
      "source_url": "https://example.com/report.pdf"
    }
  }'

Success Response 200

json
{
  "status": "success",
  "output": {
    "document_id": "64f3a1b2c9e77d001a4e5f21",
    "chunks": 18,
    "source": "report.pdf"
  }
}
⚠️
Save the document_id! You will need it in Step 3 to query this document. RagSphere does not expose a document listing endpoint.
3

Query Your Knowledge

Ask any question about your ingested document. RagSphere runs a Triple-Query across vector embeddings, the Neo4j knowledge graph, and optionally the live web — then synthesises a single answer.

Request

bash
curl -X POST https://ragsphere.vercel.app/api/a2a/tasks \
  -H "x-a2a-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "skill": "query",
    "input": {
      "question": "What are the key findings in Q3?",
      "document_id": "64f3a1b2c9e77d001a4e5f21",
      "use_web_search": false
    }
  }'

Success Response 200

json
{
  "status": "success",
  "output": {
    "answer": "The Q3 report highlights a 23% YoY revenue increase...",
    "document_id": "64f3a1b2c9e77d001a4e5f21"
  }
}
💡
Set "use_web_search": true to augment the answer with live search results from the web. Useful for documents referencing recent events or external data.
4

Handle Responses

All responses are JSON. Check the HTTP status code first, then read the body. Here are the patterns you should handle in your agent.

200SuccessYour request completed. The result is in the output field.
{ "status": "success", "output": { ... } }
400Bad RequestA required field is missing or invalid. Check the details field.
{ "error": "Bad Request", "message": "Invalid input parameters", "details": { ... } }
401UnauthorizedAPI key is missing or invalid.
{ "error": "Unauthorized", "message": "Missing x-a2a-key header" }
404Not Founddocument_id not found — the document may not have been ingested yet.
{ "error": "Resource Not Found", "message": "No context found for the given document_id." }
429Rate LimitedYou have exceeded the 100 requests / 12h limit. Wait and retry.
{ "error": "Rate limit exceeded", "retryAfter": 3600 }
500Server ErrorSomething went wrong on our end. Retry with exponential backoff.
{ "error": "Internal Server Error", "message": "..." }

API Reference

Complete parameter reference for all skills and endpoints.

HEADER Authentication

Required on every request to POST /api/a2a/tasks

HeaderTypeDescription
x-a2a-keyrequiredstringYour personal API key from the RagSphere dashboard.
Content-TyperequiredstringMust be "application/json".

POST Ingest Skill

Process a remote document and add it to your knowledge base.

ParameterTypeDescription
skillrequired"ingest"Literal string that selects the ingest skill.
input.source_urlrequiredstring (URL)Public URL to a Website, PDF, Excel (.xlsx), or YouTube video. The resource must be publicly accessible.

POST Query Skill

Ask a natural language question against an ingested document.

ParameterTypeDescription
skillrequired"query"Literal string that selects the query skill.
input.questionrequiredstringThe natural language question to answer.
input.document_idrequiredstringThe document_id returned from a previous ingest call.
input.use_web_searchboolean= falseWhen true, augments the answer with live Tavily web search results. Useful for time-sensitive topics.

Error Codes

StatusErrorHow to fix
400Bad RequestEnsure all required fields are present and source_url is a valid URL.
400Unsupported SourceOnly PDF, Excel, and YouTube URLs are accepted.
401UnauthorizedInclude a valid x-a2a-key header. Generate one from the dashboard.
404Resource Not FoundThe document_id does not exist for your account. Re-ingest the document first.
429Rate Limit ExceededYou've hit the 100 req / 12h limit. Check the Retry-After header and wait.
500Internal Server ErrorTransient server error. Retry with exponential backoff.

Rate Limits

EndpointLimitWindowScope
POST /api/a2a/tasks100 requests12 hoursPer API key

A sliding window algorithm is used. When limited, the response includes a Retry-After header (in seconds) and a retryAfter field in the body.

Code Examples

Copy-paste ready snippets in common agent languages.

Python — Ingest + Query

python
import requests

API_KEY = "your_api_key_here"
BASE    = "https://ragsphere.vercel.app/api/a2a/tasks"
HEADERS = {"x-a2a-key": API_KEY, "Content-Type": "application/json"}

# Step 1: Ingest a document
ingest_res = requests.post(BASE, headers=HEADERS, json={
    "skill": "ingest",
    "input": {"source_url": "https://example.com/report.pdf"}
})
data = ingest_res.json()
document_id = data["output"]["document_id"]
print(f"Ingested! document_id = {document_id}")

# Step 2: Query the document
query_res = requests.post(BASE, headers=HEADERS, json={
    "skill": "query",
    "input": {
        "question": "Summarise the key findings.",
        "document_id": document_id,
        "use_web_search": False
    }
})
answer = query_res.json()["output"]["answer"]
print(f"Answer: {answer}")

JavaScript / Node.js — Ingest + Query

javascript
const API_KEY = "your_api_key_here";
const BASE    = "https://ragsphere.vercel.app/api/a2a/tasks";
const headers = { "x-a2a-key": API_KEY, "Content-Type": "application/json" };

// Step 1: Ingest
const ingestRes = await fetch(BASE, {
  method: "POST",
  headers,
  body: JSON.stringify({
    skill: "ingest",
    input: { source_url: "https://example.com/report.pdf" },
  }),
});
const { output: { document_id } } = await ingestRes.json();
console.log("document_id:", document_id);

// Step 2: Query
const queryRes = await fetch(BASE, {
  method: "POST",
  headers,
  body: JSON.stringify({
    skill: "query",
    input: {
      question: "What are the key findings?",
      document_id,
      use_web_search: false,
    },
  }),
});
const { output: { answer } } = await queryRes.json();
console.log("Answer:", answer);

cURL — Quick test

bash
# Ingest
curl -X POST https://ragsphere.vercel.app/api/a2a/tasks \
  -H "x-a2a-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"skill":"ingest","input":{"source_url":"https://example.com/report.pdf"}}'

# Query (replace DOCUMENT_ID with value from above)
curl -X POST https://ragsphere.vercel.app/api/a2a/tasks \
  -H "x-a2a-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"skill":"query","input":{"question":"Key findings?","document_id":"DOCUMENT_ID","use_web_search":false}}'
© 2026 RagSphere — A2A Protocol v0.3.0
agent-card.json ↗Home