Update Api

Api.md

@@ -1,5 +1,133 @@
-# API
+# f0ckm Upload API Documentation
 
-## Upload
+This document describes how to programmatically upload files to the **f0ckm** instance using the API Key system.
 
-`/api/v2/upload`
+---
+
+## Authentication
+
+All API uploads require authentication via a custom header. 
+
+To authorize your request, include the `X-Api-Key` header with your personal API key. You can generate or revoke your API key under the **Settings** panel on the web interface.
+
+```http
+X-Api-Key: your_64_character_hex_api_key_here
+```
+
+---
+
+## Endpoint: POST `/api/v2/upload`
+
+Upload a file along with associated metadata.
+
+* **URL:** `/api/v2/upload`
+* **Method:** `POST`
+* **Content-Type:** `multipart/form-data`
+
+### Request Parameters (Form Fields)
+
+| Parameter | Type | Required | Description |
+| :--- | :--- | :---: | :--- |
+| `file` | `File` (Binary) | **Yes** | The file to be uploaded. |
+| `rating` | `String` | **Conditional** | Must be one of: `sfw`, `nsfw`, or `nsfl`. Required unless `is_shitpost` mode is active and the server allows it. |
+| `tags` | `String` | **Conditional** | A comma-separated list of tags (e.g. `cats, funny, video`). Tags like `sfw`, `nsfw`, or `nsfl` should **not** be included here; use the `rating` parameter instead. Required depending on server tag requirements. |
+| `comment` | `String` | *No* | An optional description or first comment to attach to the upload. |
+| `is_oc` | `String` / `Number` | *No* | Set to `true` or `1` to mark the upload as Original Content (OC). |
+| `is_shitpost` | `String` / `Number` | *No* | Set to `true` or `1` to bypass standard tagging rules (if shitpost mode is allowed/enabled on the server). |
+
+---
+
+## Examples
+
+### 1. Simple cURL Example
+
+A standard SFW upload with tags and a comment:
+
+```bash
+curl -X POST https://yourdomain.com/api/v2/upload \
+  -H "X-Api-Key: 3c25f45bc5191610599ed3e83a62aa8eee92e013e432c097825cf312fe7a5d7e" \
+  -F "file=@/path/to/cat.jpg" \
+  -F "rating=sfw" \
+  -F "tags=cat, cute, feline" \
+  -F "comment=Look at this sleepy kitten!" \
+  -F "is_oc=1"
+```
+
+### 2. Shitpost Mode Upload (Optional Tags & Rating)
+
+If the server has `shitpost_mode` enabled or you specify `is_shitpost=1`, you can upload with fewer restrictions (or omit tags/rating depending on configuration):
+
+```bash
+curl -X POST https://yourdomain.com/api/v2/upload \
+  -H "X-Api-Key: 3c25f45bc5191610599ed3e83a62aa8eee92e013e432c097825cf312fe7a5d7e" \
+  -F "file=@/path/to/meme.png" \
+  -F "is_shitpost=1" \
+  -F "comment=low quality meme"
+```
+---
+
+## Response Formats
+
+### Success Response (Live Upload)
+
+When manual approval is not required, the upload is live immediately:
+
+```json
+{
+  "success": true,
+  "msg": "Upload successful! Your upload is now live.",
+  "itemid": 12,
+  "manual_approval": false,
+  "redirect": "/12",
+  "url": "https://yourdomain.com/12"
+}
+```
+
+### Success Response (Pending Approval)
+
+When administrative manual approval is enabled, the item is queued:
+
+```json
+{
+  "success": true,
+  "msg": "Upload queued for manual approval.",
+  "itemid": 13,
+  "manual_approval": true,
+  "redirect": null,
+  "url": "https://yourdomain.com/"
+}
+```
+
+### Error Responses
+
+#### Missing File
+```json
+{
+  "success": false,
+  "msg": "No file provided"
+}
+```
+
+#### Missing/Invalid Rating
+```json
+{
+  "success": false,
+  "msg": "Rating (sfw/nsfw/nsfl) is required"
+}
+```
+
+#### Missing Tags (when minimum tag limit is unmet)
+```json
+{
+  "success": false,
+  "msg": "At least 3 tags are required"
+}
+```
+
+#### Invalid/Banned API Key
+```json
+{
+  "success": false,
+  "msg": "Invalid or inactive API key"
+}
+```