Fareeqy Folders API

openapi: 3.2.0
info:
  title: Fareeqy REST Folders 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: Folders
  description: Folders in a project's files section. Numeric ids.
paths:
  /projects/{project_id}/folders:
    parameters:
    - $ref: '#/components/parameters/ProjectId'
    post:
      tags:
      - Folders
      operationId: createFolder
      summary: Create a folder
      description: Creates a folder. Requires operation `files:write`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                description:
                  type:
                  - string
                  - 'null'
                parent_folder_id:
                  type:
                  - integer
                  - 'null'
                  description: Parent folder; omit for the project root.
            example:
              name: التصاميم
              description: ملفات الهوية وواجهات الموقع.
              parent_folder_id: null
      responses:
        '201':
          description: The created folder.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderEnvelope'
        '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'
  /projects/{project_id}/folders/{id}:
    parameters:
    - $ref: '#/components/parameters/ProjectId'
    - $ref: '#/components/parameters/FolderId'
    delete:
      tags:
      - Folders
      operationId: deleteFolder
      summary: Delete a folder
      description: 'Permanent, RECURSIVE: the folder and its entire subtree (every subfolder

        and file, whoever uploaded them). Requires operation `files:destructive`.'
      responses:
        '200':
          description: Deletion result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    allOf:
                    - $ref: '#/components/schemas/DeletedBase'
                    - type: object
                      properties:
                        folder:
                          type: object
                          properties:
                            id:
                              type: integer
                            name:
                              type: string
                        destroyed:
                          type: object
                          properties:
                            files:
                              type: integer
                            subfolders:
                              type: integer
              example:
                data:
                  deleted: true
                  folder:
                    id: 42
                    name: التصاميم
                  destroyed:
                    files: 7
                    subfolders: 1
        '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:
    FolderId:
      name: id
      in: path
      required: true
      description: The folder's NUMERIC id (folders have no slug).
      schema:
        type: integer
    ProjectId:
      name: project_id
      in: path
      required: true
      description: The project REF, or its slug.
      schema:
        type: string
  schemas:
    DeletedBase:
      type: object
      required:
      - deleted
      properties:
        deleted:
          type: boolean
          const: true
    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 "; ").
    FolderEnvelope:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Folder'
    Folder:
      type: object
      properties:
        id:
          type: integer
          description: Numeric id (folders have no slug).
        url:
          type:
          - string
          - 'null'
          description: The project's files page scoped to this folder.
        name:
          type: string
        path:
          type: string
        description:
          type:
          - string
          - 'null'
        parent_folder_id:
          type:
          - integer
          - 'null'
        created_at:
          type: string
          format: date-time
      example:
        id: 42
        url: https://app.fareeqy.com/projects/prj-8f3kd/files?folder_id=42
        name: التصاميم
        path: التصاميم
        description: ملفات الهوية وواجهات الموقع.
        parent_folder_id: null
        created_at: '2026-07-05T08:20:00.000+03:00'
  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.

        '