REST API · V1.0

Siwaan API Documentation

Integrate explainable workforce predictions directly into your internal tooling and HRMS.

Overview

The Siwaan API allows enterprise customers to integrate workforce intelligence directly into their existing HRMS, custom dashboards, and performance portals.

All sensitive API queries are routed directly through your locally deployed Siwaan agent container. Plain-text employee descriptions or status updates never exit your secure local area network.

Local Agent Base URL:
http://localhost:8421/api/v1
Cloud Metadata Dashboard Base URL:
https://app.siwaan.com/api/v1

Authentication

Authenticate calls to both local and cloud endpoints using an API key passed in the authorization header prefix. Your key should remain secure at all times.

Example Ping Query:
curl -H "Authorization: Bearer sk_live_yourkeyhere" http://localhost:8421/api/v1/ping

Core Endpoints

GET/attrition/risk/{employee_id}

Queries the local machine learning engine to return the live attrition risk score and contributing SHAP drivers for a specific employee.

Example JSON Response:
{ "employee_id": "emp_4821", "risk_score": 0.86, "risk_label": "HIGH", "drivers": [ { "feature": "bench_days", "weight": 0.34, "value": 14 }, { "feature": "wsr_sentiment", "weight": 0.28, "value": -0.41 }, { "feature": "peer_departure_rate", "weight": 0.16, "value": 0.22 } ], "computed_at": "2026-07-09T05:00:00Z" }
GET/bench/summary

Returns an active summary list of all bench personnel, sorted automatically by billing idle time.

SDKs & Client Libraries

Deploy integrations faster using our pre-built Python client wrapper package.

# Install package
pip install siwaan
# Initialize Client
from siwaan import Client
client = Client(api_key="sk_...", host="http://localhost:8421")
risk = client.attrition.get_risk("emp_4821")

Rate Limits

Because queries to the local agent run on your own hardware containers, there are no local rate limits. The cloud dashboard API endpoint maintains a ceiling limit of 1,000 requests/hour per master API key.

Request Developer Sandbox Access

The Siwaan API and Python SDK libraries are available to customers on our Enterprise subscription plans. Contact our product alignment engineering desk to request access keys.

Request API Access Key