Fareeqy Account API

openapi: 3.2.0
info:
  title: Fareeqy REST Account 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: Account
  description: The calling key itself and workspace-wide search.
paths:
  /me:
    get:
      tags:
      - Account
      operationId: getMe
      summary: The calling key and the company it acts for
      description: '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. Requires operation `account:read`.'
      x-codeSamples:
      - lang: cURL
        label: curl
        source: "curl -s \"$FRQ_BASE/me\" \\\n  -H \"Authorization: Bearer $FRQ_KEY\"\n"
      responses:
        '200':
          description: The authenticated account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /search:
    get:
      tags:
      - Account
      operationId: search
      summary: Unified workspace search
      description: '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. Requires operation `account:read`.'
      parameters:
      - name: q
        in: query
        description: The search term. Blank returns empty results.
        schema:
          type: string
      - name: types
        in: query
        description: Restrict to these kinds. Omit for all kinds. Unknown names are ignored.
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - project
            - task_list
            - task
            - folder
            - file
            - discussion
      - name: per_type
        in: query
        description: Max hits per kind (default 5, max 25, clamped).
        schema:
          type: integer
          default: 5
          minimum: 1
          maximum: 25
      responses:
        '200':
          description: Search results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      query:
                        type: string
                      results:
                        type: array
                        items:
                          $ref: '#/components/schemas/SearchResult'
                      truncated:
                        type: array
                        description: The kinds that had more matches than were returned.
                        items:
                          type: string
                      widened:
                        type: array
                        description: The kinds where no record matched every word of the query, so the hits are near-misses. Always present, empty when every kind matched exactly.
                        items:
                          type: string
              example:
                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: []
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    AccountEnvelope:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Account'
    SearchFile:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          const: file
        id:
          type: string
          description: The file ref.
        url:
          type:
          - string
          - 'null'
          description: Absolute address of the page a person opens in فريقي.
        name:
          type: string
        project_slug:
          type: string
          description: The project ref. Named _slug for compatibility.
        file_id:
          type: integer
        folder_id:
          type:
          - integer
          - 'null'
      example:
        type: file
        id: fil-3qd8n
        url: https://app.fareeqy.com/files/fil-3qd8n
        name: الهوية-البصرية.pdf
        project_slug: prj-8f3kd
        file_id: 108
        folder_id: 42
    SearchTaskList:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          const: task_list
        id:
          type: string
          description: The task-list ref.
        url:
          type:
          - string
          - 'null'
          description: Absolute address of the page a person opens in فريقي.
        title:
          type: string
        project_slug:
          type: string
          description: The project ref. Named _slug for compatibility.
        task_list_slug:
          type: string
          description: The task-list ref. Named _slug for compatibility.
        completed:
          type: boolean
      example:
        type: task_list
        id: lst-4m2qp
        url: https://app.fareeqy.com/lists/lst-4m2qp
        title: الصفحة الرئيسية
        project_slug: prj-8f3kd
        task_list_slug: lst-4m2qp
        completed: false
    SearchFolder:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          const: folder
        url:
          type:
          - string
          - 'null'
          description: The project's files page scoped to this folder.
        name:
          type: string
        project_slug:
          type: string
          description: The project ref. Named _slug for compatibility.
        folder_id:
          type: integer
      example:
        type: folder
        url: https://app.fareeqy.com/projects/prj-8f3kd/files?folder_id=42
        name: التصاميم
        project_slug: prj-8f3kd
        folder_id: 42
    SearchProject:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          const: project
        id:
          type: string
          description: The project ref.
        url:
          type:
          - string
          - 'null'
          description: Absolute address of the page a person opens in فريقي.
        title:
          type: string
        project_slug:
          type: string
          description: The project ref. Named _slug for compatibility.
        archived:
          type: boolean
      example:
        type: project
        id: prj-8f3kd
        url: https://app.fareeqy.com/projects/prj-8f3kd
        title: تطوير الموقع
        project_slug: prj-8f3kd
        archived: false
    SearchDiscussion:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          const: discussion
        id:
          type: string
          description: The majlis topic ref.
        url:
          type:
          - string
          - 'null'
          description: Absolute address of the page a person opens in فريقي.
        title:
          type: string
        project_slug:
          type: string
          description: The project ref. Named _slug for compatibility.
        discussion_slug:
          type: string
          description: The majlis topic ref. Named _slug for compatibility.
      example:
        type: discussion
        id: mjl-6khz2
        url: https://app.fareeqy.com/majlis/mjl-6khz2
        title: اقتراح لتحسين صفحة التسعير
        project_slug: prj-8f3kd
        discussion_slug: mjl-6khz2
    SearchTask:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          const: task
        id:
          type: string
          description: The task ref.
        url:
          type:
          - string
          - 'null'
          description: Absolute address of the page a person opens in فريقي.
        title:
          type: string
        project_slug:
          type: string
          description: The project ref. Named _slug for compatibility.
        task_list_slug:
          type: string
          description: The task-list ref. Named _slug for compatibility.
        task_slug:
          type: string
          description: The task ref. Named _slug for compatibility.
        completed:
          type: boolean
      example:
        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
    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 "; ").
    SearchResult:
      description: 'A unified search hit. The shape depends on `type`; each carries the refs/ids the other endpoints take, and a `url`.

        '
      oneOf:
      - $ref: '#/components/schemas/SearchProject'
      - $ref: '#/components/schemas/SearchTaskList'
      - $ref: '#/components/schemas/SearchTask'
      - $ref: '#/components/schemas/SearchFolder'
      - $ref: '#/components/schemas/SearchFile'
      - $ref: '#/components/schemas/SearchDiscussion'
      discriminator:
        propertyName: type
        mapping:
          project: '#/components/schemas/SearchProject'
          task_list: '#/components/schemas/SearchTaskList'
          task: '#/components/schemas/SearchTask'
          folder: '#/components/schemas/SearchFolder'
          file: '#/components/schemas/SearchFile'
          discussion: '#/components/schemas/SearchDiscussion'
    Account:
      type: object
      description: The calling ApiKey and the company it acts for (GET /me).
      properties:
        key:
          type: object
          properties:
            name:
              type: string
              description: The label the key was given in the app.
            access:
              type: string
              enum:
              - read
              - write
              description: The scope ceiling. A `write` key also carries `read`.
            operations:
              type: array
              items:
                type: string
              description: Exactly the operations this key may call. Anything else is a 403.
        company:
          type: object
          properties:
            name:
              type:
              - string
              - 'null'
        created_by:
          type: object
          description: Who created the key. A signature, not the permissions the call runs with.
          properties:
            name:
              type:
              - string
              - 'null'
            email:
              type:
              - string
              - 'null'
              format: email
      example:
        key:
          name: مزامنة الفوترة
          access: write
          operations:
          - projects:read
          - tasks:read
          - tasks:write
        company:
          name: فريق التقنية
        created_by:
          name: سارة العتيبي
          email: sara@example.com
  responses:
    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.
    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 غير صالح أو غير مُرسَل.
  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.

        '