Folders | Fareeqy API

The resource

The fields returned inside data by the endpoints in this group.

idinteger

Numeric id (folders have no slug).

namestring

pathstring

descriptionstring | null

parent_folder_idinteger | null

created_atstring (date-time)

Folder

{
  "id": 42,
  "name": "التصاميم",
  "path": "التصاميم",
  "description": "ملفات الهوية وواجهات الموقع.",
  "parent_folder_id": null,
  "created_at": "2026-07-05T08:20:00.000+03:00"
}

Create a folder

POST/projects/{project_id}/foldersRequires files:write

Creates a folder (an upload-level right, manage_files).

Path parameters

project_idstringrequired

The project SLUG.

Request body

namestringrequired

descriptionstring | null

parent_folder_idinteger | null

Parent folder; omit for the project root.

Request

cURL

curl -X POST "https://app.fareeqy.com/api/v1/projects/تطوير-الموقع/folders" \
  -H "Authorization: Bearer $FAREEQY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"التصاميم","description":"ملفات الهوية وواجهات الموقع.","parent_folder_id":null}'

Response

201

{
  "data": {
    "id": 42,
    "name": "التصاميم",
    "path": "التصاميم",
    "description": "ملفات الهوية وواجهات الموقع.",
    "parent_folder_id": null,
    "created_at": "2026-07-05T08:20:00.000+03:00"
  }
}

Refusals:401403404409422429Show failure examples

401default

Missing or invalid API key.

default

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}

403forbidden

Two different refusals share this status, and a client must tell them apart by error.code. forbidden means the key's scope or allowlist does not permit this operation, or Pundit denied the action. plan_upgrade_required means the company's plan carries no API access at all, so no key on it can ever succeed and there is nothing to retry.

This key may not perform this operation

{
  "error": {
    "code": "forbidden",
    "message": "This API key is not permitted to perform this operation."
  }
}

The company's plan carries no API access

{
  "error": {
    "code": "plan_upgrade_required",
    "message": "خطة «الاحترافي» لا تشمل الوصول إلى API. رقِّ إلى «المتطور» أو «الانتاجي» لتفعيله. — The الاحترافي plan does not include API access. Upgrade to «المتطور» or «الانتاجي» to enable it."
  }
}

404default

Resource not found or not accessible — also returned for EVERY endpoint when the company's rest_api feature flag is disabled (the surface is hidden). Lookups drill through the URL hierarchy, so another company's record is a 404 and never a leak. A path that matches no route at all answers 404 with the distinct code unknown_endpoint and echoes the path back, so a mistyped or half-built URL is told apart from a record that is missing or out of reach.

default

{
  "error": {
    "code": "not_found",
    "message": "Resource not found, or you do not have access to it."
  }
}

409default

A uniqueness/record conflict; retry.

default

{
  "error": {
    "code": "conflict",
    "message": "Could not complete due to a conflict; please retry."
  }
}

422default

A caller-fixable bad request (validation error, bad date, bad enum).

default

{
  "error": {
    "code": "unprocessable_entity",
    "message": "Title can't be blank"
  }
}

429rate_limit_exceeded

Either the company's daily API allowance is spent (rate_limit_exceeded), or the per-key / per-IP burst throttle of 300 requests per minute fired. Both come back after a wait, so Retry-After is honest here. The two bodies are not the same shape. The daily-quota refusal uses the standard error envelope. The burst throttle is served by Rack::Attack ahead of the application, so its body is a flat {"error": "<string>"} with no code. A client that reads error.code has to tolerate error being a plain string.

Today's daily allowance is spent (application envelope)

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "استهلكت رصيد اليوم من طلبات API في خطة «المتطور» (1000 طلب يوميًا). يتجدد الرصيد عند منتصف الليل بتوقيت Asia/Riyadh. — Daily API quota exhausted: the المتطور plan allows 1000 calls per day. It resets at midnight Asia/Riyadh."
  }
}

Over 300 requests in a minute (Rack::Attack body, flat error)

{
  "error": "Rate limit exceeded. Please try again later."
}

Errors

Delete a folder

DELETE/projects/{project_id}/folders/{id}Requires files:destructive

Permanent, RECURSIVE — the folder and its entire subtree (every subfolder and file, whoever uploaded them). Demands delete_any_file, no creator bypass.

Path parameters

project_idstringrequired

The project SLUG.

idintegerrequired

The folder's NUMERIC id (folders have no slug).

Request

cURL

curl -X DELETE "https://app.fareeqy.com/api/v1/projects/تطوير-الموقع/folders/42" \
  -H "Authorization: Bearer $FAREEQY_API_KEY"

Response

200

{
  "data": {
    "deleted": true,
    "folder": {
      "id": 42,
      "name": "التصاميم"
    },
    "destroyed": {
      "files": 7,
      "subfolders": 1
    }
  }
}

Refusals:401403404429Show failure examples

401default

Missing or invalid API key.

default

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}

403forbidden

This key may not perform this operation

{
  "error": {
    "code": "forbidden",
    "message": "This API key is not permitted to perform this operation."
  }
}

The company's plan carries no API access

{
  "error": {
    "code": "plan_upgrade_required",
    "message": "خطة «الاحترافي» لا تشمل الوصول إلى API. رقِّ إلى «المتطور» أو «الانتاجي» لتفعيله. — The الاحترافي plan does not include API access. Upgrade to «المتطور» or «الانتاجي» to enable it."
  }
}

404default

default

{
  "error": {
    "code": "not_found",
    "message": "Resource not found, or you do not have access to it."
  }
}

429rate_limit_exceeded

Today's daily allowance is spent (application envelope)

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "استهلكت رصيد اليوم من طلبات API في خطة «المتطور» (1000 طلب يوميًا). يتجدد الرصيد عند منتصف الليل بتوقيت Asia/Riyadh. — Daily API quota exhausted: the المتطور plan allows 1000 calls per day. It resets at midnight Asia/Riyadh."
  }
}

Over 300 requests in a minute (Rack::Attack body, flat error)

{
  "error": "Rate limit exceeded. Please try again later."
}

Errors