--- title: "Account | Fareeqy API" description: "The calling key itself and workspace-wide search. The Account endpoints in the Fareeqy REST API: parameters, request bodies, response examples, and refusals." url: https://fareeqy.com/api/v1/docs/account/en language: en --- # Account The calling key itself and workspace-wide search. Base URL `https://app.fareeqy.com/api/v1` Contents On this page - The resource - The calling key and the company it acts for - Unified workspace search 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 - The calling key and the company it acts for - Unified workspace search 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. `key` object `company` object `created_by` object Who created the key. A signature, not the permissions the call runs with. Account Copy `{ "key": { "name": "مزامنة الفوترة", "access": "write", "operations": [ "projects:read", "tasks:read", "tasks:write" ] }, "company": { "name": "فريق التقنية" }, "created_by": { "name": "سارة العتيبي", "email": "sara@example.com" } }` ### The calling key and the company it acts for GET /me Requires `account:read` Returns the key itself — its name, its access level and the exact operations it may call — plus the company it acts for. The canonical "is my key valid, and what does it reach?" check. `created_by` names the person who created the key; it is a signature, not the identity the call runs as. #### Request cURL Copy `curl "https://app.fareeqy.com/api/v1/me" \ -H "Authorization: Bearer $FAREEQY_API_KEY"` #### Response 200 Copy `{ "data": { "key": { "name": "مزامنة الفوترة", "access": "write", "operations": [ "projects:read", "tasks:read", "tasks:write" ] }, "company": { "name": "فريق التقنية" }, "created_by": { "name": "سارة العتيبي", "email": "sara@example.com" } } }` 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) ### Unified workspace search GET /search Requires `account:read` Finds projects, task lists, tasks, folders, files and majlis topics by name (Arabic-normalized, within the key's company). Returns the refs and ids the other endpoints take. Each kind is capped independently ( `per_type` ); `truncated` names every kind that had more matches than were returned. `widened` names every kind where no record carried every word of the query, so its hits are near-misses: check one before acting on it. A blank `q` returns empty results. #### Query parameters `q` string The search term. Blank returns empty results. `types` string\[\] Restrict to these kinds. Omit for all kinds. Unknown names are ignored. `per_type` integer Max hits per kind (default 5, max 25, clamped). Default: `5` #### Request cURL Copy `curl "https://app.fareeqy.com/api/v1/search" \ -H "Authorization: Bearer $FAREEQY_API_KEY"` #### Response 200 Copy `{ "data": { "query": "تصميم", "results": [ { "type": "project", "id": "prj-8f3kd", "url": "https://app.fareeqy.com/projects/prj-8f3kd", "title": "تطوير الموقع", "project_slug": "prj-8f3kd", "archived": false }, { "type": "task", "id": "tsk-9wb7t", "url": "https://app.fareeqy.com/tasks/tsk-9wb7t", "title": "تصميم الهيدر", "project_slug": "prj-8f3kd", "task_list_slug": "lst-4m2qp", "task_slug": "tsk-9wb7t", "completed": false }, { "type": "folder", "url": "https://app.fareeqy.com/projects/prj-8f3kd/files?folder_id=42", "name": "التصاميم", "project_slug": "prj-8f3kd", "folder_id": 42 } ], "truncated": [ "task" ], "widened": [] } }` 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) [Back to the overview](https://fareeqy.com/api/v1/docs/en) [Next Events](https://fareeqy.com/api/v1/docs/events/en)