Project 404

API Documentation

TL;DR

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

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_your_64_character_api_key_here" \
  https://4-0-4.io/api/user/bookmarks

Via URL Parameter:

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

Via JSON Body:

curl -X POST -H "Content-Type: application/json" \
  -d '{"api_key":"p404_your_64_character_api_key_here","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":"your_username","password":"your_password","title":"My Bookmark","url":"https://example.com"}' \
  https://4-0-4.io/api/links

3. Basic Authentication Header

curl -u "your_username:your_password" \
  https://4-0-4.io/api/links

4. POST Data

curl -X POST -d "username=your_username&password=your_password&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": 1,
    "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:
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": 1,
      "name": "Production API Key",
      "key_prefix": "p404_abc123",
      "created_at": "2025-07-02 12:00:00",
      "last_used_at": "2025-07-02 13:30:00",
      "expires_at": "2026-07-02 12:00:00",
      "is_active": true
    }
  ]
}

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/1
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:
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:
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

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