REST API Reference

Base URL: https://api.doushi.ai/api
All requests must be made over HTTPS (TLS 1.3). Requests over unencrypted HTTP will fail.

Authentication

The backend supports two authentication methods depending on your integration:

1. API Key (Programmatic Integrations & CI/CD):
   Pass your API key in the X-API-Key header:

   X-API-Key: dsh_live_xxxxxxxxxxxxxxxxxxxxxxxx
   

   API keys can be generated and managed in your dashboard under Settings ➔ API Keys.

2. Bearer JWT Token (Web Frontend & Playground Sessions):
   When interacting with the platform via the browser web dashboard or interactive API Playground, requests are authenticated using standard AWS Cognito JWT tokens:

   Authorization: Bearer <COGNITO_JWT_TOKEN>
   

[!WARNING] Keep your secret API keys safe. Never commit keys to public GitHub repositories or expose them in client-side browser JavaScript.

---

Single Prediction Endpoint:

POST /api/projects/<YOUR_PROJECT_ID>/predict

Generates real-time predictions for a single record or small batch.

[!NOTE] <YOUR_PROJECT_ID> is a placeholder value representing your unique project ID (e.g. c7b39a4f-1234-4567-89ab-cdef01234567 or proj_12345).

Request Headers

Header	Value	Required
X-API-Key	<YOUR_API_KEY>	yes
Content-Type	application/json	yes

Query Parameters

• return_probabilities (boolean, optional): Set to true to return class probabilities alongside predictions.

Request Body Schema

{
  "feature_name_1": "float | int | string",
  "feature_name_2": "float | int | string"
}

Sample Request (cURL)

curl -X POST https://api.doushi.ai/api/projects/<YOUR_PROJECT_ID>/predict?return_probabilities=true \
  -H "X-API-Key: dsh_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "monthly_spend": 94.20,
    "tenure_months": 16,
    "support_tickets": 2,
    "contract_type": "month-to-month"
  }'

Response Schema (200 OK)

{
  "project_id": "<YOUR_PROJECT_ID>",
  "prediction": [0],
  "count": 1,
  "latency_ms": 13.8,
  "cache_tier": "DIRECT",
  "probabilities": [[0.716, 0.284]]
}

---

Batch Prediction Endpoint: POST /api/projects/<YOUR_PROJECT_ID>/predict/batch

High-throughput batch inference endpoint supporting JSON arrays or direct file uploads (.csv, .parquet, .xlsx, .jsonl). Also aliased as /batch-predict.

Sample Request (Python)

import requests

project_id = "<YOUR_PROJECT_ID>"
url = f"https://api.doushi.ai/api/projects/{project_id}/predict/batch"
headers = {
    "X-API-Key": "dsh_live_xxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json"
}

payload = [
    {"monthly_spend": 45.0, "tenure_months": 2, "support_tickets": 5, "contract_type": "month-to-month"},
    {"monthly_spend": 120.0, "tenure_months": 36, "support_tickets": 0, "contract_type": "two-year"},
    {"monthly_spend": 85.5, "tenure_months": 11, "support_tickets": 1, "contract_type": "annual"}
]

params = {
    "return_probabilities": "true",
    "include_inputs": "true"
}

response = requests.post(url, json=payload, headers=headers, params=params)
data = response.json()

print(f"Scored {data['count']} records in {data['latency_ms']}ms (Cache: {data['cache_tier']})")
for idx, item in enumerate(data.get("results", [])):
    print(f"Record {idx + 1}: Prediction={item['prediction']} (Prob: {item.get('probability')})")

---

TypeScript / Node.js Integration

import axios from 'axios';

interface PredictResponse {
  project_id: string;
  prediction: number[];
  count: number;
  latency_ms: number;
  cache_tier: string;
  probabilities?: number[][];
}

async function predictChurn(inputData: Record<string, any>): Promise<PredictResponse> {
  const projectId = process.env.DOUSHI_PROJECT_ID; // Your Project ID placeholder
  const { data } = await axios.post<PredictResponse>(
    `https://api.doushi.ai/api/projects/${projectId}/predict?return_probabilities=true`,
    inputData,
    {
      headers: {
        'X-API-Key': process.env.DOUSHI_API_KEY,
        'Content-Type': 'application/json',
      },
    }
  );

  return data;
}

---

Rate Limits & SLA

Plan	Rate Limit (req/sec)	Batch Limit (rows/call)	Uptime SLA
Free	5 req/sec	50 rows	Community Best Effort
Starter	25 req/sec	500 rows	99.5%
Professional	100 req/sec	2,500 rows	99.9%
Growth / Enterprise	1,000+ req/sec	25,000 rows	99.99% Dedicated

---

Error Handling

Standard HTTP status codes are returned:

Code	Status	Description
200	OK	Request succeeded
400	Bad Request	Missing required feature columns or invalid JSON
401	Unauthorized	Missing or invalid API key
404	Not Found	Specified project_id does not exist
429	Too Many Requests	Rate limit exceeded. Back off and retry
500	Internal Error	Server error. Contact support