API Reference
Complete documentation for the Costif.ai REST API. Integrate software asset management, cost optimization, and compliance tracking into your workflows.
Base URL
https://api.costif.ai/api/v1
Authentication
Most API endpoints require authentication via a Bearer token. Include your access token in the Authorization header:
Obtain an access token by calling /api/v1/auth/login with your credentials.
API Tester
Authentication
1 endpointsAuthenticate to receive an access token for API requests
Authenticate with email and password to receive a JWT access token. The token should be included in the Authorization header for all authenticated API requests.
Request Body
{
"email": "user@company.com",
"password": "your_password"
}Response
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "bearer",
"expires_in": 86400
}Examples
Loading...Loading...Users
5 endpointsUser management within your organization
Get all users in your organization with optional filtering and pagination.
Query Parameters
| Name | Type | Description |
|---|---|---|
| search | string | Search by name or email |
| role | string | Filter by role: admin, user_admin, agent_admin, read_only |
| limit | integer | Results per page (default: 50) |
| offset | integer | Pagination offset |
Response
{
"users": [
{
"id": "...",
"email": "...",
"full_name": "...",
"role": "admin"
}
],
"total": 15
}Examples
Loading...Loading...Invite a new user to your organization. Requires user_admin or admin role.
Request Body
{
"email": "newuser@company.com",
"full_name": "Jane Smith",
"role": "read_only"
}Response
{
"id": "...",
"email": "newuser@company.com",
"full_name": "Jane Smith",
"role": "read_only",
"is_active": true
}Examples
Loading...Loading...Retrieve details for a specific user.
Response
{
"id": "...",
"email": "user@company.com",
"full_name": "John Doe",
"role": "admin",
"is_active": true,
"created_at": "2024-01-15T10:30:00Z"
}Examples
Loading...Loading...Update user details. Users can update their own profile, admins can update any user.
Request Body
{
"full_name": "John Updated",
"role": "user_admin"
}Response
{
"id": "...",
"full_name": "John Updated",
"role": "user_admin"
}Examples
Loading...Loading...Deactivate a user account. Requires admin role. Cannot delete yourself.
Response
{
"success": true
}Examples
Loading...Loading...Dashboard
2 endpointsOverview statistics and summaries
Retrieve comprehensive dashboard statistics including agent counts, software totals, cost savings, and trends.
Response
{
"total_agents": 156,
"active_agents": 142,
"total_software": 2847,
"enterprise_software": 89,
"potential_savings": 125000,
"realized_savings": 87500,
"compliance_score": 94,
"last_scan": "2024-01-20T14:30:00Z"
}Examples
Loading...Loading...Get a summary list of all agents with their status, last seen time, and software counts.
Query Parameters
| Name | Type | Description |
|---|---|---|
| status | string | Filter: online, offline, all |
| limit | integer | Results per page |
Response
[
{
"id": "...",
"hostname": "workstation-001",
"os": "Windows 11",
"status": "online",
"last_seen": "2024-01-20T14:30:00Z",
"software_count": 47
}
]Examples
Loading...Loading...Agents
6 endpointsManage deployed agents and trigger scans
Retrieve comprehensive details about a specific agent including hardware specs, installed software, and scan history.
Response
{
"id": "...",
"hostname": "workstation-001",
"os": "Windows 11 Pro",
"os_version": "10.0.22631",
"architecture": "x64",
"cpu": "Intel Core i7-12700K",
"memory_gb": 32,
"status": "online",
"last_seen": "2024-01-20T14:30:00Z",
"agent_version": "1.2.0",
"software": [
{
"name": "Microsoft Office",
"version": "365"
}
]
}Examples
Loading...Loading...Remove an agent and all associated data. This action cannot be undone.
Response
{
"deleted": 1,
"message": "Agent deleted successfully"
}Examples
Loading...Loading...Delete multiple agents at once. Useful for cleanup operations.
Request Body
{
"agent_ids": [
"agent-id-1",
"agent-id-2"
]
}Response
{
"deleted": 2,
"message": "2 agents deleted successfully"
}Examples
Loading...Loading...Configure automatic scan schedule for an agent using cron syntax.
Request Body
{
"scan_schedule": "0 2 * * *",
"scan_enabled": true
}Response
{
"id": "...",
"scan_schedule": "0 2 * * *",
"scan_enabled": true
}Examples
Loading...Loading...Manually trigger an immediate scan on the specified agent.
Response
{
"success": true,
"message": "Scan initiated",
"scan_id": "..."
}Examples
Loading...Loading...Agent-only endpoint. Submit software scan results from an agent. Used by the Costif agent binary.
Request Body
{
"agent_id": "...",
"hostname": "workstation-001",
"software": [
{
"name": "Microsoft Office",
"version": "365",
"publisher": "Microsoft"
}
]
}Response
{
"success": true,
"software_count": 47
}Examples
Loading...Loading...Assets
6 endpointsSoftware and hardware asset management
Overview of asset counts, license compliance, and upcoming renewals.
Response
{
"total_software_assets": 89,
"total_hardware_assets": 156,
"expiring_soon": 5,
"total_license_cost": 450000,
"compliance_rate": 94.5
}Examples
Loading...Loading...Get software licenses expiring in the next 90 days.
Response
[
{
"id": "...",
"name": "Microsoft 365 E5",
"vendor": "Microsoft",
"renewal_date": "2024-03-15",
"annual_cost": 45000,
"days_until_renewal": 54
}
]Examples
Loading...Loading...Get all tracked software assets with license details.
Query Parameters
| Name | Type | Description |
|---|---|---|
| vendor | string | Filter by vendor name |
| category | string | Filter by category |
| search | string | Search by name |
Response
{
"assets": [
{
"id": "...",
"name": "Microsoft 365 E5",
"vendor": "Microsoft",
"license_type": "subscription",
"license_count": 500,
"used_count": 423,
"annual_cost": 45000,
"renewal_date": "2024-03-15"
}
],
"total": 89
}Examples
Loading...Loading...Add a new software asset to track licenses and costs.
Request Body
{
"name": "Adobe Creative Cloud",
"vendor": "Adobe",
"license_type": "subscription",
"license_count": 50,
"annual_cost": 35000,
"renewal_date": "2024-06-01"
}Response
{
"id": "...",
"name": "Adobe Creative Cloud"
}Examples
Loading...Loading...Get all tracked hardware assets.
Response
{
"assets": [
{
"id": "...",
"name": "Dell OptiPlex 7090",
"type": "desktop",
"serial_number": "ABC123",
"purchase_date": "2023-06-15",
"warranty_end": "2026-06-15"
}
],
"total": 156
}Examples
Loading...Loading...Upload supporting documents like contracts, invoices, or license certificates.
Request Body
{
"file": "(multipart file upload)",
"asset_type": "software",
"asset_id": "...",
"document_type": "contract"
}Response
{
"id": "...",
"filename": "contract.pdf",
"url": "/documents/..."
}Examples
Loading...Loading...Software Discovery
4 endpointsDiscovered software from agent scans
Overview of discovered software across all agents.
Response
{
"total_discovered": 2847,
"unique_applications": 312,
"enterprise_requiring_license": 89,
"potential_duplicates": 23
}Examples
Loading...Loading...Available filter values for software queries (vendors, categories, hosts).
Response
{
"vendors": [
"Microsoft",
"Adobe",
"Oracle"
],
"categories": [
"productivity",
"development",
"security"
],
"hosts": [
"workstation-001",
"server-prod-01"
]
}Examples
Loading...Loading...Search and filter all discovered software with pagination.
Query Parameters
| Name | Type | Description |
|---|---|---|
| search | string | Search in name, vendor, publisher |
| vendor | string | Filter by vendor |
| host_id | uuid | Filter by agent/host |
| enterprise_only | boolean | Only enterprise software |
| limit | integer | Results per page |
| offset | integer | Pagination offset |
Response
{
"software": [
{
"id": "...",
"name": "Microsoft Office 365",
"version": "16.0.17328",
"publisher": "Microsoft Corporation",
"install_date": "2024-01-10",
"host_count": 423,
"is_enterprise": true
}
],
"total": 2847
}Examples
Loading...Loading...Export discovered software to CSV or Excel format.
Query Parameters
| Name | Type | Description |
|---|---|---|
| format | string | csv or xlsx |
Examples
Loading...Loading...Reports
5 endpointsCustom report builder and scheduling
Get available data sources and fields for building reports.
Response
[
{
"id": "software",
"name": "Discovered Software",
"fields": [
{
"id": "name",
"name": "Name",
"type": "string"
},
{
"id": "version",
"name": "Version",
"type": "string"
},
{
"id": "install_date",
"name": "Install Date",
"type": "date"
}
]
}
]Examples
Loading...Loading...Get all saved report definitions.
Response
{
"reports": [
{
"id": "...",
"name": "Monthly Software Inventory",
"data_source": "software",
"created_at": "2024-01-15T10:30:00Z"
}
],
"total": 12
}Examples
Loading...Loading...Create a new report definition with selected fields and filters.
Request Body
{
"name": "Monthly Software Inventory",
"data_source": "software",
"columns": [
"name",
"version",
"host_count"
],
"filters": [
{
"field": "is_enterprise",
"operator": "eq",
"value": true
}
],
"sort_by": "name",
"sort_order": "asc"
}Response
{
"id": "...",
"name": "Monthly Software Inventory"
}Examples
Loading...Loading...Execute a report and get the results.
Response
{
"columns": [
"name",
"version",
"host_count"
],
"rows": [
[
"Microsoft Office",
"365",
423
],
[
"Adobe Acrobat",
"DC",
156
]
],
"total_rows": 89,
"generated_at": "2024-01-20T14:30:00Z"
}Examples
Loading...Loading...Schedule automatic report generation and delivery.
Request Body
{
"frequency": "weekly",
"day_of_week": 1,
"time": "09:00",
"recipients": [
"user@company.com"
],
"format": "xlsx"
}Response
{
"id": "...",
"next_run": "2024-01-22T09:00:00Z"
}Examples
Loading...Loading...Optimizations
4 endpointsCost optimization recommendations
Summary of optimization opportunities and realized savings.
Response
{
"total_opportunities": 47,
"potential_savings": 125000,
"realized_savings": 87500,
"by_category": {
"unused_licenses": 23,
"duplicate_software": 12,
"rightsizing": 8,
"vendor_consolidation": 4
}
}Examples
Loading...Loading...Get all cost optimization recommendations.
Query Parameters
| Name | Type | Description |
|---|---|---|
| category | string | Filter by category |
| status | string | Filter by status: pending, in_progress, implemented, dismissed |
| min_savings | number | Minimum savings amount |
Response
{
"optimizations": [
{
"id": "...",
"title": "Unused Microsoft 365 Licenses",
"description": "47 licenses have not been used in 90+ days",
"category": "unused_licenses",
"potential_savings": 28200,
"status": "pending",
"priority": "high"
}
],
"total": 47
}Examples
Loading...Loading...Manually create an optimization recommendation.
Request Body
{
"title": "Consolidate PDF Editors",
"description": "Multiple PDF editing tools in use",
"category": "duplicate_software",
"potential_savings": 5000,
"priority": "medium"
}Response
{
"id": "...",
"title": "Consolidate PDF Editors"
}Examples
Loading...Loading...Update the status of an optimization (implement, dismiss, etc.).
Request Body
{
"status": "implemented",
"realized_savings": 28200,
"notes": "Reclaimed 47 unused licenses"
}Response
{
"id": "...",
"status": "implemented",
"realized_savings": 28200
}Examples
Loading...Loading...Community
3 endpointsCommunity Q&A forum
Browse community questions with search and filtering.
Query Parameters
| Name | Type | Description |
|---|---|---|
| category | string | Filter by category |
| answered | boolean | Filter by answered status |
| search | string | Search in title and body |
Response
{
"questions": [
{
"id": "...",
"title": "How to configure firewall rules?",
"author_name": "John",
"category": "installation",
"is_answered": true,
"answer_count": 3,
"upvotes": 5
}
],
"total": 156
}Examples
Loading...Loading...Post a new question to the community.
Request Body
{
"author_name": "John Doe",
"author_email": "john@company.com",
"title": "How to configure firewall rules?",
"body": "I need to allow the agent through our firewall...",
"category": "installation"
}Response
{
"id": "...",
"title": "How to configure firewall rules?"
}Examples
Loading...Loading...Answer a community question.
Request Body
{
"author_name": "Jane Smith",
"author_email": "jane@company.com",
"body": "You need to allow outbound HTTPS on port 443..."
}Response
{
"id": "...",
"body": "You need to allow outbound HTTPS..."
}Examples
Loading...Loading...Bug Reports
2 endpointsPublic bug tracking
Browse reported bugs with filtering.
Query Parameters
| Name | Type | Description |
|---|---|---|
| category | string | Filter by category |
| severity | string | Filter: low, medium, high, critical |
| status | string | Filter: open, investigating, resolved, etc. |
Response
{
"bugs": [
{
"id": "...",
"title": "Dashboard not loading",
"severity": "high",
"status": "investigating",
"upvotes": 12
}
],
"total": 23
}Examples
Loading...Loading...Submit a new bug report.
Request Body
{
"reporter_name": "John Doe",
"reporter_email": "john@company.com",
"title": "Dashboard not loading",
"description": "The dashboard shows a blank page...",
"steps_to_reproduce": "1. Login\n2. Go to dashboard\n3. See blank page",
"severity": "high",
"category": "dashboard"
}Response
{
"id": "...",
"title": "Dashboard not loading"
}Examples
Loading...Loading...