EpidBot OpenClaw Skill#

Enables AI agents to interact with EpidBot's REST API for analyzing Brazilian public health data. EpidBot uses natural language processing to help users query, download, and analyze health data from DATASUS.

Overview#

EpidBot provides access to:

• Brazilian health data: SINAN, SIM, SIH, SIA, CNES, PNI, CIHA, SINASC via PySUS
• International data sources: WHO, PAHO, ECDC, Eurostat, World Bank, HealthData.gov, NZ Health
• Environmental/Vector data: Mosqlimate/InfoDengue forecasts, GBIF species occurrences
• Genomic data: Pathoplexus pathogen sequences
• Literature: OpenAlex, PubMed, Zotero
• Data analysis: Temporal trends, spatial distribution, demographic breakdowns, causal inference
• Visualizations: Charts, maps, heatmaps, raster plots, and PDF reports
• Knowledge base: Document ingestion, wiki, semantic search
• File uploads: CSV, XLSX, GeoJSON, GPKG — auto-converted to parquet
• SQL queries: Execute DuckDB SQL on parquet files via sandbox
• Code snippets: Reusable Python/SQL snippet management

Safety & Data Handling#

Read this section before invoking any endpoint. Following it protects users from accidental data loss, privacy breaches, and compliance violations.

External transmission disclosure#

Every request in this skill sends data to the EpidBot service, a third-party API hosted at $EPIDBOT_BASE_URL (default https://api.epidbot.kwar-ai.com.br). This includes message text, uploaded files, query results, and any content you include in a request body. Confirm the user understands their data is leaving the local machine and being processed by an external service before proceeding.

Sensitive & regulated data#

EpidBot is designed for public health data, which may be subject to LGPD (Brazil), HIPAA, or equivalent regulations. Before uploading files or sending queries that could contain personally identifiable or health information:

• Apply data minimization: upload only the columns/rows needed for the analysis.
• Confirm the user has consent, legal basis, or a data-sharing agreement.
• Prefer de-identified or aggregated data over raw individual-level records.
• Never upload credentials, tokens, or secrets as part of a dataset.

Destructive & irreversible actions#

The following operations are destructive or irreversible. Before executing any of them, state what will happen and get explicit confirmation from the user. Do not batch these silently into an automated workflow.

ActionEndpointRiskPublish datasetPOST /api/v1/uploads/{dataset_id}/publishMakes a private dataset visible to all users — potential public disclosure of sensitive data.

Delete endpoints are intentionally omitted. This skill does not document DELETE /api/v1/uploads/{dataset_id}, DELETE /api/v1/plots/{plot_id}, or POST /api/v1/plots/bulk-delete to prevent automated data loss. Do not call them. Direct users to the EpidBot web UI at https://kwar-ai.com.br/epidbot to manage deletion manually.

Authentication#

Option 1: API Key (Recommended for agents)#

1. Login to EpidBot web interface at https://kwar-ai.com.br/epidbot
2. Go to Settings -> API Keys -> Create new API key
3. Set the API key as an environment variable:

bash

export EPIDBOT_API_KEY="your-api-key-here"
export EPIDBOT_BASE_URL="https://api.epidbot.kwar-ai.com.br"

Option 2: Username/Password (Returns JWT tokens)#

bash

curl -X POST "$EPIDBOT_BASE_URL/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username": "user", "password": "pass"}'

# Response:
# {
#   "access_token": "eyJ...",
#   "refresh_token": "eyJ...",
#   "token_type": "bearer",
#   "expires_in": 900
# }

Option 3: OAuth#

EpidBot supports OAuth login. Check configured providers:

bash

curl "$EPIDBOT_BASE_URL/api/v1/auth/oauth-providers"
# Response: {"providers": [{"name": "google", "label": "Google"}]}

Redirect users to $EPIDBOT_BASE_URL/api/v1/auth/oauth/{provider} to start the flow.

API Base URL#

Default: https://api.epidbot.kwar-ai.com.br/api/v1

Configure via EPIDBOT_BASE_URL environment variable.

Quick Examples#

Check API Health#

bash

curl -H "X-API-Key: $EPIDBOT_API_KEY" \
  "$EPIDBOT_BASE_URL/api/v1/health"

Send a Chat Message (Async Submit + Poll)#

Chat messages are processed asynchronously. Submit a message to get a job_id, then poll for the result.

Important: EpidBot queries may invoke data downloads, SQL execution, and LLM reasoning. Responses typically take 30 seconds to 3 minutes, and complex queries involving large datasets can take up to 5 minutes. Use exponential backoff when polling (start at 3s, double each interval up to 30s, max total wait 5 minutes).

bash

# Step 1: Submit the message (returns immediately with job_id)
JOB=$(curl -s -X POST "$EPIDBOT_BASE_URL/api/v1/chat" \
  -H "X-API-Key: $EPIDBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Show me dengue cases in São Paulo for 2023", "locale": "en"}')

JOB_ID=$(echo $JOB | jq -r '.job_id')

# Step 2: Poll for result with exponential backoff
INTERVAL=3
MAX_WAIT=300  # 5 minutes
ELAPSED=0
while [ "$ELAPSED" -lt "$MAX_WAIT" ]; do
  RESULT=$(curl -s "$EPIDBOT_BASE_URL/api/v1/chat/$JOB_ID" \
    -H "X-API-Key: $EPIDBOT_API_KEY")
  STATUS=$(echo $RESULT | jq -r '.status')
  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; then
    echo $RESULT | jq .
    break
  fi
  sleep $INTERVAL
  ELAPSED=$((ELAPSED + INTERVAL))
  INTERVAL=$((INTERVAL * 2))
  if [ "$INTERVAL" -gt 30 ]; then
    INTERVAL=30
  fi
done

List Available Tools#

bash

curl -H "X-API-Key: $EPIDBOT_API_KEY" \
  "$EPIDBOT_BASE_URL/api/v1/tools"

Tools / Capabilities#

chat (async submit)#

Submit a chat message for async processing. Returns a job_id immediately. LLM responses typically take 5-120 seconds.

Request:

json

{
  "message": "What data is available for dengue in 2023?",
  "session_id": null,
  "locale": "en"
}

Submit Response (200):

json

{
  "job_id": "job_a1b2c3d4...",
  "session_id": 1,
  "status": "processing"
}

chat_poll#

Poll for the status and result of a chat job. Endpoint: GET /api/v1/chat/{job_id}

Recommended polling: exponential backoff starting at 3s, doubling up to 30s, max total wait 5 minutes. Responses may take 30s–3min for simple queries, up to 5min for complex data analysis.

Poll Response -- still processing:

json

{
  "job_id": "job_a1b2c3d4...",
  "status": "processing",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:05Z"
}

Poll Response -- completed:

json

{
  "job_id": "job_a1b2c3d4...",
  "status": "completed",
  "session_id": 1,
  "content": "EpidBot has access to SINAN dengue data for 2023...",
  "images": ["![plot](plots/abc.png)"],
  "thinking": "The user is asking about available data...",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:45Z"
}

Poll Response -- failed:

json

{
  "job_id": "job_a1b2c3d4...",
  "status": "failed",
  "error": "Error message description",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:10Z"
}

chat_stream (WebSocket)#

For streaming responses, connect via WebSocket at:

text

wss://api.epidbot.kwar-ai.com.br/api/v1/chat/stream?api_key=<your-api-key>

Client -> Server Messages:

json

{"type": "start", "payload": {"message": "...", "session_id": null, "locale": "en"}}
{"type": "cancel"}
{"type": "ping"}
{"type": "poll", "payload": {"job_id": "..."}}
{"type": "clarification_response", "payload": {"session_id": 1, "response": "..."}}

Server -> Client Messages:

json

{"type": "thinking", "data": {"content": "..."}}
{"type": "tool_start", "data": {"tool": "...", "job_id": null, "timeout": 240}}
{"type": "tool_complete", "data": {"tool": "...", "duration_ms": 123, "result": {...}}}
{"type": "job_started", "data": {"job_id": "...", "status": "processing"}}
{"type": "job_result", "data": {"job_id": "...", "result": {...}}}
{"type": "chunk", "data": {"content": "..."}}
{"type": "complete", "data": {"content": "...", "images": [], "usage": {...}}}
{"type": "clarification_ack", "data": {"session_id": 1}}
{"type": "error", "data": {"error": "..."}}
{"type": "cancelled"}
{"type": "pong"}

list_sessions#

List all chat sessions for the authenticated user.

Endpoint: GET /api/v1/sessions

Output:

json

[
  {
    "id": 1,
    "name": "Dengue Analysis",
    "message_count": 12,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-02T00:00:00Z"
  }
]

get_session_messages#

Get message history for a specific session.

Endpoint: GET /api/v1/sessions/{session_id}/messages

Output:

json

{
  "session_id": 1,
  "messages": [
    {
      "id": 1,
      "role": "user",
      "text_content": "Show me dengue data",
      "thinking": null,
      "created_at": "2024-01-01T00:00:00Z"
    },
    {
      "id": 2,
      "role": "assistant",
      "text_content": "Here is the dengue data...",
      "thinking": "The user is asking about...",
      "created_at": "2024-01-01T00:00:01Z"
    }
  ]
}

list_reports#

List all generated reports.

Endpoint: GET /api/v1/reports

Output:

json

[
  {
    "id": 1,
    "title": "Dengue Analysis 2023",
    "report_type": "analysis",
    "image_count": 3,
    "content_size_bytes": 15234,
    "has_pdf": true,
    "created_at": "2024-01-01T00:00:00Z"
  }
]

get_report#

Get full details of a specific report.

Endpoint: GET /api/v1/reports/{report_id}

Output:

json

{
  "id": 1,
  "title": "Dengue Analysis 2023",
  "report_type": "analysis",
  "prompt": "Show me dengue cases...",
  "content": "# Dengue Analysis\n\n...",
  "image_count": 3,
  "content_size_bytes": 15234,
  "has_pdf": true,
  "created_at": "2024-01-01T00:00:00Z"
}

download_report#

Download report as a markdown file.

Endpoint: GET /api/v1/reports/{report_id}/download

Output: File download with Content-Disposition header.

list_tools#

List all available agent tools with descriptions.

Endpoint: GET /api/v1/tools

Output:

json

[
  {
    "name": "download_sinan_data",
    "description": "Download SINAN disease notification data for a given disease",
    "parameters": null
  },
  {
    "name": "execute_sql_query",
    "description": "Execute a SQL query on the health database",
    "parameters": null
  },
  {
    "name": "get_temporal_trend",
    "description": "Calculate temporal trend for a dataset",
    "parameters": null
  }
]

search#

Search across chat messages and code snippets.

Endpoint: POST /api/v1/search

Request:

json

{
  "query": "dengue São Paulo",
  "source_type": "message",
  "session_id": null,
  "date_from": "2024-01-01",
  "date_to": "2024-12-31"
}

• source_type: "message", "snippet", or null for both
• session_id: filter to a specific session (optional)

Output:

json

{
  "message_results": [
    {
      "source_type": "message",
      "session_id": 1,
      "session_name": "Dengue Analysis",
      "message_id": 5,
      "role": "assistant",
      "content": "Dengue cases in São Paulo...",
      "created_at": "2024-06-15T10:00:00Z"
    }
  ],
  "snippet_results": []
}

uploads#

Upload custom data files for analysis. Supported formats: CSV, ODS, XLSX, XLS (tabular), GeoJSON, JSON, GPKG, ZIP (GIS). Max 50 MB. Files are auto-converted to parquet for querying.

Privacy notice: Uploading transmits the file to the external EpidBot service. Confirm the data does not contain unconsented personally identifiable or regulated health information before uploading. Apply data minimization (remove unnecessary columns/rows) and prefer de-identified data. See Safety & Data Handling.

Upload a file: POST /api/v1/uploads

bash

curl -X POST "$EPIDBOT_BASE_URL/api/v1/uploads" \
  -H "X-API-Key: $EPIDBOT_API_KEY" \
  -F "file=@data.csv" \
  -F "name=sinan_aggregated_2023" \
  -F "description=Aggregated dengue case counts by municipality"

List user datasets: GET /api/v1/uploads

Get dataset info: GET /api/v1/uploads/{dataset_id}

Update description: PATCH /api/v1/uploads/{dataset_id}

Publish dataset (make public): POST /api/v1/uploads/{dataset_id}/publish

Public disclosure risk. Publishing makes the dataset visible to all EpidBot users. Confirm the user has verified the dataset contains no sensitive, identifiable, or regulated data before publishing. This cannot be auto-reversed by this skill.

plots#

Manage generated plots and images. Upload custom images or list plots generated by the agent.

List plots: GET /api/v1/plots

Upload a plot image: POST /api/v1/plots/upload (PNG, JPG, WebP, GIF, SVG — max 20 MB)

Get plot info: GET /api/v1/plots/{plot_id}

Update plot metadata: PATCH /api/v1/plots/{plot_id}

Download plot: GET /api/v1/plots/{plot_id}/download

catalog#

List available datasets from the data catalog with metadata (row counts, column counts, file sizes). Designed for IDE data browser integration.

List datasets: GET /api/v1/catalog/datasets

Query parameters: search (filter by name), limit (max 200, default 50)

Output:

json

[
  {
    "id": 1,
    "name": "sinan_dengue_2023",
    "path": "/data/pysus/sinan_dengue_2023.parquet",
    "row_count": 150000,
    "column_count": 42,
    "file_size_bytes": 52428800
  }
]

Export dataset as CSV: GET /api/v1/catalog/datasets/{dataset_id}/csv

jobs#

List and poll background jobs (e.g., manuscript writing, dataset enrichment).

List jobs: GET /api/v1/jobs

Query parameters: job_type (filter by type), status (filter by status), limit (max 200)

Get job by ID: GET /api/v1/jobs/{job_id}

Output:

json

{
  "id": "job_abc123",
  "job_type": "manuscript",
  "status": "completed",
  "session_id": 5,
  "result": {"content": "..."},
  "error": null,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:05:00Z"
}

usage#

Check token quota and usage history.

Get usage: GET /api/v1/usage

Query parameters: limit (max 200, default 50)

Output:

json

{
  "quota": {
    "tokens_used": 15000,
    "tokens_limit": 100000,
    "consultations_used": 20,
    "consultations_limit": 50,
    "reset_date": "2024-01-02",
    "is_allowed": true
  },
  "recent_usage": [
    {
      "id": 1,
      "tokens_input": 500,
      "tokens_output": 200,
      "tokens_total": 700,
      "model": "gpt-4",
      "session_id": 1,
      "created_at": "2024-01-01T10:00:00Z"
    }
  ],
  "warnings": []
}

knowledge base#

Manage the knowledge base: search documents, add content, browse wiki, run audits.

Get KB status: GET /api/v1/kb/status

List collections: GET /api/v1/kb/collections

Search KB: POST /api/v1/kb/search

json

{"query": "dengue transmission", "limit": 10}

Add document: POST /api/v1/kb/documents

Add URL: POST /api/v1/kb/urls

Browse wiki: GET /api/v1/kb/wiki

Query wiki: GET /api/v1/kb/wiki/query?q=topic

Ingest wiki page: POST /api/v1/kb/wiki/ingest

Run audit: POST /api/v1/kb/audit

List audit flags: GET /api/v1/kb/audit/flags

Error Handling#

All endpoints may return errors:

json

{
  "detail": "Error message description"
}

Common Status Codes:

• 400 - Bad Request (invalid input)
• 401 - Unauthorized (missing/invalid authentication)
• 403 - Forbidden (valid auth but insufficient permissions)
• 404 - Not Found
• 429 - Too Many Requests
• 500 - Internal Server Error

Agent Usage Patterns#

Pattern 1: Async Chat (Submit + Poll) -- Recommended#

text

Agent: POST /chat -> get job_id -> poll GET /chat/{job_id} with exponential backoff (3s, 6s, 12s, 24s, 30s, 30s...) -> return result
Best for: All queries. Responses take 30s–5min depending on complexity.
IMPORTANT: Always poll with exponential backoff up to 5 minutes total. Do not give up early.

Pattern 2: Streaming Chat (WebSocket)#

text

Agent: Connect to WebSocket -> Send start message -> Receive streaming chunks -> Receive complete
Best for: Long responses, real-time feedback, progress indicators

Pattern 3: Session-Aware Chat#

text

Agent: List sessions -> Get session messages -> Continue conversation in same session
Best for: Multi-turn analysis workflows

Pattern 4: Tool-Based Workflow#

text

Agent: List tools -> Execute specific tool -> Process result -> Chat about results
Best for: Automated data retrieval pipelines

Available Data Sources#

Brazilian (DATASUS/PySUS)#

• SINAN: Disease notifications (dengue, Zika, chikungunya, measles, etc.)
• SIM: Mortality data
• SIH: Hospital admissions
• SIA: Outpatient procedures
• CNES: Health facilities
• PNI: Vaccination coverage
• CIHA: Hospital care records
• SINASC: Live birth records

International#

• WHO/GHO: Global health indicators
• PAHO: Immunization, malaria, dengue, health indicators for the Americas
• ECDC: European disease surveillance
• ECDC Atlas: Disease and antimicrobial resistance atlas data
• World Bank: Development indicators
• HealthData.gov: US hospital capacity, COVID metrics, nursing homes, vaccination, testing
• Eurostat: Mortality, life expectancy, healthcare expenditure, physicians, hospital beds
• NZ Health: New Zealand mortality, hospital events, life tables, immunisation

Environmental/Vector#

• Mosqlimate/InfoDengue: Dengue surveillance, climate data, vegetation, mosquito indices, ARIMA/LSTM/ensemble forecasts
• GBIF: Species occurrence records

Genomic#

• Pathoplexus: Genomic sequence data for pathogens

Geographic#

• GADM: Administrative boundary shapefiles (global)
• IBGE: Brazilian census and demographic data

Literature#

• OpenAlex: Academic literature search
• PubMed: Biomedical literature
• Zotero: Reference management

Configuration#

Environment VariableDefaultDescriptionEPIDBOT_API_KEY-API key for authenticationEPIDBOT_BASE_URL``https://api.epidbot.kwar-ai.com.brBase URL of EpidBot API

Rate Limits#

EndpointLimitPOST /auth/login10 requests/minutePOST /auth/register5 requests/minuteOther endpoints60 requests/minute

Limitations#

• Job expiry: Chat jobs expire after 1 hour
• Response time: Simple queries take 30s–3min; complex data analysis can take up to 5 minutes. Always poll with exponential backoff.
• File sizes: Large data exports may be limited by memory constraints
• Sandbox execution: Python/SQL code execution happens in an isolated sandbox with resource limits

Support#

• Homepage: https://kwar-ai.com.br/epidbot
• GitHub: https://github.com/fccoelho/EpiDBot