API Documentation

TL;DR

RESTful API for file sharing and bookmark management with JSON responses.

  • Base URL: /api
  • Authentication: Username/password via JSON body, POST data, Basic Auth header, or API key
  • Response Format: JSON
  • CORS: Enabled for all origins
  • Rate Limiting: None (please be reasonable)

Authentication

Most endpoints require authentication. You can authenticate in four ways:

1. API Key Authentication (Recommended)

Use an API key for secure, long-term access without exposing your password.

Via Header:

curl -H "X-API-Key: p404_5d106b399073f06b3c91cb9a2cd8011e92531cb6d44596af57a37d5776e9f2b0" \
  https://4-0-4.io/api/user/bookmarks

Via URL Parameter:

curl https://4-0-4.io/api/user/bookmarks?api_key=p404_5d106b399073f06b3c91cb9a2cd8011e92531cb6d44596af57a37d5776e9f2b0

Via JSON Body:

curl -X POST -H "Content-Type: application/json" \
  -d '{"api_key":"p404_5d106b399073f06b3c91cb9a2cd8011e92531cb6d44596af57a37d5776e9f2b0","title":"My Bookmark","url":"https://example.com"}' \
  https://4-0-4.io/api/links

2. JSON Body Authentication

curl -X POST -H "Content-Type: application/json" \
  -d '{"username":"testuser","password":"testpass","title":"My Bookmark","url":"https://example.com"}' \
  https://4-0-4.io/api/links

3. Basic Authentication Header

curl -u "testuser:testpass" \
  https://4-0-4.io/api/links

4. POST Data

curl -X POST -d "username=testuser&password=testpass&title=My Bookmark&url=https://example.com" \
  https://4-0-4.io/api/links

Response Format

All API responses are in JSON format with the following structure:

Success Response

{
  "status": "success",
  "message": "Operation completed successfully",
  "data": { ... }
}

Error Response

{
  "status": "error",
  "message": "Error description"
}

Endpoints

API Documentation

GET /api or /api/docs

Returns this API documentation in JSON format.

Authentication: None required

Example Request:
curl https://4-0-4.io/api

Authentication Endpoints

POST /api/auth/login

Authenticate user credentials and get user information.

Authentication: Username/password required

Example Request:
curl -X POST -H "Content-Type: application/json" \
  -d '{"username":"testuser","password":"testpass"}' \
  https://4-0-4.io/api/auth/login
Example Response:
{
  "status": "success",
  "message": "Authentication successful",
  "data": {
    "user_id": 11,
    "username": "testuser",
    "is_admin": false
  }
}

API Key Management Endpoints

POST /api/auth/keys

Generate a new API key for the authenticated user.

Authentication: Username/password required (cannot use API key to create another key)

Parameters:
  • name (optional): Name for the API key (default: "API Key")
  • expires_at (optional): Expiration date (YYYY-MM-DD HH:MM:SS, default: 1 year)
Example Request:
curl -X POST -H "Content-Type: application/json" \
  -d '{"username":"testuser","password":"testpass","name":"Production API Key"}' \
  https://4-0-4.io/api/auth/keys
Example Response:
{
  "status": "success",
  "message": "API key generated successfully",
  "data": {
    "id": 1,
    "key": "p404_abc123def456...",
    "name": "Production API Key",
    "expires_at": "2026-07-02 12:00:00"
  }
}

Important: Store this key securely! It will not be shown again.

GET /api/auth/keys

List all API keys for the authenticated user.

Authentication: Username/password or API key

Example Request:
curl -u "testuser:testpass" https://4-0-4.io/api/auth/keys
Example Response:
{
  "status": "success",
  "data": [
    {
      "id": 5,
      "key_prefix": "p404_5d106b3",
      "name": "test",
      "created_at": "2025-07-21 17:35:25",
      "last_used_at": null,
      "expires_at": "2026-07-21 17:35:25",
      "is_active": 1
    }
  ]
}

DELETE /api/auth/keys/{id}

Revoke (deactivate) an API key. The key will stop working immediately but remain in the database for audit purposes.

Authentication: Username/password or API key (different from the one being deleted)

Example Request:
curl -X DELETE -u "testuser:testpass" https://4-0-4.io/api/auth/keys/5
Example Response:
{
  "status": "success",
  "message": "API key revoked successfully"
}

DELETE /api/auth/keys/{id}/permanent

Permanently delete a revoked API key from the database. This can only be done on keys that are already revoked.

Authentication: Username/password or API key (different from the one being deleted)

Example Request:
curl -X DELETE -u "testuser:testpass" https://4-0-4.io/api/auth/keys/1/permanent
Example Response:
{
  "status": "success",
  "message": "API key deleted permanently"
}

Note: This action is irreversible. The key must be revoked first before it can be permanently deleted.

Bookmark Endpoints

GET /api/links

Get all public bookmarks.

Authentication: None required

Example Request:
curl https://4-0-4.io/api/links
Example Response:
{
  "status": "success",
  "data": [
    {
      "id": 1,
      "title": "Example Site",
      "url": "https://example.com",
      "description": "A sample website",
      "created_at": "2025-07-02 12:00:00"
    }
  ]
}

POST /api/links

Create a new bookmark.

Authentication: Required

Parameters:
  • title (required): Bookmark title
  • url (required): URL to bookmark
  • description (optional): Bookmark description
  • is_public (optional): Make bookmark public (0 or 1, default: 0)
Example Request:
curl -X POST -H "Content-Type: application/json" \
  -d '{"username":"testuser","password":"testpass","title":"My Site","url":"https://mysite.com","description":"My personal website","is_public":1}' \
  https://4-0-4.io/api/links

GET /api/user/bookmarks

Get all bookmarks for the authenticated user (both public and private).

Authentication: Required

Example Request:
curl -u "testuser:testpass" https://4-0-4.io/api/user/bookmarks

DELETE /api/links/{id}

Delete a bookmark. Only the owner or admin can delete bookmarks.

Authentication: Required

Example Request:
curl -X DELETE -u "testuser:testpass" https://4-0-4.io/api/links/123

File Endpoints

GET /api/files

Get list of all public files with metadata.

Authentication: None required

Example Request:
curl https://4-0-4.io/api/files
Example Response:
{
  "status": "success",
  "data": [
    {
      "slug": "abc123def456",
      "original_name": "example.txt",
      "size": 1024,
      "mime": "text/plain",
      "extension": "txt",
      "downloads": 5,
      "created_at": "2025-07-02 12:00:00",
      "expires_at": "2025-08-02 12:00:00",
      "download_url": "/file/abc123def456",
      "preview_url": "/preview/abc123def456"
    }
  ]
}

POST /api/files

Upload a new file.

Authentication: Required

Content-Type: multipart/form-data

Parameters:
  • file (required): File to upload (max 100MB)
  • password (optional): Password to encrypt the file
  • expires_at (optional): Expiration date (YYYY-MM-DD HH:MM:SS)
  • username (required): Your username
  • password (required): Your password
Example Request:
curl -X POST -F "file=@example.txt" -F "username=testuser" -F "password=testpass" \
  https://4-0-4.io/api/files
Example Response:
{
  "status": "success",
  "message": "File uploaded",
  "data": {
    "slug": "abc123def456",
    "download_url": "/file/abc123def456",
    "preview_url": "/preview/abc123def456"
  }
}

GET /api/files/{slug}

Download a file by its slug. This will initiate the file download.

Authentication: None required (unless file is password protected)

Example Request:
curl -O https://4-0-4.io/api/files/abc123def456

GET /api/user/files

Get all files uploaded by the authenticated user.

Authentication: Required

Example Request:
curl -u "testuser:testpass" https://4-0-4.io/api/user/files

DELETE /api/files/{slug}

Delete a file. Only the owner or admin can delete files.

Authentication: Required

Example Request:
curl -X DELETE -u "testuser:testpass" https://4-0-4.io/api/files/abc123def456

HTTP Status Codes

  • 200 OK: Request successful
  • 400 Bad Request: Invalid request parameters
  • 401 Unauthorized: Authentication required or invalid credentials
  • 403 Forbidden: Permission denied
  • 404 Not Found: Resource not found
  • 405 Method Not Allowed: HTTP method not supported for this endpoint
  • 500 Internal Server Error: Server error

Examples

Complete Workflow Example

Here's a complete example of uploading a file and creating a bookmark:

1. Test Authentication

curl -X POST -H "Content-Type: application/json" \
  -d '{"username":"testuser","password":"testpass"}' \
  https://4-0-4.io/api/auth/login

2. Upload a File

curl -X POST -F "file=@document.pdf" -F "username=testuser" -F "password=testpass" \
  https://4-0-4.io/api/files

3. Create a Public Bookmark

curl -X POST -H "Content-Type: application/json" \
  -d '{"username":"testuser","password":"testpass","title":"Important Document","url":"https://4-0-4.io/file/abc123def456","is_public":1}' \
  https://4-0-4.io/api/links

4. List Your Files

curl -u "testuser:testpass" https://4-0-4.io/api/user/files

5. List Your Bookmarks

curl -u "testuser:testpass" https://4-0-4.io/api/user/bookmarks

Notes

  • URLs in bookmarks will automatically have http:// prepended if no protocol is specified
  • File uploads support password protection which encrypts the file at rest
  • Maximum file size is 100MB
  • Files can expire automatically (up to 2 years for anonymous users, 10 years for logged-in users)
  • All API responses include CORS headers for cross-origin requests
  • The API supports JSON, form data, and Basic Auth for maximum compatibility