API Reference

{
  "name": "Zamfara Health Bot",
  "type": "state_chatbot",
  "languages": ["en", "ha"],
  "welcome_message": "Welcome to Zamfara State Health Service. How can I help you today?",
  "config": {
    "tone": "friendly",
    "max_response_length": 500,
    "fallback_message": "I'm not sure about that. Please contact the helpline at 0800-ZAMFARA."
  }
}

{
  "id": "ast_zam_abc123",
  "name": "Zamfara Health Bot",
  "type": "state_chatbot",
  "status": "active",
  "languages": ["en", "ha"],
  "documents_count": 0,
  "conversations_count": 0,
  "created_at": "2026-02-27T10:30:00Z",
  "embed_code": "<script src='https://cdn.hiva.chat/widget/ast_zam_abc123.js'></script>"
}

{
  "data": [
    {
      "id": "ast_zam_abc123",
      "name": "Zamfara Health Bot",
      "type": "state_chatbot",
      "status": "active",
      "documents_count": 12,
      "conversations_count": 8450,
      "created_at": "2026-02-27T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 5,
    "total_pages": 1
  }
}

{
  "id": "ast_zam_abc123",
  "name": "Zamfara Health Bot",
  "type": "state_chatbot",
  "status": "active",
  "languages": ["en", "ha"],
  "welcome_message": "Welcome to Zamfara State Health Service.",
  "config": {
    "tone": "friendly",
    "max_response_length": 500,
    "fallback_message": "I'm not sure about that..."
  },
  "documents_count": 12,
  "conversations_count": 8450,
  "avg_satisfaction": 4.6,
  "resolution_rate": 0.89,
  "created_at": "2026-02-27T10:30:00Z",
  "updated_at": "2026-02-27T14:20:00Z"
}

{
  "name": "Zamfara State Health Assistant",
  "config": {
    "tone": "professional",
    "max_response_length": 800
  }
}

{
  "id": "ast_zam_abc123",
  "name": "Zamfara State Health Assistant",
  "status": "active",
  "updated_at": "2026-02-27T15:00:00Z"
}

{
  "deleted": true,
  "id": "ast_zam_abc123"
}

// multipart/form-data
curl -X POST https://api.hiva.chat/v1/assistants/ast_zam_abc123/documents \
  -H "Authorization: Bearer hiva_sk_live_..." \
  -F "file=@malaria_protocol_2026.pdf" \
  -F "category=clinical_guidelines" \
  -F "description=NCDC Malaria Treatment Protocol 2026" \
  -F "language=en"

{
  "id": "doc_xyz789",
  "assistant_id": "ast_zam_abc123",
  "filename": "malaria_protocol_2026.pdf",
  "category": "clinical_guidelines",
  "status": "processing",
  "pages": 45,
  "chunks": null,
  "estimated_processing_time": "120 seconds",
  "created_at": "2026-02-27T10:35:00Z"
}

{
  "data": [
    {
      "id": "doc_xyz789",
      "filename": "malaria_protocol_2026.pdf",
      "category": "clinical_guidelines",
      "status": "ready",
      "pages": 45,
      "chunks": 128,
      "created_at": "2026-02-27T10:35:00Z"
    },
    {
      "id": "doc_abc456",
      "filename": "nhis_drug_formulary.pdf",
      "category": "formulary",
      "status": "ready",
      "pages": 210,
      "chunks": 645,
      "created_at": "2026-02-25T08:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 12,
    "total_pages": 1
  }
}

{
  "deleted": true,
  "id": "doc_xyz789"
}

{
  "assistant_id": "ast_zam_abc123",
  "session_id": "sess_user_001",
  "message": "What is the recommended treatment for malaria in pregnancy?",
  "language": "en"
}

{
  "id": "msg_a1b2c3d4",
  "session_id": "sess_user_001",
  "assistant_id": "ast_zam_abc123",
  "response": "According to the NHIS guidelines and NCDC Malaria Treatment Protocol, the recommended first-line treatment for uncomplicated malaria in pregnancy depends on the trimester:\n\n• 1st trimester: Oral Quinine + Clindamycin for 7 days\n• 2nd & 3rd trimester: Artemether-Lumefantrine (ACT) for 3 days\n\nFor severe malaria in any trimester, IV Artesunate is recommended. Always confirm with the latest NCDC protocol updates and consult with the attending physician.",
  "sources": [
    {
      "document": "NCDC Malaria Treatment Protocol 2026",
      "page": 23,
      "relevance": 0.96
    },
    {
      "document": "NHIS Essential Drug List",
      "page": 45,
      "relevance": 0.91
    }
  ],
  "confidence": 0.94,
  "language": "en",
  "tokens_used": 342,
  "created_at": "2026-02-27T11:00:00Z"
}

{
  "session_id": "sess_user_001",
  "assistant_id": "ast_zam_abc123",
  "messages": [
    {
      "id": "msg_0001",
      "role": "user",
      "content": "What is the recommended treatment for malaria in pregnancy?",
      "created_at": "2026-02-27T11:00:00Z"
    },
    {
      "id": "msg_0002",
      "role": "assistant",
      "content": "According to the NHIS guidelines...",
      "sources": [...],
      "confidence": 0.94,
      "created_at": "2026-02-27T11:00:01Z"
    }
  ],
  "has_more": false
}

{
  "name": "Zamfara Enrollment DB",
  "engine": "postgresql",
  "host": "db.zamfara-health.gov.ng",
  "port": 5432,
  "database": "nhis_enrollment",
  "username": "hiva_readonly",
  "password": "••••••••",
  "ssl": true
}

{
  "id": "conn_pg_001",
  "name": "Zamfara Enrollment DB",
  "engine": "postgresql",
  "status": "connected",
  "tables_discovered": 24,
  "schema_indexed": true,
  "created_at": "2026-02-27T09:00:00Z"
}

{
  "connection_id": "conn_pg_001",
  "question": "How many beneficiaries enrolled in Zamfara this month, broken down by week?",
  "format": "chart"
}

{
  "id": "qry_abc123",
  "answer": "3,247 beneficiaries enrolled in Zamfara State in February 2026.",
  "data": [
    { "week": "Feb 3–9", "enrollments": 812 },
    { "week": "Feb 10–16", "enrollments": 956 },
    { "week": "Feb 17–23", "enrollments": 748 },
    { "week": "Feb 24–27", "enrollments": 731 }
  ],
  "sql": "SELECT date_trunc('week', enrolled_at) AS week, COUNT(*) AS enrollments FROM beneficiaries WHERE state = 'Zamfara' AND enrolled_at >= '2026-02-01' GROUP BY 1 ORDER BY 1;",
  "execution_time_ms": 45,
  "rows_returned": 4,
  "format": "chart",
  "created_at": "2026-02-27T11:15:00Z"
}

{
  "data": [
    {
      "id": "conn_pg_001",
      "name": "Zamfara Enrollment DB",
      "engine": "postgresql",
      "status": "connected",
      "tables_discovered": 24,
      "last_query_at": "2026-02-27T11:15:00Z"
    },
    {
      "id": "conn_mysql_002",
      "name": "Claims Processing DB",
      "engine": "mysql",
      "status": "connected",
      "tables_discovered": 18,
      "last_query_at": "2026-02-26T16:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 2,
    "total_pages": 1
  }
}

{
  "period": {
    "start": "2026-01-28T00:00:00Z",
    "end": "2026-02-27T23:59:59Z"
  },
  "summary": {
    "total_conversations": 12450,
    "total_messages": 38200,
    "unique_users": 8930,
    "resolution_rate": 0.89,
    "avg_satisfaction": 4.6,
    "avg_response_time_ms": 1200,
    "languages": {
      "en": 0.45,
      "ha": 0.32,
      "pcm": 0.15,
      "yo": 0.05,
      "ig": 0.03
    }
  },
  "time_series": [
    {
      "date": "2026-02-27",
      "conversations": 420,
      "messages": 1280,
      "satisfaction": 4.7
    }
  ]
}

{
  "data": [
    {
      "query": "How do I enroll in NHIS?",
      "count": 1240,
      "avg_confidence": 0.92,
      "resolved_rate": 0.95
    },
    {
      "query": "What drugs are covered under my plan?",
      "count": 890,
      "avg_confidence": 0.88,
      "resolved_rate": 0.87
    },
    {
      "query": "Where is the nearest accredited hospital?",
      "count": 756,
      "avg_confidence": 0.85,
      "resolved_rate": 0.82
    }
  ]
}

{
  "url": "https://your-app.com/webhooks/hiva",
  "events": [
    "assistant.created",
    "document.ready",
    "document.failed",
    "chat.message",
    "chat.feedback",
    "connection.status_changed",
    "query.completed"
  ]
}

{
  "id": "wh_001",
  "url": "https://your-app.com/webhooks/hiva",
  "events": ["assistant.created", "document.ready", ...],
  "secret": "whsec_abc123...",
  "status": "active",
  "created_at": "2026-02-27T09:00:00Z"
}

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// The signature is in the X-Hiva-Signature header