Fareeqy Events API

openapi: 3.2.0
info:
  title: Fareeqy REST Events API
  version: 1.3.0
  summary: Authenticated public REST API for Fareeqy project management.
  description: 'The Fareeqy public REST API (`/api/v1`) lets a company automate its projects,

    task lists, tasks, majlis discussions, files, folders and calendar events over

    plain JSON with a Bearer API key. **Preview.** This surface is gated behind the per-company Flipper feature flag

    `rest_api` (off by default). While the flag is disabled for a company, every

    authenticated endpoint returns **404** — the surface is hidden, not merely

    forbidden. Authentication is checked first (a bad key is still 401), then the

    flag, so the 404 only appears once a valid key has been presented. With the flag on, the PLAN decides access: Free and Pro carry no API calls, so

    a key on either is refused **403** `plan_upgrade_required`. There is deliberately no "my tasks" or "my personal tasks" endpoint. A key

    belongs to the COMPANY and the person on it merely created it, so "assigned

    to me" has no answer a company credential can give. Both lists remain on the

    MCP server, whose Personal Access Token really is personal. ## Vocabulary


    Product vocabulary and the internal schema differ, and this API follows the

    **product**:


    | API term | Path segment | What it is |

    |---|---|---|

    | Task list | `/lists` | A container that groups tasks within a project (schema model `Task`) |

    | Task | `/tasks` | The actionable item a user checks off (schema model `Todo`) |

    | Majlis topic / discussion | `/discussions` | A project discussion thread |


    ## Identifiers


    Every nested path segment accepts **any** shape below: the ref, the slug, or

    the record''s numeric id. The flat addresses take the ref only. Reads hand back

    the ref, so a client that follows its own output stays on refs without

    deciding anything. - **Refs** are the current identifier: a short ASCII handle like `prj-8f3kd`,

    `lst-4m2qp`, `tsk-9wb7t`, `mjl-6khz2`, `fil-3qd8n` — the same string the

    فريقي web app shows in its address bar, so a person can paste a link

    straight into a script. Three properties are worth knowing: a ref never

    changes when the record is renamed; it needs no percent-encoding; and the

    prefix is checked, so `/lists/tsk-…` is a 404 rather than a wrong

    record of the wrong kind. This is what the `id` field of every project,

    task list, task and discussion response contains, and the `id` of a file

    hit in search. A file response itself carries its numeric id. - **Slugs** are the older identifier and keep working on every nested

    address, including slugs retired by a rename. The flat addresses refuse them. A slug is unique only **within its parent**, so

    URLs stay fully nested and every slug is resolved through its parent (a

    task-list slug can repeat across projects). Never assume a slug is globally

    unique, and remember an Arabic slug must be percent-encoded. - **Numeric ids** address the records that have no ref: folders, events,

    comments, and the files attached inside a comment. A file accepts both its

    `fil-` ref and its numeric id on the nested routes, and projects, task

    lists, tasks and discussions accept their numeric id there too. These ids

    are global, so the API always drills a lookup through the parent project

    (or, for events, the key''s company): a numeric id from another company

    resolves to 404, never a leak. Parameters are still **named** `*_slug` in the paths and the schemas below. That is compatibility, not a constraint: renaming a public parameter would

    break every caller, and widening what one accepts breaks nobody. Read them as

    "handle". The same holds for the `*_slug` fields in responses (`project_slug`,

    `task_list_slug`, `task_slug`, `discussion_slug`): they carry the ref, not a

    slug. ## Links


    Every project, task list, task, discussion, comment, file, folder, event and

    search hit carries `url`: the absolute address of the page a person opens in

    فريقي. A comment has no page of its own, so its `url` is its parent''s page; a

    folder''s is the files page scoped to that folder. A project member is the one

    record without a `url`. Link to it rather than building the address yourself.'
  x-operation-catalog:
    description: 'The full operation catalog (Api::OperationRegistry). read needs the read scope; write needs the write scope; destructive needs the write scope AND is excluded from the write preset''s default grant (opt-in per key). `account` has no destructive operation.

      '
    account:
      read:
      - account:read
    projects:
      read:
      - projects:read
      write:
      - projects:write
      destructive:
      - projects:destructive
    task_lists:
      read:
      - task_lists:read
      write:
      - task_lists:write
      destructive:
      - task_lists:destructive
    tasks:
      read:
      - tasks:read
      write:
      - tasks:write
      destructive:
      - tasks:destructive
    discussions:
      read:
      - discussions:read
      write:
      - discussions:write
      destructive:
      - discussions:destructive
    comments:
      read:
      - comments:read
      write:
      - comments:write
    files:
      read:
      - files:read
      write:
      - files:write
      destructive:
      - files:destructive
    events:
      read:
      - events:read
      write:
      - events:write
      destructive:
      - events:destructive
servers:
- url: https://app.fareeqy.com/api/v1
  description: Production. The app runs on app.fareeqy.com (fareeqy.com is the marketing site and answers no API call). The base path (/api/v1) is part of the server URL, so operation paths below are written relative to it (e.g. /projects).
security:
- bearerAuth: []
tags:
- name: Events
  description: Company calendar events. Numeric ids.
paths:
  /events:
    get:
      tags:
      - Events
      operationId: listEvents
      summary: List calendar events
      description: '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. Requires operation

        `events:read`.'
      parameters:
      - name: from
        in: query
        description: Lower bound on start time (ISO 8601). An explicit window overrides include_past.
        schema:
          type: string
      - name: to
        in: query
        description: Upper bound on start time (ISO 8601).
        schema:
          type: string
      - name: include_past
        in: query
        description: When no from/to window is given, include past events.
        schema:
          type: boolean
          default: false
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: A page of events.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/CollectionMeta'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/Event'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      tags:
      - Events
      operationId: createEvent
      summary: Create an event
      description: '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. Requires operation `events:write`.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - starts_at
              - ends_at
              properties:
                name:
                  type: string
                description:
                  type:
                  - string
                  - 'null'
                starts_at:
                  type: string
                  description: ISO 8601 (e.g. 2026-07-20T14:00).
                ends_at:
                  type: string
                  description: ISO 8601.
                all_day:
                  type: boolean
                  default: false
                meeting_url:
                  type:
                  - string
                  - 'null'
                attendee_emails:
                  type: array
                  description: Emails of assignable company users to invite.
                  items:
                    type: string
                    format: email
            example:
              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
      responses:
        '201':
          description: The created event.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
  /events/{id}:
    parameters:
    - $ref: '#/components/parameters/EventId'
    get:
      tags:
      - Events
      operationId: getEvent
      summary: Get an event
      description: Requires operation `events:read`.
      responses:
        '200':
          description: The event.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
    patch:
      tags:
      - Events
      operationId: updateEvent
      summary: Update an event
      description: '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. Requires

        operation `events:write`.'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type:
                  - string
                  - 'null'
                starts_at:
                  type: string
                  description: ISO 8601.
                ends_at:
                  type: string
                  description: ISO 8601.
                all_day:
                  type: boolean
                meeting_url:
                  type:
                  - string
                  - 'null'
                attendee_emails:
                  type: array
                  description: When present, REPLACES the entire attendee list.
                  items:
                    type: string
                    format: email
            examples:
              rename_only:
                summary: Change the title and nothing else
                description: '`attendee_emails` is absent, so the guest list is left exactly as it was. Times are untouched too.

                  '
                value:
                  name: اجتماع مراجعة التصاميم (نسخة مُحدثة)
              replace_guest_list:
                summary: Replace the whole guest list
                description: '`attendee_emails` is PRESENT, so it is the complete new list. Anyone missing from it is uninvited. Sending an empty array removes everyone.

                  '
                value:
                  attendee_emails:
                  - abdullah@example.com
                  - sara@example.com
      responses:
        '200':
          description: The updated event.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
    delete:
      tags:
      - Events
      operationId: deleteEvent
      summary: Delete an event
      description: 'Permanent. Any event in the key''s company, whoever organized it. Cascades

        to personal copies others made of a public event. Requires operation `events:destructive`.'
      responses:
        '200':
          description: Deletion result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    allOf:
                    - $ref: '#/components/schemas/DeletedBase'
                    - type: object
                      properties:
                        event:
                          type: object
                          properties:
                            id:
                              type: integer
                            name:
                              type: string
              example:
                data:
                  deleted: true
                  event:
                    id: 77
                    name: اجتماع مراجعة التصاميم
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  responses:
    Conflict:
      description: A uniqueness/record conflict; retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: conflict
              message: تعذّر إتمام العملية بسبب تعارض. أعد المحاولة.
    Forbidden:
      description: '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.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            forbidden:
              summary: This key may not perform this operation
              value:
                error:
                  code: forbidden
                  message: هذا الـ API key لا يملك صلاحية تنفيذ هذه العملية.
            plan_upgrade_required:
              summary: The company's plan carries no API access
              value:
                error:
                  code: plan_upgrade_required
                  message: خطة «الاحترافي» لا تشمل الوصول إلى API. رقِّ إلى «المتطور» أو «الإنتاجي» لتفعيله.
    NotFound:
      description: '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.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            not_found:
              summary: A record that is missing or out of reach
              value:
                error:
                  code: not_found
                  message: غير موجود، أو لا تملك صلاحية الوصول إليه.
            unknown_endpoint:
              summary: A path that matches no endpoint
              value:
                error:
                  code: unknown_endpoint
                  message: لا يوجد endpoint يطابق GET /api/v1/projcts. راجع المسار في توثيق الـ API.
    Unprocessable:
      description: A caller-fixable bad request (validation error, bad date, bad enum).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: unprocessable_entity
              message: قيمة due_at غير صالحة؛ أرسل تاريخاً مثل 2026-07-20. المهمة تُستحق في يوم، وأي وقت ترسله يُهمل.
    RateLimited:
      description: 'Either the company''s daily API allowance is spent (`rate_limit_exceeded`), or the per-key / per-IP burst throttle of 300 requests per minute fired. Both come back after a wait, so `Retry-After` is honest here.


        **The two bodies are not the same shape.** The daily-quota refusal uses the standard error envelope. The burst throttle is served by Rack::Attack ahead of the application, so its body is a flat `{"error": "<string>"}` with no `code`. A client that reads `error.code` has to tolerate `error` being a plain string.

        '
      headers:
        Retry-After:
          description: Seconds to wait before retrying. On a spent daily allowance this points at the company's next midnight.
          schema:
            type: integer
        X-RateLimit-Limit:
          description: The plan's daily API allowance, or `unlimited`.
          schema:
            type: string
        X-RateLimit-Remaining:
          description: Calls left in today's allowance, or `unlimited`.
          schema:
            type: string
        X-RateLimit-Reset:
          description: Unix timestamp of the next reset (the company's next midnight).
          schema:
            type: integer
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/Error'
            - type: object
              description: The Rack::Attack burst-throttle body. Flat, with no error code.
              required:
              - error
              properties:
                error:
                  type: string
          examples:
            rate_limit_exceeded:
              summary: Today's daily allowance is spent (application envelope)
              value:
                error:
                  code: rate_limit_exceeded
                  message: استهلكت رصيد اليوم من طلبات API في خطة «المتطور» (1000 طلب يوميًا). يتجدد الرصيد عند منتصف الليل بتوقيت Asia/Riyadh.
            burst_throttled:
              summary: Over 300 requests in a minute (Rack::Attack body, flat error)
              value:
                error: Rate limit exceeded. Please try again later.
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: unauthorized
              message: مفتاح الـ API غير صالح أو غير مُرسَل.
  parameters:
    Limit:
      name: limit
      in: query
      description: Page size (default 50, max 100, clamped).
      schema:
        type: integer
        default: 50
        minimum: 1
        maximum: 100
    EventId:
      name: id
      in: path
      required: true
      description: The event's NUMERIC id (events have no ref and no slug).
      schema:
        type: integer
    Offset:
      name: offset
      in: query
      description: Number of records to skip (default 0).
      schema:
        type: integer
        default: 0
        minimum: 0
  schemas:
    EventEnvelope:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Event'
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: A stable machine-readable slug.
              enum:
              - unauthorized
              - forbidden
              - plan_upgrade_required
              - not_found
              - unknown_endpoint
              - unprocessable_entity
              - conflict
              - project_in_use
              - bad_request
              - rate_limit_exceeded
            message:
              type: string
              description: A human-readable explanation in Arabic (may join several validation messages with "; ").
    CollectionMeta:
      type: object
      properties:
        meta:
          type: object
          properties:
            total:
              type: integer
              description: The full unfiltered count.
            limit:
              type: integer
            offset:
              type: integer
            count:
              type: integer
              description: Records in the returned page.
      example:
        meta:
          total: 4
          limit: 50
          offset: 0
          count: 4
    Event:
      type: object
      properties:
        id:
          type: integer
          description: Numeric id (events have no slug).
        url:
          type:
          - string
          - 'null'
          description: Absolute address of the page a person opens in فريقي.
        name:
          type: string
        description:
          type:
          - string
          - 'null'
        starts_at:
          type: string
          format: date-time
        ends_at:
          type: string
          format: date-time
        all_day:
          type: boolean
        meeting_url:
          type:
          - string
          - 'null'
        organizer:
          type:
          - string
          - 'null'
          description: The person who organized the event. A key can edit or delete any event in its company, whoever organized it.
        organizer_email:
          type:
          - string
          - 'null'
        attendees:
          type: array
          items:
            $ref: '#/components/schemas/UserRef'
      example:
        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
    UserRef:
      type: object
      description: A user reference — name for humans, email as the write handle.
      properties:
        name:
          type: string
        email:
          type: string
          format: email
      example:
        name: عبدالله المطيري
        email: abdullah@example.com
    DeletedBase:
      type: object
      required:
      - deleted
      properties:
        deleted:
          type: boolean
          const: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'An ApiKey presented as a Bearer credential. Keys carry the `frq_api_` prefix and are shown once at creation (only their SHA-256 digest is stored). Isolated from the MCP server''s Personal Access Tokens (`frq_`).


        A key belongs to the **company**, not to a person: it is administered from /settings/api_keys by the company owner or anyone granted the `manage_api_keys` permission, who can see and revoke every key the company has. Its capability is its own `allowed_operations` and its reach is the whole company; the person who created it is recorded as a signature and is not whose permissions the call runs with.


        So a key stops authenticating (401) for two reasons and no others: revocation and expiry. With the API switched off for the company, a valid key gets 404 instead: the surface is hidden. A key is explicitly unaffected by its creator changing role or leaving.

        '