API Documentation

Blocklist Manager API Documentation

Version 1.0

Base URL: http://blocklist.gixed.com/api

This API provides access to the Blocklist Manager blocklist management system.

Authentication

Authentication is required for most endpoints. Include the token in the Authorization header.

Authorization: Bearer YOUR_API_TOKEN

Authentication

POST /auth/register
Register a new user
Parameters
Name Description
username The username (required)
email The email address (required)
password The password (required)
Example Request
{
    "username": "johndoe",
    "email": "john@example.com",
    "password": "securepassword"
}
Example Response
{
    "message": "Registration successful. Please check your email to verify your account.",
    "user": {
        "id": 123,
        "username": "johndoe",
        "email": "john@example.com",
        "role": "member"
    }
}
POST /auth/login
Login a user
Parameters
Name Description
username_email The username or email (required)
password The password (required)
Example Request
{
    "username_email": "john@example.com",
    "password": "securepassword"
}
Example Response
{
    "message": "Login successful",
    "user": {
        "id": 123,
        "username": "johndoe",
        "email": "john@example.com",
        "role": "member"
    },
    "token": "YOUR_API_TOKEN"
}
POST /auth/token
Generate an API token
Parameters
Name Description
username_email The username or email (required)
password The password (required)
Example Request
{
    "username_email": "john@example.com",
    "password": "securepassword"
}
Example Response
{
    "message": "Token generated successfully",
    "token": "YOUR_API_TOKEN",
    "expires_in": 2592000
}
POST /auth/logout Requires Authentication
Logout a user (revoke the token)
Example Request
[]
Example Response
{
    "message": "Logout successful"
}

Blocklists

GET /blocklists
Get all blocklists
Parameters
Name Description
page Page number (default: 1)
per_page Items per page (default: 10, max: 100)
search Search term
category_id Filter by category ID
type_id Filter by type ID
is_public Filter by public status (1 or 0)
created_by Filter by creator user ID
Example Response
{
    "blocklists": [
        {
            "id": 1,
            "name": "Ad Domains",
            "description": "List of advertising domains",
            "category_id": 2,
            "category_name": "Advertising",
            "type_id": 3,
            "type_name": "domain",
            "is_public": 1,
            "created_by": 123,
            "creator_name": "johndoe",
            "created_at": "2023-01-01 12:00:00",
            "updated_at": "2023-01-01 12:00:00",
            "entry_count": 1500
        }
    ],
    "pagination": {
        "current_page": 1,
        "total_pages": 5,
        "items_per_page": 10,
        "total_items": 50
    }
}
GET /blocklists/{id}
Get a specific blocklist
Example Response
{
    "id": 1,
    "name": "Ad Domains",
    "description": "List of advertising domains",
    "category_id": 2,
    "category_name": "Advertising",
    "type_id": 3,
    "type_name": "domain",
    "is_public": 1,
    "created_by": 123,
    "creator_name": "johndoe",
    "created_at": "2023-01-01 12:00:00",
    "updated_at": "2023-01-01 12:00:00"
}
POST /blocklists Requires Authentication
Create a new blocklist
Parameters
Name Description
name The blocklist name (required)
description The blocklist description
category_id The category ID (required)
type_id The type ID (required)
is_public Whether the blocklist is public (default: false)
Example Request
{
    "name": "Ad Domains",
    "description": "List of advertising domains",
    "category_id": 2,
    "type_id": 3,
    "is_public": true
}
Example Response
{
    "id": 1,
    "name": "Ad Domains",
    "description": "List of advertising domains",
    "category_id": 2,
    "category_name": "Advertising",
    "type_id": 3,
    "type_name": "domain",
    "is_public": 1,
    "created_by": 123,
    "creator_name": "johndoe",
    "created_at": "2023-01-01 12:00:00",
    "updated_at": "2023-01-01 12:00:00"
}
PUT /blocklists/{id} Requires Authentication
Update a blocklist
Parameters
Name Description
name The blocklist name
description The blocklist description
category_id The category ID
type_id The type ID
is_public Whether the blocklist is public
Example Request
{
    "name": "Updated Ad Domains",
    "is_public": false
}
Example Response
{
    "id": 1,
    "name": "Updated Ad Domains",
    "description": "List of advertising domains",
    "category_id": 2,
    "category_name": "Advertising",
    "type_id": 3,
    "type_name": "domain",
    "is_public": 0,
    "created_by": 123,
    "creator_name": "johndoe",
    "created_at": "2023-01-01 12:00:00",
    "updated_at": "2023-01-01 12:30:00"
}
DELETE /blocklists/{id} Requires Authentication
Delete a blocklist
Example Response
{
    "message": "Blocklist deleted successfully"
}
GET /blocklists/{id}/entries
Get entries for a blocklist
Parameters
Name Description
page Page number (default: 1)
per_page Items per page (default: 50, max: 1000)
search Search term
Example Response
{
    "blocklist": {
        "id": 1,
        "name": "Ad Domains",
        "description": "List of advertising domains",
        "category_id": 2,
        "category_name": "Advertising",
        "type_id": 3,
        "type_name": "domain",
        "is_public": 1,
        "created_by": 123,
        "creator_name": "johndoe",
        "created_at": "2023-01-01 12:00:00",
        "updated_at": "2023-01-01 12:00:00"
    },
    "entries": [
        {
            "id": 1,
            "blocklist_id": 1,
            "value": "ads.example.com",
            "comment": "Example ad domain",
            "created_by": 123,
            "creator_name": "johndoe",
            "created_at": "2023-01-01 12:00:00"
        }
    ],
    "pagination": {
        "current_page": 1,
        "total_pages": 30,
        "items_per_page": 50,
        "total_items": 1500
    },
    "total_entries": 1500
}
POST /blocklists/{id}/entries Requires Authentication
Add an entry to a blocklist
Parameters
Name Description
value The entry value (required)
comment Comment for the entry
Example Request
{
    "value": "ads.example.com",
    "comment": "Example ad domain"
}
Example Response
{
    "message": "Entry added successfully",
    "entry_id": 1
}
DELETE /blocklists/{id}/entries Requires Authentication
Delete an entry from a blocklist
Parameters
Name Description
entry_id The entry ID (required)
Example Response
{
    "message": "Entry deleted successfully"
}
POST /blocklists/{id}/import Requires Authentication
Import entries to a blocklist
Parameters
Name Description
content The content to import (required)
cidr Whether to parse CIDR notation (for IP blocklists)
wildcard Whether to parse wildcard patterns (for domain blocklists)
Example Request
{
    "content": "ads.example.com\ntracking.example.com",
    "wildcard": false
}
Example Response
{
    "message": "Import completed successfully",
    "stats": {
        "total": 2,
        "added": 2,
        "skipped": 0,
        "invalid": 0
    }
}
POST /blocklists/{id}/export Requires Authentication
Export a blocklist
Parameters
Name Description
format_id The export format ID (required)
Example Request
{
    "format_id": 1
}
Example Response
{
    "content": "ads.example.com\ntracking.example.com",
    "filename": "ad-domains.txt",
    "format": "Plain Text",
    "mime_type": "text\/plain"
}

Categories

GET /categories
Get all categories
Example Response
{
    "categories": [
        {
            "id": 1,
            "name": "Advertising",
            "description": "Advertising domains and IPs",
            "created_by": 1,
            "created_at": "2023-01-01 12:00:00",
            "updated_at": "2023-01-01 12:00:00",
            "blocklist_count": 5
        }
    ]
}
GET /categories/{id}
Get a specific category
Example Response
{
    "id": 1,
    "name": "Advertising",
    "description": "Advertising domains and IPs",
    "created_by": 1,
    "created_at": "2023-01-01 12:00:00",
    "updated_at": "2023-01-01 12:00:00"
}
POST /categories Requires Authentication
Create a new category (admin only)
Parameters
Name Description
name The category name (required)
description The category description
Example Request
{
    "name": "Malware",
    "description": "Malware domains and IPs"
}
Example Response
{
    "id": 2,
    "name": "Malware",
    "description": "Malware domains and IPs",
    "created_by": 1,
    "created_at": "2023-01-01 12:30:00",
    "updated_at": "2023-01-01 12:30:00"
}
PUT /categories/{id} Requires Authentication
Update a category (admin only)
Parameters
Name Description
name The category name
description The category description
Example Request
{
    "name": "Updated Malware",
    "description": "Updated description"
}
Example Response
{
    "id": 2,
    "name": "Updated Malware",
    "description": "Updated description",
    "created_by": 1,
    "created_at": "2023-01-01 12:30:00",
    "updated_at": "2023-01-01 13:00:00"
}
DELETE /categories/{id} Requires Authentication
Delete a category (admin only)
Example Response
{
    "message": "Category deleted successfully"
}

Types

GET /types
Get all blocklist types
Example Response
{
    "types": [
        {
            "id": 1,
            "name": "email",
            "description": "Email addresses",
            "validation_regex": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$",
            "created_at": "2023-01-01 12:00:00",
            "updated_at": "2023-01-01 12:00:00",
            "blocklist_count": 3
        }
    ]
}
GET /types/{id}
Get a specific blocklist type
Example Response
{
    "id": 1,
    "name": "email",
    "description": "Email addresses",
    "validation_regex": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$",
    "created_at": "2023-01-01 12:00:00",
    "updated_at": "2023-01-01 12:00:00"
}

Formats

GET /formats
Get all export formats
Example Response
{
    "formats": [
        {
            "id": 1,
            "name": "Plain Text",
            "description": "Simple list of entries, one per line",
            "format_template": "{entry}",
            "file_extension": "txt",
            "created_at": "2023-01-01 12:00:00",
            "updated_at": "2023-01-01 12:00:00"
        }
    ]
}
GET /formats/{id}
Get a specific export format
Example Response
{
    "id": 1,
    "name": "Plain Text",
    "description": "Simple list of entries, one per line",
    "format_template": "{entry}",
    "file_extension": "txt",
    "created_at": "2023-01-01 12:00:00",
    "updated_at": "2023-01-01 12:00:00"
}

Users

GET /users Requires Authentication
Get all users (admin only)
Parameters
Name Description
page Page number (default: 1)
per_page Items per page (default: 10, max: 100)
search Search term
role Filter by role (admin or member)
verified Filter by verification status (1 or 0)
Example Response
{
    "users": [
        {
            "id": 1,
            "username": "admin",
            "email": "admin@example.com",
            "role": "admin",
            "email_verified": 1,
            "last_login": "2023-01-01 12:00:00",
            "created_at": "2023-01-01 12:00:00",
            "updated_at": "2023-01-01 12:00:00"
        }
    ],
    "pagination": {
        "current_page": 1,
        "total_pages": 5,
        "items_per_page": 10,
        "total_items": 50
    }
}
GET /users/{id} Requires Authentication
Get a specific user (admin or own user)
Example Response
{
    "id": 1,
    "username": "admin",
    "email": "admin@example.com",
    "role": "admin",
    "email_verified": 1,
    "last_login": "2023-01-01 12:00:00",
    "created_at": "2023-01-01 12:00:00",
    "updated_at": "2023-01-01 12:00:00"
}
GET /users/me Requires Authentication
Get the current user
Example Response
{
    "id": 123,
    "username": "johndoe",
    "email": "john@example.com",
    "role": "member",
    "email_verified": 1,
    "last_login": "2023-01-01 12:00:00",
    "created_at": "2023-01-01 12:00:00",
    "updated_at": "2023-01-01 12:00:00"
}
PUT /users/{id} Requires Authentication
Update a user (admin or own user)
Parameters
Name Description
username The username
email The email address
role The role (admin only)
Example Request
{
    "username": "newusername"
}
Example Response
{
    "id": 123,
    "username": "newusername",
    "email": "john@example.com",
    "role": "member",
    "email_verified": 1,
    "last_login": "2023-01-01 12:00:00",
    "created_at": "2023-01-01 12:00:00",
    "updated_at": "2023-01-01 13:00:00"
}
DELETE /users/{id} Requires Authentication
Delete a user (admin only)
Example Response
{
    "message": "User deleted successfully"
}
GET /users/{id}/blocklists Requires Authentication
Get blocklists for a user (admin or own user)
Parameters
Name Description
page Page number (default: 1)
per_page Items per page (default: 10, max: 100)
search Search term
category_id Filter by category ID
type_id Filter by type ID
is_public Filter by public status (1 or 0)
Example Response
{
    "blocklists": [
        {
            "id": 1,
            "name": "Ad Domains",
            "description": "List of advertising domains",
            "category_id": 2,
            "category_name": "Advertising",
            "type_id": 3,
            "type_name": "domain",
            "is_public": 1,
            "created_by": 123,
            "creator_name": "johndoe",
            "created_at": "2023-01-01 12:00:00",
            "updated_at": "2023-01-01 12:00:00",
            "entry_count": 1500
        }
    ],
    "pagination": {
        "current_page": 1,
        "total_pages": 5,
        "items_per_page": 10,
        "total_items": 50
    }
}