--- title: "Tasks | Fareeqy API" description: "The actionable items nested under a task list. Ref ids (tsk-); a slug still resolves. The Tasks endpoints in the Fareeqy REST API: parameters, request bodies" url: https://fareeqy.com/api/v1/docs/tasks/en language: en --- # Tasks The actionable items nested under a task list. Ref ids (tsk-); a slug still resolves. Base URL `https://app.fareeqy.com/api/v1` Contents On this page - The resource - List a task list's tasks - Create a task - Get a task - Update a task - Delete a task - Mark a task complete - Reopen a task - Move a task to another list in the same project - Record time spent on a task - List a task list's tasks, by ref - Create a task in a task list, by ref - Get a task by ref - Update a task by ref - Delete a task by ref - Complete a task by ref - Reopen a task by ref - Move a task to another list, by ref - Record time spent on a task, by ref Endpoints - [Account](https://fareeqy.com/api/v1/docs/account/en) - [Events](https://fareeqy.com/api/v1/docs/events/en) - [Projects](https://fareeqy.com/api/v1/docs/projects/en) - [Members](https://fareeqy.com/api/v1/docs/members/en) - [Task lists](https://fareeqy.com/api/v1/docs/task-lists/en) - [Tasks](https://fareeqy.com/api/v1/docs/tasks/en) - [Comments](https://fareeqy.com/api/v1/docs/comments/en) - [Discussions](https://fareeqy.com/api/v1/docs/discussions/en) - [Files](https://fareeqy.com/api/v1/docs/files/en) - [Folders](https://fareeqy.com/api/v1/docs/folders/en) More - [Changelog](https://fareeqy.com/api/v1/docs/changelog/en) On this page - The resource - List a task list's tasks - Create a task - Get a task - Update a task - Delete a task - Mark a task complete - Reopen a task - Move a task to another list in the same project - Record time spent on a task - List a task list's tasks, by ref - Create a task in a task list, by ref - Get a task by ref - Update a task by ref - Delete a task by ref - Complete a task by ref - Reopen a task by ref - Move a task to another list, by ref - Record time spent on a task, by ref Endpoints - [Account](https://fareeqy.com/api/v1/docs/account/en) - [Events](https://fareeqy.com/api/v1/docs/events/en) - [Projects](https://fareeqy.com/api/v1/docs/projects/en) - [Members](https://fareeqy.com/api/v1/docs/members/en) - [Task lists](https://fareeqy.com/api/v1/docs/task-lists/en) - [Tasks](https://fareeqy.com/api/v1/docs/tasks/en) - [Comments](https://fareeqy.com/api/v1/docs/comments/en) - [Discussions](https://fareeqy.com/api/v1/docs/discussions/en) - [Files](https://fareeqy.com/api/v1/docs/files/en) - [Folders](https://fareeqy.com/api/v1/docs/folders/en) More - [Changelog](https://fareeqy.com/api/v1/docs/changelog/en) ## The resource The fields returned inside `data` by the endpoints in this group. `id` string The task ref. A slug is still accepted anywhere this is passed back. `url` string | null Absolute address of the page a person opens in فريقي. `title` string `notes` string | null Plain-text rendering of the rich-text notes. `completed` boolean `completed_at` string (date-time) | null `due_at` string (date) | null Due DATE (no time component). `time_spent_minutes` integer | null How long the task took, in whole minutes. Always present, null when nobody has measured it — null is not zero. Reading it is ungated; writing needs a plan that carries time tracking. `project_slug` string The project ref. Named \_slug for compatibility. `task_list_slug` string The task-list ref. Named \_slug for compatibility. `assignee` object | any | null `created_at` string (date-time) Task Copy `{ "id": "tsk-9wb7t", "url": "https://app.fareeqy.com/tasks/tsk-9wb7t", "title": "تصميم الهيدر", "notes": "نحتاج نسخة للجوال ونسخة للديسكتوب.", "completed": false, "completed_at": null, "due_at": "2026-08-10", "time_spent_minutes": 90, "project_slug": "prj-8f3kd", "task_list_slug": "lst-4m2qp", "assignee": { "name": "عبدالله المطيري", "email": "abdullah@example.com" }, "created_at": "2026-07-03T11:40:09.000+03:00" }` ### List a task list's tasks GET /projects/ {project\_id} /lists/ {task\_list\_id} /tasks Requires `tasks:read` #### Path parameters `project_id` string required The project REF, or its slug. `task_list_id` string required The task-list REF, or its slug. #### Query parameters `limit` integer Page size (default 50, max 100, clamped). Default: `50` `offset` integer Number of records to skip (default 0). Default: `0` #### Request cURL Copy `curl "https://app.fareeqy.com/api/v1/projects/prj-8f3kd/lists/lst-4m2qp/tasks" \ -H "Authorization: Bearer $FAREEQY_API_KEY"` #### Response 200 Copy `{ "data": [ { "id": "tsk-9wb7t", "url": "https://app.fareeqy.com/tasks/tsk-9wb7t", "title": "تصميم الهيدر", "notes": "نحتاج نسخة للجوال ونسخة للديسكتوب.", "completed": false, "completed_at": null, "due_at": "2026-08-10", "time_spent_minutes": 90, "project_slug": "prj-8f3kd", "task_list_slug": "lst-4m2qp", "assignee": { "name": "عبدالله المطيري", "email": "abdullah@example.com" }, "created_at": "2026-07-03T11:40:09.000+03:00" } ], "meta": { "total": 4, "limit": 50, "offset": 0, "count": 4 } }` Refusals: 401 403 404 429 Show failure examples Hide failure examples 401 `default` Missing or invalid API key. default Copy `{ "error": { "code": "unauthorized", "message": "مفتاح الـ API غير صالح أو غير مُرسَل." } }` 403 `forbidden` 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 Copy `{ "error": { "code": "forbidden", "message": "هذا الـ API key لا يملك صلاحية تنفيذ هذه العملية." } }` The company's plan carries no API access Copy `{ "error": { "code": "plan_upgrade_required", "message": "خطة «الاحترافي» لا تشمل الوصول إلى API. رقِّ إلى «المتطور» أو «الإنتاجي» لتفعيله." } }` 404 `not_found` 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. A record that is missing or out of reach Copy `{ "error": { "code": "not_found", "message": "غير موجود، أو لا تملك صلاحية الوصول إليه." } }` A path that matches no endpoint Copy `{ "error": { "code": "unknown_endpoint", "message": "لا يوجد endpoint يطابق GET /api/v1/projcts. راجع المسار في توثيق الـ API." } }` 429 `rate_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": ""}` 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) Copy `{ "error": { "code": "rate_limit_exceeded", "message": "استهلكت رصيد اليوم من طلبات API في خطة «المتطور» (1000 طلب يوميًا). يتجدد الرصيد عند منتصف الليل بتوقيت Asia/Riyadh." } }` Over 300 requests in a minute (Rack::Attack body, flat error) Copy `{ "error": "Rate limit exceeded. Please try again later." }` [Errors](https://fareeqy.com/api/v1/docs/en#errors) ### Create a task POST /projects/ {project\_id} /lists/ {task\_list\_id} /tasks Requires `tasks:write` Creates a task in the list. `assignee_email` must name an assignable member (see the project's members). #### Path parameters `project_id` string required The project REF, or its slug. `task_list_id` string required The task-list REF, or its slug. #### Request body `title` string required `notes` string | null Rich-text notes (plain text in). `due_at` string | null Due DATE (YYYY-MM-DD, e.g. 2026-07-20). A task is due on a day, not at a moment: the column is a `date`, so a value carrying a time is accepted and the time is then dropped. Send `2026-07-20T14:00` and you get `2026-07-20` back. `assignee_email` string (email) | null Email of an assignable member. #### Request cURL Copy `curl -X POST "https://app.fareeqy.com/api/v1/projects/prj-8f3kd/lists/lst-4m2qp/tasks" \ -H "Authorization: Bearer $FAREEQY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"title":"تصميم الهيدر","notes":"نحتاج نسخة للجوال ونسخة للديسكتوب.","due_at":"2026-08-10","assignee_email":"abdullah@example.com"}'` #### Response 201 Copy `{ "data": { "id": "tsk-9wb7t", "url": "https://app.fareeqy.com/tasks/tsk-9wb7t", "title": "تصميم الهيدر", "notes": "نحتاج نسخة للجوال ونسخة للديسكتوب.", "completed": false, "completed_at": null, "due_at": "2026-08-10", "time_spent_minutes": 90, "project_slug": "prj-8f3kd", "task_list_slug": "lst-4m2qp", "assignee": { "name": "عبدالله المطيري", "email": "abdullah@example.com" }, "created_at": "2026-07-03T11:40:09.000+03:00" } }` Refusals: 401 403 404 409 422 429 Show failure examples Hide failure examples 401 `default` Missing or invalid API key. default Copy `{ "error": { "code": "unauthorized", "message": "مفتاح الـ API غير صالح أو غير مُرسَل." } }` 403 `forbidden` 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 Copy `{ "error": { "code": "forbidden", "message": "هذا الـ API key لا يملك صلاحية تنفيذ هذه العملية." } }` The company's plan carries no API access Copy `{ "error": { "code": "plan_upgrade_required", "message": "خطة «الاحترافي» لا تشمل الوصول إلى API. رقِّ إلى «المتطور» أو «الإنتاجي» لتفعيله." } }` 404 `not_found` 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. A record that is missing or out of reach Copy `{ "error": { "code": "not_found", "message": "غير موجود، أو لا تملك صلاحية الوصول إليه." } }` A path that matches no endpoint Copy `{ "error": { "code": "unknown_endpoint", "message": "لا يوجد endpoint يطابق GET /api/v1/projcts. راجع المسار في توثيق الـ API." } }` 409 `default` A uniqueness/record conflict; retry. default Copy `{ "error": { "code": "conflict", "message": "تعذّر إتمام العملية بسبب تعارض. أعد المحاولة." } }` 422 `default` A caller-fixable bad request (validation error, bad date, bad enum). default Copy `{ "error": { "code": "unprocessable_entity", "message": "قيمة due_at غير صالحة؛ أرسل تاريخاً مثل 2026-07-20. المهمة تُستحق في يوم، وأي وقت ترسله يُهمل." } }` 429 `rate_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": ""}` 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) Copy `{ "error": { "code": "rate_limit_exceeded", "message": "استهلكت رصيد اليوم من طلبات API في خطة «المتطور» (1000 طلب يوميًا). يتجدد الرصيد عند منتصف الليل بتوقيت Asia/Riyadh." } }` Over 300 requests in a minute (Rack::Attack body, flat error) Copy `{ "error": "Rate limit exceeded. Please try again later." }` [Errors](https://fareeqy.com/api/v1/docs/en#errors) ### Get a task GET /projects/ {project\_id} /lists/ {task\_list\_id} /tasks/ {id} Requires `tasks:read` #### Path parameters `project_id` string required The project REF, or its slug. `task_list_id` string required The task-list REF, or its slug. `id` string required The task REF (tsk-8f3kd), or its slug (unique within its task list). #### Request cURL Copy `curl "https://app.fareeqy.com/api/v1/projects/prj-8f3kd/lists/lst-4m2qp/tasks/tsk-9wb7t" \ -H "Authorization: Bearer $FAREEQY_API_KEY"` #### Response 200 Copy `{ "data": { "id": "tsk-9wb7t", "url": "https://app.fareeqy.com/tasks/tsk-9wb7t", "title": "تصميم الهيدر", "notes": "نحتاج نسخة للجوال ونسخة للديسكتوب.", "completed": false, "completed_at": null, "due_at": "2026-08-10", "time_spent_minutes": 90, "project_slug": "prj-8f3kd", "task_list_slug": "lst-4m2qp", "assignee": { "name": "عبدالله المطيري", "email": "abdullah@example.com" }, "created_at": "2026-07-03T11:40:09.000+03:00" } }` Refusals: 401 403 404 429 Show failure examples Hide failure examples 401 `default` Missing or invalid API key. default Copy `{ "error": { "code": "unauthorized", "message": "مفتاح الـ API غير صالح أو غير مُرسَل." } }` 403 `forbidden` 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 Copy `{ "error": { "code": "forbidden", "message": "هذا الـ API key لا يملك صلاحية تنفيذ هذه العملية." } }` The company's plan carries no API access Copy `{ "error": { "code": "plan_upgrade_required", "message": "خطة «الاحترافي» لا تشمل الوصول إلى API. رقِّ إلى «المتطور» أو «الإنتاجي» لتفعيله." } }` 404 `not_found` 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. A record that is missing or out of reach Copy `{ "error": { "code": "not_found", "message": "غير موجود، أو لا تملك صلاحية الوصول إليه." } }` A path that matches no endpoint Copy `{ "error": { "code": "unknown_endpoint", "message": "لا يوجد endpoint يطابق GET /api/v1/projcts. راجع المسار في توثيق الـ API." } }` 429 `rate_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": ""}` 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) Copy `{ "error": { "code": "rate_limit_exceeded", "message": "استهلكت رصيد اليوم من طلبات API في خطة «المتطور» (1000 طلب يوميًا). يتجدد الرصيد عند منتصف الليل بتوقيت Asia/Riyadh." } }` Over 300 requests in a minute (Rack::Attack body, flat error) Copy `{ "error": "Rate limit exceeded. Please try again later." }` [Errors](https://fareeqy.com/api/v1/docs/en#errors) ### Update a task PATCH /projects/ {project\_id} /lists/ {task\_list\_id} /tasks/ {id} Requires `tasks:write` Only passed fields change. Passing `assignee_email` (even empty) reassigns; an empty value unassigns. #### Path parameters `project_id` string required The project REF, or its slug. `task_list_id` string required The task-list REF, or its slug. `id` string required The task REF (tsk-8f3kd), or its slug (unique within its task list). #### Request body `title` string `notes` string | null `due_at` string | null New due DATE (YYYY-MM-DD). Any time component is dropped — see the create operation. `assignee_email` string | null Email of an assignable member. An empty string unassigns, which is why this carries no `email` format: the empty value is a real, accepted input here. #### Request cURL Copy `curl -X PATCH "https://app.fareeqy.com/api/v1/projects/prj-8f3kd/lists/lst-4m2qp/tasks/tsk-9wb7t" \ -H "Authorization: Bearer $FAREEQY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"title":"","notes":null,"due_at":null,"assignee_email":null}'` #### Response 200 Copy `{ "data": { "id": "tsk-9wb7t", "url": "https://app.fareeqy.com/tasks/tsk-9wb7t", "title": "تصميم الهيدر", "notes": "نحتاج نسخة للجوال ونسخة للديسكتوب.", "completed": false, "completed_at": null, "due_at": "2026-08-10", "time_spent_minutes": 90, "project_slug": "prj-8f3kd", "task_list_slug": "lst-4m2qp", "assignee": { "name": "عبدالله المطيري", "email": "abdullah@example.com" }, "created_at": "2026-07-03T11:40:09.000+03:00" } }` Refusals: 401 403 404 409 422 429 Show failure examples Hide failure examples 401 `default` Missing or invalid API key. default Copy `{ "error": { "code": "unauthorized", "message": "مفتاح الـ API غير صالح أو غير مُرسَل." } }` 403 `forbidden` 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 Copy `{ "error": { "code": "forbidden", "message": "هذا الـ API key لا يملك صلاحية تنفيذ هذه العملية." } }` The company's plan carries no API access Copy `{ "error": { "code": "plan_upgrade_required", "message": "خطة «الاحترافي» لا تشمل الوصول إلى API. رقِّ إلى «المتطور» أو «الإنتاجي» لتفعيله." } }` 404 `not_found` 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. A record that is missing or out of reach Copy `{ "error": { "code": "not_found", "message": "غير موجود، أو لا تملك صلاحية الوصول إليه." } }` A path that matches no endpoint Copy `{ "error": { "code": "unknown_endpoint", "message": "لا يوجد endpoint يطابق GET /api/v1/projcts. راجع المسار في توثيق الـ API." } }` 409 `default` A uniqueness/record conflict; retry. default Copy `{ "error": { "code": "conflict", "message": "تعذّر إتمام العملية بسبب تعارض. أعد المحاولة." } }` 422 `default` A caller-fixable bad request (validation error, bad date, bad enum). default Copy `{ "error": { "code": "unprocessable_entity", "message": "قيمة due_at غير صالحة؛ أرسل تاريخاً مثل 2026-07-20. المهمة تُستحق في يوم، وأي وقت ترسله يُهمل." } }` 429 `rate_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": ""}` 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) Copy `{ "error": { "code": "rate_limit_exceeded", "message": "استهلكت رصيد اليوم من طلبات API في خطة «المتطور» (1000 طلب يوميًا). يتجدد الرصيد عند منتصف الليل بتوقيت Asia/Riyadh." } }` Over 300 requests in a minute (Rack::Attack body, flat error) Copy `{ "error": "Rate limit exceeded. Please try again later." }` [Errors](https://fareeqy.com/api/v1/docs/en#errors) ### Delete a task DELETE /projects/ {project\_id} /lists/ {task\_list\_id} /tasks/ {id} Requires `tasks:destructive` Permanent. #### Path parameters `project_id` string required The project REF, or its slug. `task_list_id` string required The task-list REF, or its slug. `id` string required The task REF (tsk-8f3kd), or its slug (unique within its task list). #### Request cURL Copy `curl -X DELETE "https://app.fareeqy.com/api/v1/projects/prj-8f3kd/lists/lst-4m2qp/tasks/tsk-9wb7t" \ -H "Authorization: Bearer $FAREEQY_API_KEY"` #### Response 200 Copy `{ "data": { "deleted": true, "task": { "title": "تصميم الهيدر", "id": "tsk-9wb7t" } } }` Refusals: 401 403 404 429 Show failure examples Hide failure examples 401 `default` Missing or invalid API key. default Copy `{ "error": { "code": "unauthorized", "message": "مفتاح الـ API غير صالح أو غير مُرسَل." } }` 403 `forbidden` 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 Copy `{ "error": { "code": "forbidden", "message": "هذا الـ API key لا يملك صلاحية تنفيذ هذه العملية." } }` The company's plan carries no API access Copy `{ "error": { "code": "plan_upgrade_required", "message": "خطة «الاحترافي» لا تشمل الوصول إلى API. رقِّ إلى «المتطور» أو «الإنتاجي» لتفعيله." } }` 404 `not_found` 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. A record that is missing or out of reach Copy `{ "error": { "code": "not_found", "message": "غير موجود، أو لا تملك صلاحية الوصول إليه." } }` A path that matches no endpoint Copy `{ "error": { "code": "unknown_endpoint", "message": "لا يوجد endpoint يطابق GET /api/v1/projcts. راجع المسار في توثيق الـ API." } }` 429 `rate_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": ""}` 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) Copy `{ "error": { "code": "rate_limit_exceeded", "message": "استهلكت رصيد اليوم من طلبات API في خطة «المتطور» (1000 طلب يوميًا). يتجدد الرصيد عند منتصف الليل بتوقيت Asia/Riyadh." } }` Over 300 requests in a minute (Rack::Attack body, flat error) Copy `{ "error": "Rate limit exceeded. Please try again later." }` [Errors](https://fareeqy.com/api/v1/docs/en#errors) ### Mark a task complete POST /projects/ {project\_id} /lists/ {task\_list\_id} /tasks/ {id} /complete Requires `tasks:write` Idempotent: completing an already-complete task is a no-op. #### Path parameters `project_id` string required The project REF, or its slug. `task_list_id` string required The task-list REF, or its slug. `id` string required The task REF (tsk-8f3kd), or its slug (unique within its task list). #### Request cURL Copy `curl -X POST "https://app.fareeqy.com/api/v1/projects/prj-8f3kd/lists/lst-4m2qp/tasks/tsk-9wb7t/complete" \ -H "Authorization: Bearer $FAREEQY_API_KEY"` #### Response 200 Copy `{ "data": { "id": "tsk-9wb7t", "url": "https://app.fareeqy.com/tasks/tsk-9wb7t", "title": "تصميم الهيدر", "notes": "نحتاج نسخة للجوال ونسخة للديسكتوب.", "completed": false, "completed_at": null, "due_at": "2026-08-10", "time_spent_minutes": 90, "project_slug": "prj-8f3kd", "task_list_slug": "lst-4m2qp", "assignee": { "name": "عبدالله المطيري", "email": "abdullah@example.com" }, "created_at": "2026-07-03T11:40:09.000+03:00" } }` Refusals: 401 403 404 409 429 Show failure examples Hide failure examples 401 `default` Missing or invalid API key. default Copy `{ "error": { "code": "unauthorized", "message": "مفتاح الـ API غير صالح أو غير مُرسَل." } }` 403 `forbidden` 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 Copy `{ "error": { "code": "forbidden", "message": "هذا الـ API key لا يملك صلاحية تنفيذ هذه العملية." } }` The company's plan carries no API access Copy `{ "error": { "code": "plan_upgrade_required", "message": "خطة «الاحترافي» لا تشمل الوصول إلى API. رقِّ إلى «المتطور» أو «الإنتاجي» لتفعيله." } }` 404 `not_found` 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. A record that is missing or out of reach Copy `{ "error": { "code": "not_found", "message": "غير موجود، أو لا تملك صلاحية الوصول إليه." } }` A path that matches no endpoint Copy `{ "error": { "code": "unknown_endpoint", "message": "لا يوجد endpoint يطابق GET /api/v1/projcts. راجع المسار في توثيق الـ API." } }` 409 `default` A uniqueness/record conflict; retry. default Copy `{ "error": { "code": "conflict", "message": "تعذّر إتمام العملية بسبب تعارض. أعد المحاولة." } }` 429 `rate_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": ""}` 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) Copy `{ "error": { "code": "rate_limit_exceeded", "message": "استهلكت رصيد اليوم من طلبات API في خطة «المتطور» (1000 طلب يوميًا). يتجدد الرصيد عند منتصف الليل بتوقيت Asia/Riyadh." } }` Over 300 requests in a minute (Rack::Attack body, flat error) Copy `{ "error": "Rate limit exceeded. Please try again later." }` [Errors](https://fareeqy.com/api/v1/docs/en#errors) ### Reopen a task POST /projects/ {project\_id} /lists/ {task\_list\_id} /tasks/ {id} /incomplete Requires `tasks:write` Idempotent. #### Path parameters `project_id` string required The project REF, or its slug. `task_list_id` string required The task-list REF, or its slug. `id` string required The task REF (tsk-8f3kd), or its slug (unique within its task list). #### Request cURL Copy `curl -X POST "https://app.fareeqy.com/api/v1/projects/prj-8f3kd/lists/lst-4m2qp/tasks/tsk-9wb7t/incomplete" \ -H "Authorization: Bearer $FAREEQY_API_KEY"` #### Response 200 Copy `{ "data": { "id": "tsk-9wb7t", "url": "https://app.fareeqy.com/tasks/tsk-9wb7t", "title": "تصميم الهيدر", "notes": "نحتاج نسخة للجوال ونسخة للديسكتوب.", "completed": false, "completed_at": null, "due_at": "2026-08-10", "time_spent_minutes": 90, "project_slug": "prj-8f3kd", "task_list_slug": "lst-4m2qp", "assignee": { "name": "عبدالله المطيري", "email": "abdullah@example.com" }, "created_at": "2026-07-03T11:40:09.000+03:00" } }` Refusals: 401 403 404 409 429 Show failure examples Hide failure examples 401 `default` Missing or invalid API key. default Copy `{ "error": { "code": "unauthorized", "message": "مفتاح الـ API غير صالح أو غير مُرسَل." } }` 403 `forbidden` 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 Copy `{ "error": { "code": "forbidden", "message": "هذا الـ API key لا يملك صلاحية تنفيذ هذه العملية." } }` The company's plan carries no API access Copy `{ "error": { "code": "plan_upgrade_required", "message": "خطة «الاحترافي» لا تشمل الوصول إلى API. رقِّ إلى «المتطور» أو «الإنتاجي» لتفعيله." } }` 404 `not_found` 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. A record that is missing or out of reach Copy `{ "error": { "code": "not_found", "message": "غير موجود، أو لا تملك صلاحية الوصول إليه." } }` A path that matches no endpoint Copy `{ "error": { "code": "unknown_endpoint", "message": "لا يوجد endpoint يطابق GET /api/v1/projcts. راجع المسار في توثيق الـ API." } }` 409 `default` A uniqueness/record conflict; retry. default Copy `{ "error": { "code": "conflict", "message": "تعذّر إتمام العملية بسبب تعارض. أعد المحاولة." } }` 429 `rate_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": ""}` 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) Copy `{ "error": { "code": "rate_limit_exceeded", "message": "استهلكت رصيد اليوم من طلبات API في خطة «المتطور» (1000 طلب يوميًا). يتجدد الرصيد عند منتصف الليل بتوقيت Asia/Riyadh." } }` Over 300 requests in a minute (Rack::Attack body, flat error) Copy `{ "error": "Rate limit exceeded. Please try again later." }` [Errors](https://fareeqy.com/api/v1/docs/en#errors) ### Move a task to another list in the same project POST /projects/ {project\_id} /lists/ {task\_list\_id} /tasks/ {id} /move Requires `tasks:write` Moves the task to a different list in the SAME project, appended to the end. The destination is resolved inside the project in the path, so `target_task_list_slug` may be its ref, slug or numeric id. To move a task into another project, use the flat address. #### Path parameters `project_id` string required The project REF, or its slug. `task_list_id` string required The task-list REF, or its slug. `id` string required The task REF (tsk-8f3kd), or its slug (unique within its task list). #### Request body `target_task_list_slug` string required The destination task list. On the nested address, its ref, slug or numeric id inside the same project. On the flat address, its ref only, and it may be in another project. Named \_slug for compatibility. #### Request cURL Copy `curl -X POST "https://app.fareeqy.com/api/v1/projects/prj-8f3kd/lists/lst-4m2qp/tasks/tsk-9wb7t/move" \ -H "Authorization: Bearer $FAREEQY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"target_task_list_slug":"lst-7hx2r"}'` #### Response 200 Copy `{ "data": { "id": "tsk-9wb7t", "url": "https://app.fareeqy.com/tasks/tsk-9wb7t", "title": "تصميم الهيدر", "notes": "نحتاج نسخة للجوال ونسخة للديسكتوب.", "completed": false, "completed_at": null, "due_at": "2026-08-10", "time_spent_minutes": 90, "project_slug": "prj-8f3kd", "task_list_slug": "lst-4m2qp", "assignee": { "name": "عبدالله المطيري", "email": "abdullah@example.com" }, "created_at": "2026-07-03T11:40:09.000+03:00" } }` Refusals: 401 403 404 409 422 429 Show failure examples Hide failure examples 401 `default` Missing or invalid API key. default Copy `{ "error": { "code": "unauthorized", "message": "مفتاح الـ API غير صالح أو غير مُرسَل." } }` 403 `forbidden` 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 Copy `{ "error": { "code": "forbidden", "message": "هذا الـ API key لا يملك صلاحية تنفيذ هذه العملية." } }` The company's plan carries no API access Copy `{ "error": { "code": "plan_upgrade_required", "message": "خطة «الاحترافي» لا تشمل الوصول إلى API. رقِّ إلى «المتطور» أو «الإنتاجي» لتفعيله." } }` 404 `not_found` 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. A record that is missing or out of reach Copy `{ "error": { "code": "not_found", "message": "غير موجود، أو لا تملك صلاحية الوصول إليه." } }` A path that matches no endpoint Copy `{ "error": { "code": "unknown_endpoint", "message": "لا يوجد endpoint يطابق GET /api/v1/projcts. راجع المسار في توثيق الـ API." } }` 409 `default` A uniqueness/record conflict; retry. default Copy `{ "error": { "code": "conflict", "message": "تعذّر إتمام العملية بسبب تعارض. أعد المحاولة." } }` 422 `default` A caller-fixable bad request (validation error, bad date, bad enum). default Copy `{ "error": { "code": "unprocessable_entity", "message": "قيمة due_at غير صالحة؛ أرسل تاريخاً مثل 2026-07-20. المهمة تُستحق في يوم، وأي وقت ترسله يُهمل." } }` 429 `rate_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": ""}` 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) Copy `{ "error": { "code": "rate_limit_exceeded", "message": "استهلكت رصيد اليوم من طلبات API في خطة «المتطور» (1000 طلب يوميًا). يتجدد الرصيد عند منتصف الليل بتوقيت Asia/Riyadh." } }` Over 300 requests in a minute (Rack::Attack body, flat error) Copy `{ "error": "Rate limit exceeded. Please try again later." }` [Errors](https://fareeqy.com/api/v1/docs/en#errors) ### Record time spent on a task POST /projects/ {project\_id} /lists/ {task\_list\_id} /tasks/ {id} /time Requires `tasks:write` Records how long the task took. A separate action from PATCH, as it is in the web app., and a plan that carries time tracking (403 otherwise, with nothing recorded). #### Path parameters `project_id` string required The project REF, or its slug. `task_list_id` string required The task-list REF, or its slug. `id` string required The task REF (tsk-8f3kd), or its slug (unique within its task list). #### Request cURL Copy `curl -X POST "https://app.fareeqy.com/api/v1/projects/prj-8f3kd/lists/lst-4m2qp/tasks/tsk-9wb7t/time" \ -H "Authorization: Bearer $FAREEQY_API_KEY"` #### Response 200 Copy `{ "data": { "id": "tsk-9wb7t", "url": "https://app.fareeqy.com/tasks/tsk-9wb7t", "title": "تصميم الهيدر", "notes": "نحتاج نسخة للجوال ونسخة للديسكتوب.", "completed": false, "completed_at": null, "due_at": "2026-08-10", "time_spent_minutes": 90, "project_slug": "prj-8f3kd", "task_list_slug": "lst-4m2qp", "assignee": { "name": "عبدالله المطيري", "email": "abdullah@example.com" }, "created_at": "2026-07-03T11:40:09.000+03:00" } }` Refusals: 401 403 404 409 422 429 Show failure examples Hide failure examples 401 `default` Missing or invalid API key. default Copy `{ "error": { "code": "unauthorized", "message": "مفتاح الـ API غير صالح أو غير مُرسَل." } }` 403 `forbidden` 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 Copy `{ "error": { "code": "forbidden", "message": "هذا الـ API key لا يملك صلاحية تنفيذ هذه العملية." } }` The company's plan carries no API access Copy `{ "error": { "code": "plan_upgrade_required", "message": "خطة «الاحترافي» لا تشمل الوصول إلى API. رقِّ إلى «المتطور» أو «الإنتاجي» لتفعيله." } }` 404 `not_found` 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. A record that is missing or out of reach Copy `{ "error": { "code": "not_found", "message": "غير موجود، أو لا تملك صلاحية الوصول إليه." } }` A path that matches no endpoint Copy `{ "error": { "code": "unknown_endpoint", "message": "لا يوجد endpoint يطابق GET /api/v1/projcts. راجع المسار في توثيق الـ API." } }` 409 `default` A uniqueness/record conflict; retry. default Copy `{ "error": { "code": "conflict", "message": "تعذّر إتمام العملية بسبب تعارض. أعد المحاولة." } }` 422 `default` A caller-fixable bad request (validation error, bad date, bad enum). default Copy `{ "error": { "code": "unprocessable_entity", "message": "قيمة due_at غير صالحة؛ أرسل تاريخاً مثل 2026-07-20. المهمة تُستحق في يوم، وأي وقت ترسله يُهمل." } }` 429 `rate_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": ""}` 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) Copy `{ "error": { "code": "rate_limit_exceeded", "message": "استهلكت رصيد اليوم من طلبات API في خطة «المتطور» (1000 طلب يوميًا). يتجدد الرصيد عند منتصف الليل بتوقيت Asia/Riyadh." } }` Over 300 requests in a minute (Rack::Attack body, flat error) Copy `{ "error": "Rate limit exceeded. Please try again later." }` [Errors](https://fareeqy.com/api/v1/docs/en#errors) ### List a task list's tasks, by ref GET /lists/ {task\_list\_id} /tasks Requires `tasks:read` #### Path parameters `task_list_id` string required The task list REF (lst-4m2qp). A slug is not accepted here. #### Query parameters `limit` integer Page size (default 50, max 100, clamped). Default: `50` `offset` integer Number of records to skip (default 0). Default: `0` #### Request cURL Copy `curl "https://app.fareeqy.com/api/v1/lists/lst-4m2qp/tasks" \ -H "Authorization: Bearer $FAREEQY_API_KEY"` #### Response 200 Copy `{ "data": [ { "id": "tsk-9wb7t", "url": "https://app.fareeqy.com/tasks/tsk-9wb7t", "title": "تصميم الهيدر", "notes": "نحتاج نسخة للجوال ونسخة للديسكتوب.", "completed": false, "completed_at": null, "due_at": "2026-08-10", "time_spent_minutes": 90, "project_slug": "prj-8f3kd", "task_list_slug": "lst-4m2qp", "assignee": { "name": "عبدالله المطيري", "email": "abdullah@example.com" }, "created_at": "2026-07-03T11:40:09.000+03:00" } ], "meta": { "total": 4, "limit": 50, "offset": 0, "count": 4 } }` Refusals: 401 403 404 429 Show failure examples Hide failure examples 401 `default` Missing or invalid API key. default Copy `{ "error": { "code": "unauthorized", "message": "مفتاح الـ API غير صالح أو غير مُرسَل." } }` 403 `forbidden` 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 Copy `{ "error": { "code": "forbidden", "message": "هذا الـ API key لا يملك صلاحية تنفيذ هذه العملية." } }` The company's plan carries no API access Copy `{ "error": { "code": "plan_upgrade_required", "message": "خطة «الاحترافي» لا تشمل الوصول إلى API. رقِّ إلى «المتطور» أو «الإنتاجي» لتفعيله." } }` 404 `not_found` 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. A record that is missing or out of reach Copy `{ "error": { "code": "not_found", "message": "غير موجود، أو لا تملك صلاحية الوصول إليه." } }` A path that matches no endpoint Copy `{ "error": { "code": "unknown_endpoint", "message": "لا يوجد endpoint يطابق GET /api/v1/projcts. راجع المسار في توثيق الـ API." } }` 429 `rate_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": ""}` 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) Copy `{ "error": { "code": "rate_limit_exceeded", "message": "استهلكت رصيد اليوم من طلبات API في خطة «المتطور» (1000 طلب يوميًا). يتجدد الرصيد عند منتصف الليل بتوقيت Asia/Riyadh." } }` Over 300 requests in a minute (Rack::Attack body, flat error) Copy `{ "error": "Rate limit exceeded. Please try again later." }` [Errors](https://fareeqy.com/api/v1/docs/en#errors) ### Create a task in a task list, by ref POST /lists/ {task\_list\_id} /tasks Requires `tasks:write` #### Path parameters `task_list_id` string required The task list REF (lst-4m2qp). A slug is not accepted here. #### Request body `title` string required `notes` string | null Rich-text notes (plain text in). `due_at` string | null Due DATE (YYYY-MM-DD, e.g. 2026-07-20). A task is due on a day, not at a moment: the column is a `date`, so a value carrying a time is accepted and the time is then dropped. Send `2026-07-20T14:00` and you get `2026-07-20` back. `assignee_email` string (email) | null Email of an assignable member. #### Request cURL Copy `curl -X POST "https://app.fareeqy.com/api/v1/lists/lst-4m2qp/tasks" \ -H "Authorization: Bearer $FAREEQY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"title":"تصميم الهيدر","notes":"نحتاج نسخة للجوال ونسخة للديسكتوب.","due_at":"2026-08-10","assignee_email":"abdullah@example.com"}'` #### Response 201 Copy `{ "data": { "id": "tsk-9wb7t", "url": "https://app.fareeqy.com/tasks/tsk-9wb7t", "title": "تصميم الهيدر", "notes": "نحتاج نسخة للجوال ونسخة للديسكتوب.", "completed": false, "completed_at": null, "due_at": "2026-08-10", "time_spent_minutes": 90, "project_slug": "prj-8f3kd", "task_list_slug": "lst-4m2qp", "assignee": { "name": "عبدالله المطيري", "email": "abdullah@example.com" }, "created_at": "2026-07-03T11:40:09.000+03:00" } }` Refusals: 401 403 404 409 422 429 Show failure examples Hide failure examples 401 `default` Missing or invalid API key. default Copy `{ "error": { "code": "unauthorized", "message": "مفتاح الـ API غير صالح أو غير مُرسَل." } }` 403 `forbidden` 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 Copy `{ "error": { "code": "forbidden", "message": "هذا الـ API key لا يملك صلاحية تنفيذ هذه العملية." } }` The company's plan carries no API access Copy `{ "error": { "code": "plan_upgrade_required", "message": "خطة «الاحترافي» لا تشمل الوصول إلى API. رقِّ إلى «المتطور» أو «الإنتاجي» لتفعيله." } }` 404 `not_found` 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. A record that is missing or out of reach Copy `{ "error": { "code": "not_found", "message": "غير موجود، أو لا تملك صلاحية الوصول إليه." } }` A path that matches no endpoint Copy `{ "error": { "code": "unknown_endpoint", "message": "لا يوجد endpoint يطابق GET /api/v1/projcts. راجع المسار في توثيق الـ API." } }` 409 `default` A uniqueness/record conflict; retry. default Copy `{ "error": { "code": "conflict", "message": "تعذّر إتمام العملية بسبب تعارض. أعد المحاولة." } }` 422 `default` A caller-fixable bad request (validation error, bad date, bad enum). default Copy `{ "error": { "code": "unprocessable_entity", "message": "قيمة due_at غير صالحة؛ أرسل تاريخاً مثل 2026-07-20. المهمة تُستحق في يوم، وأي وقت ترسله يُهمل." } }` 429 `rate_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": ""}` 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) Copy `{ "error": { "code": "rate_limit_exceeded", "message": "استهلكت رصيد اليوم من طلبات API في خطة «المتطور» (1000 طلب يوميًا). يتجدد الرصيد عند منتصف الليل بتوقيت Asia/Riyadh." } }` Over 300 requests in a minute (Rack::Attack body, flat error) Copy `{ "error": "Rate limit exceeded. Please try again later." }` [Errors](https://fareeqy.com/api/v1/docs/en#errors) ### Get a task by ref GET /tasks/ {id} Requires `tasks:read` The shortest address this API has, and the one a person copies out of the browser. #### Path parameters `id` string required The task REF (tsk-9wb7t). A slug is not accepted here. #### Request cURL Copy `curl "https://app.fareeqy.com/api/v1/tasks/tsk-9wb7t" \ -H "Authorization: Bearer $FAREEQY_API_KEY"` #### Response 200 Copy `{ "data": { "id": "tsk-9wb7t", "url": "https://app.fareeqy.com/tasks/tsk-9wb7t", "title": "تصميم الهيدر", "notes": "نحتاج نسخة للجوال ونسخة للديسكتوب.", "completed": false, "completed_at": null, "due_at": "2026-08-10", "time_spent_minutes": 90, "project_slug": "prj-8f3kd", "task_list_slug": "lst-4m2qp", "assignee": { "name": "عبدالله المطيري", "email": "abdullah@example.com" }, "created_at": "2026-07-03T11:40:09.000+03:00" } }` Refusals: 401 403 404 429 Show failure examples Hide failure examples 401 `default` Missing or invalid API key. default Copy `{ "error": { "code": "unauthorized", "message": "مفتاح الـ API غير صالح أو غير مُرسَل." } }` 403 `forbidden` 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 Copy `{ "error": { "code": "forbidden", "message": "هذا الـ API key لا يملك صلاحية تنفيذ هذه العملية." } }` The company's plan carries no API access Copy `{ "error": { "code": "plan_upgrade_required", "message": "خطة «الاحترافي» لا تشمل الوصول إلى API. رقِّ إلى «المتطور» أو «الإنتاجي» لتفعيله." } }` 404 `not_found` 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. A record that is missing or out of reach Copy `{ "error": { "code": "not_found", "message": "غير موجود، أو لا تملك صلاحية الوصول إليه." } }` A path that matches no endpoint Copy `{ "error": { "code": "unknown_endpoint", "message": "لا يوجد endpoint يطابق GET /api/v1/projcts. راجع المسار في توثيق الـ API." } }` 429 `rate_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": ""}` 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) Copy `{ "error": { "code": "rate_limit_exceeded", "message": "استهلكت رصيد اليوم من طلبات API في خطة «المتطور» (1000 طلب يوميًا). يتجدد الرصيد عند منتصف الليل بتوقيت Asia/Riyadh." } }` Over 300 requests in a minute (Rack::Attack body, flat error) Copy `{ "error": "Rate limit exceeded. Please try again later." }` [Errors](https://fareeqy.com/api/v1/docs/en#errors) ### Update a task by ref PATCH /tasks/ {id} Requires `tasks:write` Only passed fields change. Passing `assignee_email` (even empty) reassigns; an empty value unassigns. #### Path parameters `id` string required The task REF (tsk-9wb7t). A slug is not accepted here. #### Request body `title` string `notes` string | null `due_at` string | null New due DATE (YYYY-MM-DD). Any time component is dropped — see the create operation. `assignee_email` string | null Email of an assignable member. An empty string unassigns, which is why this carries no `email` format: the empty value is a real, accepted input here. #### Request cURL Copy `curl -X PATCH "https://app.fareeqy.com/api/v1/tasks/tsk-9wb7t" \ -H "Authorization: Bearer $FAREEQY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"title":"","notes":null,"due_at":null,"assignee_email":null}'` #### Response 200 Copy `{ "data": { "id": "tsk-9wb7t", "url": "https://app.fareeqy.com/tasks/tsk-9wb7t", "title": "تصميم الهيدر", "notes": "نحتاج نسخة للجوال ونسخة للديسكتوب.", "completed": false, "completed_at": null, "due_at": "2026-08-10", "time_spent_minutes": 90, "project_slug": "prj-8f3kd", "task_list_slug": "lst-4m2qp", "assignee": { "name": "عبدالله المطيري", "email": "abdullah@example.com" }, "created_at": "2026-07-03T11:40:09.000+03:00" } }` Refusals: 401 403 404 409 422 429 Show failure examples Hide failure examples 401 `default` Missing or invalid API key. default Copy `{ "error": { "code": "unauthorized", "message": "مفتاح الـ API غير صالح أو غير مُرسَل." } }` 403 `forbidden` 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 Copy `{ "error": { "code": "forbidden", "message": "هذا الـ API key لا يملك صلاحية تنفيذ هذه العملية." } }` The company's plan carries no API access Copy `{ "error": { "code": "plan_upgrade_required", "message": "خطة «الاحترافي» لا تشمل الوصول إلى API. رقِّ إلى «المتطور» أو «الإنتاجي» لتفعيله." } }` 404 `not_found` 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. A record that is missing or out of reach Copy `{ "error": { "code": "not_found", "message": "غير موجود، أو لا تملك صلاحية الوصول إليه." } }` A path that matches no endpoint Copy `{ "error": { "code": "unknown_endpoint", "message": "لا يوجد endpoint يطابق GET /api/v1/projcts. راجع المسار في توثيق الـ API." } }` 409 `default` A uniqueness/record conflict; retry. default Copy `{ "error": { "code": "conflict", "message": "تعذّر إتمام العملية بسبب تعارض. أعد المحاولة." } }` 422 `default` A caller-fixable bad request (validation error, bad date, bad enum). default Copy `{ "error": { "code": "unprocessable_entity", "message": "قيمة due_at غير صالحة؛ أرسل تاريخاً مثل 2026-07-20. المهمة تُستحق في يوم، وأي وقت ترسله يُهمل." } }` 429 `rate_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": ""}` 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) Copy `{ "error": { "code": "rate_limit_exceeded", "message": "استهلكت رصيد اليوم من طلبات API في خطة «المتطور» (1000 طلب يوميًا). يتجدد الرصيد عند منتصف الليل بتوقيت Asia/Riyadh." } }` Over 300 requests in a minute (Rack::Attack body, flat error) Copy `{ "error": "Rate limit exceeded. Please try again later." }` [Errors](https://fareeqy.com/api/v1/docs/en#errors) ### Delete a task by ref DELETE /tasks/ {id} Requires `tasks:destructive` Permanent. #### Path parameters `id` string required The task REF (tsk-9wb7t). A slug is not accepted here. #### Request cURL Copy `curl -X DELETE "https://app.fareeqy.com/api/v1/tasks/tsk-9wb7t" \ -H "Authorization: Bearer $FAREEQY_API_KEY"` #### Response 200 Copy `{ "data": { "deleted": true, "task": { "title": "تصميم الهيدر", "id": "tsk-9wb7t" } } }` Refusals: 401 403 404 429 Show failure examples Hide failure examples 401 `default` Missing or invalid API key. default Copy `{ "error": { "code": "unauthorized", "message": "مفتاح الـ API غير صالح أو غير مُرسَل." } }` 403 `forbidden` 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 Copy `{ "error": { "code": "forbidden", "message": "هذا الـ API key لا يملك صلاحية تنفيذ هذه العملية." } }` The company's plan carries no API access Copy `{ "error": { "code": "plan_upgrade_required", "message": "خطة «الاحترافي» لا تشمل الوصول إلى API. رقِّ إلى «المتطور» أو «الإنتاجي» لتفعيله." } }` 404 `not_found` 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. A record that is missing or out of reach Copy `{ "error": { "code": "not_found", "message": "غير موجود، أو لا تملك صلاحية الوصول إليه." } }` A path that matches no endpoint Copy `{ "error": { "code": "unknown_endpoint", "message": "لا يوجد endpoint يطابق GET /api/v1/projcts. راجع المسار في توثيق الـ API." } }` 429 `rate_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": ""}` 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) Copy `{ "error": { "code": "rate_limit_exceeded", "message": "استهلكت رصيد اليوم من طلبات API في خطة «المتطور» (1000 طلب يوميًا). يتجدد الرصيد عند منتصف الليل بتوقيت Asia/Riyadh." } }` Over 300 requests in a minute (Rack::Attack body, flat error) Copy `{ "error": "Rate limit exceeded. Please try again later." }` [Errors](https://fareeqy.com/api/v1/docs/en#errors) ### Complete a task by ref POST /tasks/ {id} /complete Requires `tasks:write` Idempotent. #### Path parameters `id` string required The task REF (tsk-9wb7t). A slug is not accepted here. #### Request cURL Copy `curl -X POST "https://app.fareeqy.com/api/v1/tasks/tsk-9wb7t/complete" \ -H "Authorization: Bearer $FAREEQY_API_KEY"` #### Response 200 Copy `{ "data": { "id": "tsk-9wb7t", "url": "https://app.fareeqy.com/tasks/tsk-9wb7t", "title": "تصميم الهيدر", "notes": "نحتاج نسخة للجوال ونسخة للديسكتوب.", "completed": false, "completed_at": null, "due_at": "2026-08-10", "time_spent_minutes": 90, "project_slug": "prj-8f3kd", "task_list_slug": "lst-4m2qp", "assignee": { "name": "عبدالله المطيري", "email": "abdullah@example.com" }, "created_at": "2026-07-03T11:40:09.000+03:00" } }` Refusals: 401 403 404 409 422 429 Show failure examples Hide failure examples 401 `default` Missing or invalid API key. default Copy `{ "error": { "code": "unauthorized", "message": "مفتاح الـ API غير صالح أو غير مُرسَل." } }` 403 `forbidden` 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 Copy `{ "error": { "code": "forbidden", "message": "هذا الـ API key لا يملك صلاحية تنفيذ هذه العملية." } }` The company's plan carries no API access Copy `{ "error": { "code": "plan_upgrade_required", "message": "خطة «الاحترافي» لا تشمل الوصول إلى API. رقِّ إلى «المتطور» أو «الإنتاجي» لتفعيله." } }` 404 `not_found` 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. A record that is missing or out of reach Copy `{ "error": { "code": "not_found", "message": "غير موجود، أو لا تملك صلاحية الوصول إليه." } }` A path that matches no endpoint Copy `{ "error": { "code": "unknown_endpoint", "message": "لا يوجد endpoint يطابق GET /api/v1/projcts. راجع المسار في توثيق الـ API." } }` 409 `default` A uniqueness/record conflict; retry. default Copy `{ "error": { "code": "conflict", "message": "تعذّر إتمام العملية بسبب تعارض. أعد المحاولة." } }` 422 `default` A caller-fixable bad request (validation error, bad date, bad enum). default Copy `{ "error": { "code": "unprocessable_entity", "message": "قيمة due_at غير صالحة؛ أرسل تاريخاً مثل 2026-07-20. المهمة تُستحق في يوم، وأي وقت ترسله يُهمل." } }` 429 `rate_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": ""}` 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) Copy `{ "error": { "code": "rate_limit_exceeded", "message": "استهلكت رصيد اليوم من طلبات API في خطة «المتطور» (1000 طلب يوميًا). يتجدد الرصيد عند منتصف الليل بتوقيت Asia/Riyadh." } }` Over 300 requests in a minute (Rack::Attack body, flat error) Copy `{ "error": "Rate limit exceeded. Please try again later." }` [Errors](https://fareeqy.com/api/v1/docs/en#errors) ### Reopen a task by ref POST /tasks/ {id} /incomplete Requires `tasks:write` Idempotent. #### Path parameters `id` string required The task REF (tsk-9wb7t). A slug is not accepted here. #### Request cURL Copy `curl -X POST "https://app.fareeqy.com/api/v1/tasks/tsk-9wb7t/incomplete" \ -H "Authorization: Bearer $FAREEQY_API_KEY"` #### Response 200 Copy `{ "data": { "id": "tsk-9wb7t", "url": "https://app.fareeqy.com/tasks/tsk-9wb7t", "title": "تصميم الهيدر", "notes": "نحتاج نسخة للجوال ونسخة للديسكتوب.", "completed": false, "completed_at": null, "due_at": "2026-08-10", "time_spent_minutes": 90, "project_slug": "prj-8f3kd", "task_list_slug": "lst-4m2qp", "assignee": { "name": "عبدالله المطيري", "email": "abdullah@example.com" }, "created_at": "2026-07-03T11:40:09.000+03:00" } }` Refusals: 401 403 404 409 422 429 Show failure examples Hide failure examples 401 `default` Missing or invalid API key. default Copy `{ "error": { "code": "unauthorized", "message": "مفتاح الـ API غير صالح أو غير مُرسَل." } }` 403 `forbidden` 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 Copy `{ "error": { "code": "forbidden", "message": "هذا الـ API key لا يملك صلاحية تنفيذ هذه العملية." } }` The company's plan carries no API access Copy `{ "error": { "code": "plan_upgrade_required", "message": "خطة «الاحترافي» لا تشمل الوصول إلى API. رقِّ إلى «المتطور» أو «الإنتاجي» لتفعيله." } }` 404 `not_found` 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. A record that is missing or out of reach Copy `{ "error": { "code": "not_found", "message": "غير موجود، أو لا تملك صلاحية الوصول إليه." } }` A path that matches no endpoint Copy `{ "error": { "code": "unknown_endpoint", "message": "لا يوجد endpoint يطابق GET /api/v1/projcts. راجع المسار في توثيق الـ API." } }` 409 `default` A uniqueness/record conflict; retry. default Copy `{ "error": { "code": "conflict", "message": "تعذّر إتمام العملية بسبب تعارض. أعد المحاولة." } }` 422 `default` A caller-fixable bad request (validation error, bad date, bad enum). default Copy `{ "error": { "code": "unprocessable_entity", "message": "قيمة due_at غير صالحة؛ أرسل تاريخاً مثل 2026-07-20. المهمة تُستحق في يوم، وأي وقت ترسله يُهمل." } }` 429 `rate_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": ""}` 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) Copy `{ "error": { "code": "rate_limit_exceeded", "message": "استهلكت رصيد اليوم من طلبات API في خطة «المتطور» (1000 طلب يوميًا). يتجدد الرصيد عند منتصف الليل بتوقيت Asia/Riyadh." } }` Over 300 requests in a minute (Rack::Attack body, flat error) Copy `{ "error": "Rate limit exceeded. Please try again later." }` [Errors](https://fareeqy.com/api/v1/docs/en#errors) ### Move a task to another list, by ref POST /tasks/ {id} /move Requires `tasks:write` Moves the task to another task list, appended to the end. The destination may be in another project of the company. With no project in the path, `target_task_list_slug` must be the list's ref (lst-4m2qp): a slug is not accepted here. #### Path parameters `id` string required The task REF (tsk-9wb7t). A slug is not accepted here. #### Request body `target_task_list_slug` string required The destination task list. On the nested address, its ref, slug or numeric id inside the same project. On the flat address, its ref only, and it may be in another project. Named \_slug for compatibility. #### Request cURL Copy `curl -X POST "https://app.fareeqy.com/api/v1/tasks/tsk-9wb7t/move" \ -H "Authorization: Bearer $FAREEQY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"target_task_list_slug":"lst-7hx2r"}'` #### Response 200 Copy `{ "data": { "id": "tsk-9wb7t", "url": "https://app.fareeqy.com/tasks/tsk-9wb7t", "title": "تصميم الهيدر", "notes": "نحتاج نسخة للجوال ونسخة للديسكتوب.", "completed": false, "completed_at": null, "due_at": "2026-08-10", "time_spent_minutes": 90, "project_slug": "prj-8f3kd", "task_list_slug": "lst-4m2qp", "assignee": { "name": "عبدالله المطيري", "email": "abdullah@example.com" }, "created_at": "2026-07-03T11:40:09.000+03:00" } }` Refusals: 401 403 404 409 422 429 Show failure examples Hide failure examples 401 `default` Missing or invalid API key. default Copy `{ "error": { "code": "unauthorized", "message": "مفتاح الـ API غير صالح أو غير مُرسَل." } }` 403 `forbidden` 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 Copy `{ "error": { "code": "forbidden", "message": "هذا الـ API key لا يملك صلاحية تنفيذ هذه العملية." } }` The company's plan carries no API access Copy `{ "error": { "code": "plan_upgrade_required", "message": "خطة «الاحترافي» لا تشمل الوصول إلى API. رقِّ إلى «المتطور» أو «الإنتاجي» لتفعيله." } }` 404 `not_found` 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. A record that is missing or out of reach Copy `{ "error": { "code": "not_found", "message": "غير موجود، أو لا تملك صلاحية الوصول إليه." } }` A path that matches no endpoint Copy `{ "error": { "code": "unknown_endpoint", "message": "لا يوجد endpoint يطابق GET /api/v1/projcts. راجع المسار في توثيق الـ API." } }` 409 `default` A uniqueness/record conflict; retry. default Copy `{ "error": { "code": "conflict", "message": "تعذّر إتمام العملية بسبب تعارض. أعد المحاولة." } }` 422 `default` A caller-fixable bad request (validation error, bad date, bad enum). default Copy `{ "error": { "code": "unprocessable_entity", "message": "قيمة due_at غير صالحة؛ أرسل تاريخاً مثل 2026-07-20. المهمة تُستحق في يوم، وأي وقت ترسله يُهمل." } }` 429 `rate_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": ""}` 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) Copy `{ "error": { "code": "rate_limit_exceeded", "message": "استهلكت رصيد اليوم من طلبات API في خطة «المتطور» (1000 طلب يوميًا). يتجدد الرصيد عند منتصف الليل بتوقيت Asia/Riyadh." } }` Over 300 requests in a minute (Rack::Attack body, flat error) Copy `{ "error": "Rate limit exceeded. Please try again later." }` [Errors](https://fareeqy.com/api/v1/docs/en#errors) ### Record time spent on a task, by ref POST /tasks/ {id} /time Requires `tasks:write` Records how long the task took. A separate action from PATCH, as it is in the web app., and a plan that carries time tracking (403 otherwise, with nothing recorded). #### Path parameters `id` string required The task REF (tsk-9wb7t). A slug is not accepted here. #### Request cURL Copy `curl -X POST "https://app.fareeqy.com/api/v1/tasks/tsk-9wb7t/time" \ -H "Authorization: Bearer $FAREEQY_API_KEY"` #### Response 200 Copy `{ "data": { "id": "tsk-9wb7t", "url": "https://app.fareeqy.com/tasks/tsk-9wb7t", "title": "تصميم الهيدر", "notes": "نحتاج نسخة للجوال ونسخة للديسكتوب.", "completed": false, "completed_at": null, "due_at": "2026-08-10", "time_spent_minutes": 90, "project_slug": "prj-8f3kd", "task_list_slug": "lst-4m2qp", "assignee": { "name": "عبدالله المطيري", "email": "abdullah@example.com" }, "created_at": "2026-07-03T11:40:09.000+03:00" } }` Refusals: 401 403 404 409 422 429 Show failure examples Hide failure examples 401 `default` Missing or invalid API key. default Copy `{ "error": { "code": "unauthorized", "message": "مفتاح الـ API غير صالح أو غير مُرسَل." } }` 403 `forbidden` 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 Copy `{ "error": { "code": "forbidden", "message": "هذا الـ API key لا يملك صلاحية تنفيذ هذه العملية." } }` The company's plan carries no API access Copy `{ "error": { "code": "plan_upgrade_required", "message": "خطة «الاحترافي» لا تشمل الوصول إلى API. رقِّ إلى «المتطور» أو «الإنتاجي» لتفعيله." } }` 404 `not_found` 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. A record that is missing or out of reach Copy `{ "error": { "code": "not_found", "message": "غير موجود، أو لا تملك صلاحية الوصول إليه." } }` A path that matches no endpoint Copy `{ "error": { "code": "unknown_endpoint", "message": "لا يوجد endpoint يطابق GET /api/v1/projcts. راجع المسار في توثيق الـ API." } }` 409 `default` A uniqueness/record conflict; retry. default Copy `{ "error": { "code": "conflict", "message": "تعذّر إتمام العملية بسبب تعارض. أعد المحاولة." } }` 422 `default` A caller-fixable bad request (validation error, bad date, bad enum). default Copy `{ "error": { "code": "unprocessable_entity", "message": "قيمة due_at غير صالحة؛ أرسل تاريخاً مثل 2026-07-20. المهمة تُستحق في يوم، وأي وقت ترسله يُهمل." } }` 429 `rate_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": ""}` 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) Copy `{ "error": { "code": "rate_limit_exceeded", "message": "استهلكت رصيد اليوم من طلبات API في خطة «المتطور» (1000 طلب يوميًا). يتجدد الرصيد عند منتصف الليل بتوقيت Asia/Riyadh." } }` Over 300 requests in a minute (Rack::Attack body, flat error) Copy `{ "error": "Rate limit exceeded. Please try again later." }` [Errors](https://fareeqy.com/api/v1/docs/en#errors) [Previous Task lists](https://fareeqy.com/api/v1/docs/task-lists/en) [Next Comments](https://fareeqy.com/api/v1/docs/comments/en)