--- title: "Events | Fareeqy API" description: "Company calendar events. Numeric ids. The Events endpoints in the Fareeqy REST API: parameters, request bodies, response examples, and refusals." url: https://fareeqy.com/api/v1/docs/events/en language: en --- # Events Company calendar events. Numeric ids. Base URL `https://app.fareeqy.com/api/v1` Contents On this page - The resource - List calendar events - Create an event - Get an event - Update an event - Delete an event 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 calendar events - Create an event - Get an event - Update an event - Delete an event 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` integer Numeric id (events have no slug). `url` string | null Absolute address of the page a person opens in فريقي. `name` string `description` string | null `starts_at` string (date-time) `ends_at` string (date-time) `all_day` boolean `meeting_url` string | null `organizer` string | null The person who organized the event. A key can edit or delete any event in its company, whoever organized it. `organizer_email` string | null `attendees` object\[\] Event Copy `{ "id": 77, "url": "https://app.fareeqy.com/events/77", "name": "اجتماع مراجعة التصاميم", "description": "نراجع نسخة الهيدر ونقرر الاتجاه النهائي.", "starts_at": "2026-08-05T13:00:00.000+03:00", "ends_at": "2026-08-05T14:00:00.000+03:00", "all_day": false, "meeting_url": "https://meet.google.com/abc-defg-hij", "organizer": "سارة العتيبي", "organizer_email": "sara@example.com", "attendees": [ { "name": "عبدالله المطيري", "email": "abdullah@example.com" } ] }` ### List calendar events GET /events Requires `events:read` Every event on the key's company calendar, whoever organized it. Defaults to upcoming only; an explicit `from` / `to` window wins over `include_past`. Bounds and the "upcoming" cutoff resolve in the company time zone. #### Query parameters `from` string Lower bound on start time (ISO 8601). An explicit window overrides include\_past. `to` string Upper bound on start time (ISO 8601). `include_past` boolean When no from/to window is given, include past events. Default: `false` `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/events" \ -H "Authorization: Bearer $FAREEQY_API_KEY"` #### Response 200 Copy `{ "data": [ { "id": 77, "url": "https://app.fareeqy.com/events/77", "name": "اجتماع مراجعة التصاميم", "description": "نراجع نسخة الهيدر ونقرر الاتجاه النهائي.", "starts_at": "2026-08-05T13:00:00.000+03:00", "ends_at": "2026-08-05T14:00:00.000+03:00", "all_day": false, "meeting_url": "https://meet.google.com/abc-defg-hij", "organizer": "سارة العتيبي", "organizer_email": "sara@example.com", "attendees": [ { "name": "عبدالله المطيري", "email": "abdullah@example.com" } ] } ], "meta": { "total": 4, "limit": 50, "offset": 0, "count": 4 } }` Refusals: 401 403 404 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." } }` 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) ### Create an event POST /events Requires `events:write` Routes through the shared Events::Creator, so attendees are notified and the event syncs to a connected Google Calendar. Naive times parse in the company zone. #### Request body `name` string required `description` string | null `starts_at` string required ISO 8601 (e.g. 2026-07-20T14:00). `ends_at` string required ISO 8601. `all_day` boolean `meeting_url` string | null `attendee_emails` string (email)\[\] Emails of assignable company users to invite. #### Request cURL Copy `curl -X POST "https://app.fareeqy.com/api/v1/events" \ -H "Authorization: Bearer $FAREEQY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"اجتماع مراجعة التصاميم","description":"نراجع نسخة الهيدر ونقرر الاتجاه النهائي.","starts_at":"2026-08-05T13:00","ends_at":"2026-08-05T14:00","all_day":false,"meeting_url":"https://meet.google.com/abc-defg-hij","attendee_emails":["abdullah@example.com"]}'` #### Response 201 Copy `{ "data": { "id": 77, "url": "https://app.fareeqy.com/events/77", "name": "اجتماع مراجعة التصاميم", "description": "نراجع نسخة الهيدر ونقرر الاتجاه النهائي.", "starts_at": "2026-08-05T13:00:00.000+03:00", "ends_at": "2026-08-05T14:00:00.000+03:00", "all_day": false, "meeting_url": "https://meet.google.com/abc-defg-hij", "organizer": "سارة العتيبي", "organizer_email": "sara@example.com", "attendees": [ { "name": "عبدالله المطيري", "email": "abdullah@example.com" } ] } }` 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 an event GET /events/ {id} Requires `events:read` #### Path parameters `id` integer required The event's NUMERIC id (events have no ref and no slug). #### Request cURL Copy `curl "https://app.fareeqy.com/api/v1/events/77" \ -H "Authorization: Bearer $FAREEQY_API_KEY"` #### Response 200 Copy `{ "data": { "id": 77, "url": "https://app.fareeqy.com/events/77", "name": "اجتماع مراجعة التصاميم", "description": "نراجع نسخة الهيدر ونقرر الاتجاه النهائي.", "starts_at": "2026-08-05T13:00:00.000+03:00", "ends_at": "2026-08-05T14:00:00.000+03:00", "all_day": false, "meeting_url": "https://meet.google.com/abc-defg-hij", "organizer": "سارة العتيبي", "organizer_email": "sara@example.com", "attendees": [ { "name": "عبدالله المطيري", "email": "abdullah@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) ### Update an event PATCH /events/ {id} Requires `events:write` Any event in the key's company, whoever organized it. Only passed fields change, EXCEPT `attendee_emails`, which replaces the whole guest list when present. #### Path parameters `id` integer required The event's NUMERIC id (events have no ref and no slug). #### Request body `name` string `description` string | null `starts_at` string ISO 8601. `ends_at` string ISO 8601. `all_day` boolean `meeting_url` string | null `attendee_emails` string (email)\[\] When present, REPLACES the entire attendee list. #### Request cURL Copy `curl -X PATCH "https://app.fareeqy.com/api/v1/events/77" \ -H "Authorization: Bearer $FAREEQY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"","description":null,"starts_at":"","ends_at":"","all_day":false,"meeting_url":null,"attendee_emails":[""]}'` #### Response 200 Copy `{ "data": { "id": 77, "url": "https://app.fareeqy.com/events/77", "name": "اجتماع مراجعة التصاميم", "description": "نراجع نسخة الهيدر ونقرر الاتجاه النهائي.", "starts_at": "2026-08-05T13:00:00.000+03:00", "ends_at": "2026-08-05T14:00:00.000+03:00", "all_day": false, "meeting_url": "https://meet.google.com/abc-defg-hij", "organizer": "سارة العتيبي", "organizer_email": "sara@example.com", "attendees": [ { "name": "عبدالله المطيري", "email": "abdullah@example.com" } ] } }` 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 an event DELETE /events/ {id} Requires `events:destructive` Permanent. Any event in the key's company, whoever organized it. Cascades to personal copies others made of a public event. #### Path parameters `id` integer required The event's NUMERIC id (events have no ref and no slug). #### Request cURL Copy `curl -X DELETE "https://app.fareeqy.com/api/v1/events/77" \ -H "Authorization: Bearer $FAREEQY_API_KEY"` #### Response 200 Copy `{ "data": { "deleted": true, "event": { "id": 77, "name": "اجتماع مراجعة التصاميم" } } }` 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) [Previous Account](https://fareeqy.com/api/v1/docs/account/en) [Next Projects](https://fareeqy.com/api/v1/docs/projects/en)