API Documentation

Use the Foldious API to upload, list, and manage your images from scripts or apps, and to track AI workflow tasks. Send your API key in a header only (never in the URL).

Base URL & Authentication
Base URL (key-based endpoints)

https://www.foldious.com/api/key

Authentication

Send your API key in a header only (never in the URL or query string):

  • Authorization: Bearer YOUR_API_KEY
  • X-API-Key: YOUR_API_KEY

Missing or invalid key returns 401 with {"success": false, "message": "..."}

1. Upload image(s)

Request: POST https://www.foldious.com/api/key/upload.php

Content-Type: multipart/form-data

Fields: images[] (file(s)), optional folder_id, filename

Success response (200):

{
  "status": "success",
  "message": "Images uploaded successfully",
  "uploaded_count": 1,
  "images": [
    {
      "image_id": 123,
      "image_code": "abc123-def456-...",
      "image_name": "photo.jpg",
      "image_size": 102400,
      "folder_id": 1
    }
  ]
}

Error: 400 / 403 / 500 with {"status": "error", "message": "..."}

2. List images (pagination)

Request: GET https://www.foldious.com/api/key/images.php?page=1&limit=20

Query params: page (default 1), limit (default 20, max 100), optional folder_id

Success response (200):

{
  "success": true,
  "images": [
    {
      "image_id": 123,
      "user_id": 1,
      "image_code": "abc123-def456-...",
      "image_name": "photo.jpg",
      "image_size": 102400,
      "image_thumb": "https://...",
      "image_medium": "https://...",
      "image_full": "https://...",
      "created_at": "2025-01-15 10:30:00",
      "folder_name": "all"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 45, "total_pages": 3 }
}

Use image_code for details and delete endpoints.

3. Image details

Request: GET https://www.foldious.com/api/key/image_details.php?image_code=YOUR_IMAGE_CODE

Query param: image_code (required)

Success response (200):

{
  "success": true,
  "image_id": 123,
  "image_code": "abc123-def456-...",
  "image_name": "photo.jpg",
  "image_thumb": "https://...",
  "image_medium": "https://...",
  "image_full": "https://...",
  "folder_name": "all",
  "created_at": "2025-01-15 10:30:00"
}

Error: 400 (missing image_code), 404 (not found)

4. Delete image (move to trash)

Request: POST https://www.foldious.com/api/key/delete_image.php

Body: image_code=YOUR_IMAGE_CODE (form) or JSON {"image_code": "YOUR_IMAGE_CODE"}

Success response (200):

{
  "success": true,
  "message": "Image moved to trash successfully"
}

Workflow API (no API key required)

Use these endpoints to create workflow records and mark them completed or failed (e.g. from n8n or your app).

5. Create workflow record (get workflow_id)

Request: POST https://www.foldious.com/api/workflow/insert.php

Content-Type: application/json. No authentication required.

Body: user_id (required), tool_type (required), optional status, created_at

Allowed tool_type: ai_create, create, edit, merge, remove_bg, remove_watermark

Success response (200):

{
  "success": true,
  "workflow_id": 123,
  "id": 123,
  "user_id": 1,
  "tool_type": "remove_bg",
  "status": "pending",
  "message": "Workflow record created"
}
6. Complete or fail workflow

Request: GET https://www.foldious.com/api/workflow/complete.php?workflow_id=123&status=completed

Query params: workflow_id (required), status = completed or failed (default completed)

Success response (200):

{
  "status": "success",
  "message": "Workflow updated"
}
Example: cURL
# List images
curl -H "Authorization: Bearer YOUR_API_KEY" "https://www.foldious.com/api/key/images.php?page=1&limit=10"

# Get image details
curl -H "X-API-Key: YOUR_API_KEY" "https://www.foldious.com/api/key/image_details.php?image_code=YOUR_IMAGE_CODE"

# Delete image
curl -X POST -H "Authorization: Bearer YOUR_API_KEY" -d "image_code=YOUR_IMAGE_CODE" "https://www.foldious.com/api/key/delete_image.php"

# Upload
curl -X POST -H "Authorization: Bearer YOUR_API_KEY" -F "images[]=@/path/to/photo.jpg" "https://www.foldious.com/api/key/upload.php"

# Create workflow record (no auth)
curl -X POST -H "Content-Type: application/json" -d '{"user_id":1,"tool_type":"remove_bg"}' "https://www.foldious.com/api/workflow/insert.php"

# Complete workflow
curl "https://www.foldious.com/api/workflow/complete.php?workflow_id=123&status=completed"