Citizen-AI

API Endpoints

Complete reference for all CitizenAI API endpoints, including request/response formats, parameters, and examples.

Base URL

All endpoints are relative to the base API URL:

Production: https://your-domain.com/api/v1
Development: http://localhost:5000/api/v1

Authentication Endpoints

Authenticate a user and create a session.

POST /api/v1/auth/login

Request Body:

{
    "username": "string (required)",
    "password": "string (required)",
    "remember_me": "boolean (optional, default: false)"
}

Response (200 OK):

{
    "success": true,
    "data": {
        "user": {
            "id": "string",
            "username": "string",
            "role": "string",
            "permissions": ["string"]
        },
        "session": {
            "id": "string",
            "expires_at": "string (ISO 8601)"
        }
    }
}

Example:

curl -X POST http://localhost:5000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "password"
  }'

Logout

End the current user session.

POST /api/v1/auth/logout

Headers: Authorization: Bearer session-token

Response (200 OK):

{
    "success": true,
    "message": "Logged out successfully"
}

Validate Session

Check if current session is valid.

GET /api/v1/auth/validate

Headers: Authorization: Bearer session-token

Response (200 OK):

{
    "success": true,
    "data": {
        "valid": true,
        "user": {
            "id": "string",
            "username": "string",
            "role": "string"
        },
        "expires_at": "string (ISO 8601)"
    }
}

Chat Endpoints

Send Message

Send a message to the AI chat assistant.

POST /api/v1/chat/message

Headers: Authorization: Bearer api-key

Request Body:

{
    "message": "string (required, max: 500)",
    "session_id": "string (optional)",
    "context": "object (optional)"
}

Response (200 OK):

{
    "success": true,
    "data": {
        "response": "string",
        "confidence": "number (0-1)",
        "intent": "string",
        "sentiment": "string (positive|neutral|negative)",
        "session_id": "string",
        "conversation_id": "string"
    }
}

Example:

curl -X POST http://localhost:5000/api/v1/chat/message \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are your office hours?",
    "session_id": "session_123"
  }'

Get Chat History

Retrieve conversation history for a session.

GET /api/v1/chat/history

Headers: Authorization: Bearer api-key

Query Parameters:

session_id (string, required): Session identifier
limit (integer, optional, default: 50): Number of messages to return
offset (integer, optional, default: 0): Pagination offset

Response (200 OK):

{
    "success": true,
    "data": {
        "messages": [
            {
                "id": "string",
                "message": "string",
                "response": "string",
                "timestamp": "string (ISO 8601)",
                "intent": "string",
                "sentiment": "string"
            }
        ],
        "session_info": {
            "session_id": "string",
            "started_at": "string (ISO 8601)",
            "message_count": "integer"
        }
    },
    "pagination": {
        "page": 1,
        "per_page": 50,
        "total": 100,
        "pages": 2
    }
}

Create Chat Session

Start a new chat session.

POST /api/v1/chat/session

Headers: Authorization: Bearer api-key

Request Body:

{
    "user_id": "string (optional)",
    "context": "object (optional)"
}

Response (201 Created):

{
    "success": true,
    "data": {
        "session_id": "string",
        "created_at": "string (ISO 8601)",
        "expires_at": "string (ISO 8601)"
    }
}

Analytics Endpoints

Get Dashboard Data

Retrieve main dashboard metrics and charts.

GET /api/v1/analytics/dashboard

Headers: Authorization: Bearer api-key

Query Parameters:

date_range (string, optional, default: “7d”): Time range (1d, 7d, 30d, 90d, custom)
start_date (string, optional): Start date for custom range (YYYY-MM-DD)
end_date (string, optional): End date for custom range (YYYY-MM-DD)
metrics (string, optional): Comma-separated list of metrics

Response (200 OK):

{
    "success": true,
    "data": {
        "summary": {
            "total_conversations": 1250,
            "avg_response_time": 1.4,
            "satisfaction_score": 4.2,
            "resolution_rate": 87
        },
        "conversations": {
            "daily_counts": [45, 67, 89, 123, 98, 34, 28],
            "trend": "+15%"
        },
        "sentiment": {
            "positive": 65,
            "neutral": 25,
            "negative": 10
        },
        "concerns": {
            "total": 45,
            "resolved": 38,
            "pending": 7
        }
    }
}

Get Specific Metrics

Retrieve detailed metrics for specific data points.

GET /api/v1/analytics/metrics/{metric_type}

Headers: Authorization: Bearer api-key

Path Parameters:

metric_type (string): Type of metric (conversations, sentiment, concerns, performance)

Query Parameters:

granularity (string, optional, default: “daily”): Data granularity (hourly, daily, weekly, monthly)
start_date (string, required): Start date (YYYY-MM-DD)
end_date (string, required): End date (YYYY-MM-DD)
filters (string, optional): JSON-encoded filter object

Response (200 OK):

{
    "success": true,
    "data": {
        "metric_type": "conversations",
        "granularity": "daily",
        "data_points": [
            {
                "date": "2025-01-01",
                "value": 45,
                "metadata": {
                    "avg_duration": 300,
                    "unique_users": 32
                }
            }
        ],
        "aggregates": {
            "total": 1250,
            "average": 45.5,
            "peak": 123,
            "trend": "+15%"
        }
    }
}

Export Analytics Data

Export analytics data in various formats.

GET /api/v1/analytics/export

Headers: Authorization: Bearer api-key

Query Parameters:

format (string, required): Export format (csv, json, pdf, xlsx)
date_range (string, optional, default: “30d”): Time range
metrics (string, optional): Comma-separated metrics to include
include_details (boolean, optional, default: false): Include detailed breakdowns

Response (200 OK): Returns file download based on format requested.

Concerns Endpoints

List Concerns

Retrieve a list of concerns with filtering and pagination.

GET /api/v1/concerns

Headers: Authorization: Bearer api-key

Query Parameters:

status (string, optional): Filter by status (submitted, in_progress, resolved, closed)
category (string, optional): Filter by category
priority (string, optional): Filter by priority (low, medium, high, emergency)
limit (integer, optional, default: 20): Number of results per page
offset (integer, optional, default: 0): Pagination offset
sort (string, optional, default: “created_at”): Sort field
order (string, optional, default: “desc”): Sort order (asc, desc)

Response (200 OK):

{
    "success": true,
    "data": {
        "concerns": [
            {
                "id": "string",
                "tracking_number": "string",
                "title": "string",
                "description": "string",
                "category": "string",
                "priority": "string",
                "status": "string",
                "location": "string",
                "submitted_at": "string (ISO 8601)",
                "last_updated": "string (ISO 8601)",
                "estimated_resolution": "string (ISO 8601)"
            }
        ]
    },
    "pagination": {
        "page": 1,
        "per_page": 20,
        "total": 100,
        "pages": 5
    }
}

Create Concern

Submit a new concern.

POST /api/v1/concerns

Headers: Authorization: Bearer api-key

Request Body:

{
    "title": "string (required, max: 100)",
    "description": "string (required, max: 2000)",
    "category": "string (required)",
    "priority": "string (optional, default: medium)",
    "location": "string (optional)",
    "contact": {
        "email": "string (optional)",
        "phone": "string (optional)",
        "name": "string (optional)"
    },
    "anonymous": "boolean (optional, default: false)",
    "attachments": ["string (optional)"]
}

Response (201 Created):

{
    "success": true,
    "data": {
        "id": "string",
        "tracking_number": "string",
        "title": "string",
        "status": "submitted",
        "priority": "string",
        "estimated_resolution": "string (ISO 8601)",
        "created_at": "string (ISO 8601)"
    }
}

Get Concern Details

Retrieve detailed information about a specific concern.

GET /api/v1/concerns/{concern_id}

Headers: Authorization: Bearer api-key

Path Parameters:

concern_id (string): Concern ID or tracking number

Response (200 OK):

{
    "success": true,
    "data": {
        "id": "string",
        "tracking_number": "string",
        "title": "string",
        "description": "string",
        "category": "string",
        "priority": "string",
        "status": "string",
        "location": "string",
        "contact": "object",
        "submitted_at": "string (ISO 8601)",
        "last_updated": "string (ISO 8601)",
        "estimated_resolution": "string (ISO 8601)",
        "updates": [
            {
                "id": "string",
                "timestamp": "string (ISO 8601)",
                "status": "string",
                "message": "string",
                "updated_by": "string"
            }
        ],
        "attachments": [
            {
                "id": "string",
                "filename": "string",
                "url": "string",
                "size": "integer",
                "uploaded_at": "string (ISO 8601)"
            }
        ]
    }
}

Update Concern

Update concern status and add comments (admin only).

PUT /api/v1/concerns/{concern_id}

Headers: Authorization: Bearer api-key

Path Parameters:

concern_id (string): Concern ID

Request Body:

{
    "status": "string (optional)",
    "priority": "string (optional)",
    "message": "string (optional)",
    "estimated_resolution": "string (optional, ISO 8601)",
    "assigned_to": "string (optional)",
    "internal_notes": "string (optional)"
}

Response (200 OK):

{
    "success": true,
    "data": {
        "id": "string",
        "status": "string",
        "last_updated": "string (ISO 8601)",
        "message": "Concern updated successfully"
    }
}

Delete Concern

Delete a concern (admin only).

DELETE /api/v1/concerns/{concern_id}

Headers: Authorization: Bearer api-key

Response (200 OK):

{
    "success": true,
    "message": "Concern deleted successfully"
}

Users Endpoints

List Users

Retrieve list of users (admin only).

GET /api/v1/users

Headers: Authorization: Bearer api-key

Query Parameters:

role (string, optional): Filter by role
active (boolean, optional): Filter by active status
limit (integer, optional, default: 50): Results per page
offset (integer, optional, default: 0): Pagination offset

Response (200 OK):

{
    "success": true,
    "data": {
        "users": [
            {
                "id": "string",
                "username": "string",
                "email": "string",
                "role": "string",
                "active": "boolean",
                "created_at": "string (ISO 8601)",
                "last_login": "string (ISO 8601)"
            }
        ]
    },
    "pagination": {
        "page": 1,
        "per_page": 50,
        "total": 25,
        "pages": 1
    }
}

Create User

Create a new user account (admin only).

POST /api/v1/users

Headers: Authorization: Bearer api-key

Request Body:

{
    "username": "string (required)",
    "email": "string (required)",
    "password": "string (required)",
    "role": "string (required)",
    "active": "boolean (optional, default: true)"
}

Response (201 Created):

{
    "success": true,
    "data": {
        "id": "string",
        "username": "string",
        "email": "string",
        "role": "string",
        "active": "boolean",
        "created_at": "string (ISO 8601)"
    }
}

Get User Details

Get detailed user information.

GET /api/v1/users/{user_id}

Headers: Authorization: Bearer api-key

Response (200 OK):

{
    "success": true,
    "data": {
        "id": "string",
        "username": "string",
        "email": "string",
        "role": "string",
        "active": "boolean",
        "permissions": ["string"],
        "created_at": "string (ISO 8601)",
        "last_login": "string (ISO 8601)",
        "profile": {
            "first_name": "string",
            "last_name": "string",
            "department": "string"
        }
    }
}

Update User

Update user information.

PUT /api/v1/users/{user_id}

Headers: Authorization: Bearer api-key

Request Body:

{
    "email": "string (optional)",
    "role": "string (optional)",
    "active": "boolean (optional)",
    "profile": "object (optional)"
}

Response (200 OK):

{
    "success": true,
    "data": {
        "id": "string",
        "message": "User updated successfully"
    }
}

Delete User

Delete a user account (admin only).

DELETE /api/v1/users/{user_id}

Headers: Authorization: Bearer api-key

Response (200 OK):

{
    "success": true,
    "message": "User deleted successfully"
}

System Endpoints

Health Check

Check system health and status.

GET /api/v1/system/health

Response (200 OK):

{
    "success": true,
    "data": {
        "status": "healthy",
        "timestamp": "string (ISO 8601)",
        "version": "string",
        "uptime": "integer (seconds)",
        "components": {
            "database": "healthy",
            "watson_api": "healthy",
            "file_storage": "healthy"
        },
        "metrics": {
            "memory_usage": "512MB",
            "cpu_usage": "15%",
            "disk_usage": "45%"
        }
    }
}

System Information

Get system configuration and information (admin only).

GET /api/v1/system/info

Headers: Authorization: Bearer api-key

Response (200 OK):

{
    "success": true,
    "data": {
        "version": "string",
        "build": "string",
        "environment": "string",
        "features": ["string"],
        "limits": {
            "max_file_size": "10MB",
            "rate_limit": "1000/hour",
            "session_timeout": "30 minutes"
        }
    }
}

WebSocket Endpoints

Real-time Chat

Establish WebSocket connection for real-time chat.

// WebSocket connection
const ws = new WebSocket('ws://localhost:5000/api/v1/ws/chat');

// Send message
ws.send(JSON.stringify({
    type: 'message',
    session_id: 'session_123',
    message: 'Hello'
}));

// Receive response
ws.onmessage = function(event) {
    const data = JSON.parse(event.data);
    console.log('AI Response:', data.response);
};

Real-time Notifications

Subscribe to system notifications.

// WebSocket connection for notifications
const ws = new WebSocket('ws://localhost:5000/api/v1/ws/notifications');

// Authentication
ws.send(JSON.stringify({
    type: 'auth',
    token: 'your-api-key'
}));

// Receive notifications
ws.onmessage = function(event) {
    const notification = JSON.parse(event.data);
    console.log('Notification:', notification);
};

Error Responses

All endpoints may return error responses in this format:

{
    "success": false,
    "error": {
        "code": "ERROR_CODE",
        "message": "Human readable error message",
        "details": "object (optional additional details)"
    },
    "metadata": {
        "timestamp": "string (ISO 8601)",
        "request_id": "string"
    }
}

Common HTTP Status Codes

Status	Description	When Used
200	OK	Request successful
201	Created	Resource created successfully
400	Bad Request	Invalid request parameters
401	Unauthorized	Authentication required
403	Forbidden	Insufficient permissions
404	Not Found	Resource not found
422	Unprocessable Entity	Validation errors
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error

SDKs and Code Examples

Python SDK

from citizenai import CitizenAI

# Initialize client
client = CitizenAI(
    api_key='your-api-key',
    base_url='http://localhost:5000/api/v1'
)

# Send chat message
response = client.chat.send_message(
    message="What are your office hours?",
    session_id="session_123"
)

# Get analytics
metrics = client.analytics.get_dashboard_metrics(
    date_range='7d'
)

# Create concern
concern = client.concerns.create(
    title="Broken street light",
    description="Street light on Main St is not working",
    category="infrastructure"
)

JavaScript SDK

import { CitizenAI } from '@citizenai/sdk';

const client = new CitizenAI({
    apiKey: 'your-api-key',
    baseUrl: 'http://localhost:5000/api/v1'
});

// Send chat message
const response = await client.chat.sendMessage({
    message: 'How do I apply for a permit?',
    sessionId: 'session_123'
});

// Get analytics
const metrics = await client.analytics.getDashboardMetrics({
    dateRange: '7d'
});

// Create concern
const concern = await client.concerns.create({
    title: 'Pothole on Oak Street',
    category: 'infrastructure'
});

Testing the API

Using curl

# Test authentication
curl -X POST http://localhost:5000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "password"}'

# Test chat endpoint
curl -X POST http://localhost:5000/api/v1/chat/message \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello", "session_id": "test_session"}'

# Test analytics endpoint
curl -X GET "http://localhost:5000/api/v1/analytics/dashboard?date_range=7d" \
  -H "Authorization: Bearer your-api-key"

Postman Collection

Import the CitizenAI Postman collection to test all endpoints:

Download collection: CitizenAI_API.postman_collection.json
Set environment variables:
- base_url: http://localhost:5000/api/v1
- api_key: Your API key
Run collection tests

Next Steps

Authentication - Detailed authentication guide
User Guide - Learn about platform features
Development Guide - API integration examples

This site is open source. Improve this page.

Citizen-AI

API Endpoints

Base URL

Authentication Endpoints

Login

Logout

Validate Session

Chat Endpoints

Send Message

Get Chat History

Create Chat Session

Analytics Endpoints

Get Dashboard Data

Get Specific Metrics

Export Analytics Data

Concerns Endpoints

List Concerns

Create Concern

Get Concern Details

Update Concern

Delete Concern

Users Endpoints

List Users

Create User

Get User Details

Update User

Delete User

System Endpoints

Health Check

System Information

WebSocket Endpoints

Real-time Chat

Real-time Notifications

Error Responses

Common HTTP Status Codes

SDKs and Code Examples

Python SDK

JavaScript SDK

Testing the API

Using curl

Postman Collection

Next Steps