Interactive API Documentation
Phishmonger includes built-in interactive API documentation powered by Swagger UI:Complete Endpoint List
Browse all available API endpoints organized by category (Templates, Campaigns, Targets, Events)
Interactive Testing
Test API calls directly from the browser with “Try it out” functionality
Request Examples
View detailed request/response schemas and example payloads for every endpoint
OpenAPI Spec
Download the OpenAPI specification in JSON format for import into API clients
OpenAPI Specification
Access the raw OpenAPI 3.0 specification:- Import into Postman or Insomnia
- Generate API clients for various programming languages
- Integrate with API testing tools
- Reference for development
Authentication
All API endpoints (except/documentation) require cookie-based authentication.
Admin Cookie Authentication
Cookie Name:admin_cookie (configurable in config.json)
Cookie Value: Secret value from your config.json
Setting the Cookie:
Security Considerations
- Cookie is HttpOnly and Secure (HTTPS only)
- Valid for 1 year (max-age=31536000)
- Single authentication token for all API access
- No per-user or per-request tokens
API Categories
Phishmonger’s API is organized into four main categories:Templates
Manage reusable email templates. Key Endpoints:GET /list_templates- List all template namesGET /get_template- Retrieve template by namePOST /save_template- Create or update templateDELETE /delete_template- Remove template
Template
Campaigns
Create, configure, and manage phishing campaigns. Key Endpoints:GET /list_campaigns- List all campaignsGET /get_campaign- Get campaign detailsPOST /save_campaign- Create new campaignPUT /update_campaign- Modify campaignPUT /send_campaign- Start sending immediatelyPUT /schedule_campaign- Schedule for future startPUT /cancel_campaign- Stop campaignDELETE /delete_campaign- Delete campaign and dataPOST /send_test_email- Send test email
Campaign, Template (for test emails)
Targets
Manage target lists and recipient information. Key Endpoints:GET /get_targets- Get all targets for campaignGET /get_target_info- Get specific target detailsPOST /create_target- Add target to campaignDELETE /delete_target- Remove targetPUT /update_phished_status- Reset email sent status
Target
Events
Track and query campaign events and interactions. Key Endpoints:POST /create_event- Log new eventGET /get_campaign_events- Get all campaign eventsGET /get_target_events- Get events for specific targetGET /get_search_events- Search events with filtersPUT /ignore_event- Mark event as ignoredPUT /unignore_events- Restore ignored events
Event
Quick Start Examples
List All Campaigns
Create a Target
Log an Event
Start Campaign
HTTP Status Codes
| Status Code | Meaning |
|---|---|
| 200 OK | Request successful |
| 401 Unauthorized | Missing or invalid admin cookie |
| 404 Not Found | Endpoint does not exist |
| 500 Internal Server Error | Server error (check logs) |
Response Formats
All API endpoints return JSON (except error messages which may be plain text). Successful Response Example:Rate Limiting
Phishmonger does not implement built-in rate limiting. Consider:- Implementing rate limiting at the reverse proxy level (NGINX)
- Monitoring API usage and database performance
- Restricting API access to trusted IP addresses
- Using appropriate campaign delays to avoid overwhelming the server
API Clients
Generating Clients
Use the OpenAPI spec to generate clients for various languages:Postman Collection
Import the OpenAPI spec into Postman:- Open Postman
- Click “Import”
- Enter URL:
https://yourdomain.com/documentation/json - Postman generates a collection with all endpoints
- Configure “Cookie” header with your admin cookie value
API Best Practices
Security
Security
Always Use HTTPS: Never send API requests over HTTPProtect Admin Cookie: Store cookie value securely, never commit to source controlRotate Credentials: Periodically change admin cookie value in config.jsonIP Whitelisting: Restrict API access to known IP addresses at firewall level
Performance
Performance
Cache Responses: Cache template and campaign lists when possibleBatch Operations: Use bulk imports for targets instead of individual API callsMonitor Resources: Watch database size and server load during API-driven campaignsDatabase Queries: For complex analytics, query SQLite database directly
Error Handling
Error Handling
Check Status Codes: Always verify HTTP status before processing responseRetry Logic: Implement exponential backoff for transient failuresValidate Data: Verify response structure matches expected schemaLog Errors: Capture and log API errors for troubleshooting
Data Management
Data Management
Clean Up: Delete old campaigns and events regularlyExport Data: Archive important campaign data before deletionMonitor Size: Track database growth and optimize as neededBackup: Regular backups of database before bulk operations
Common Use Cases
Automated Target Import
Import targets from CSV programmatically:Campaign Monitoring Script
Monitor campaign progress in real-time:Export Campaign Results
Export campaign data to CSV:Additional Resources
OpenAPI Specification
Learn more about OpenAPI 3.0 specification format
Fastify OAS
Documentation for Phishmonger’s OpenAPI plugin
Postman
API development and testing platform
Insomnia
Alternative API client and testing tool
Support
For API-specific questions:- Review the interactive documentation at
/documentation - Check the OpenAPI spec for detailed schemas
- Refer to other documentation sections for operational guidance
- Report API bugs on GitHub