External Integrations with the Fareeqy API

The API is available on the Advanced, Productive and Enterprise plans. The Free and Pro plans carry no API access at all: a request from them is refused with 403 and plan_upgrade_required, and retrying will never help.

The surface is in preview and switched on per company. While it is off for yours, every authenticated path 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.

To switch the API on for your company, or to ask for higher limits, get in touch and we will enable it on your account.

Every request carries its API key in the Authorization header as a Bearer credential. A key is shown once at creation (only its hashed digest is stored), so save yours when you mint it.

curl "https://app.fareeqy.com/api/v1/me" \
  -H "Authorization: Bearer $FAREEQY_API_KEY"

REST keys and MCP tokens are separate credentials; neither authenticates against the other's interface.

• The key belongs to the company, not its creator, and works after they leave.

• An operation not granted to the key ← 403.

• The key reaches every company project, including private ones.

• A record belonging to another company ← 404.

• created_by names the key creator, not the request identity.

• Key administration: owner and authorized users; not managers or members.

Every endpoint declares the single operation it requires, a stable <resource>:<capability> string such as projects:write. A key is gated twice before a request runs.

• Scope is the ceiling: read or write. A write key also carries read. The scope decides which operations a key may ever hold.

• The allowed-operations list is the operative gate: the explicit operations this key may call, validated to be a subset of what its scope permits. Empty means nothing, so a key is never accidentally open.

Both must hold: the operation must be in the key's list, and its scope must satisfy the operation's capability. Otherwise the request is refused with 403 and audited as denied.

Deletes are opt-in. destructive operations need the write scope but are deliberately excluded from the default grant: each delete is ticked on a key by hand. See the operation catalog below.

Projects, task lists, tasks and majlis topics are addressed by a readable slug. A slug is unique only within its parent, so URLs are fully nested and every slug resolves through its parent: the same task-list slug can repeat across projects. Never assume a slug is globally unique.

Files, folders, events and comments are addressed by numeric ids. Those ids are global, so every lookup is drilled through the parent project (or, for events, the caller's accessible set): an id from another company resolves to 404, never a leak.

Slugs are Arabic because your project names are. URL-encode them before sending: تطوير-الموقع becomes %D8%AA%D8%B7%D9%88%D9%8A%D8%B1-.... The examples here show the raw text so they stay readable.

Every response is enveloped, so you never handle a bare array or a root-level field.

• Single resource: { "data": { ... } }

• Collection: { "data": [ ... ], "meta": { total, limit, offset, count } }

• Delete: { "data": { "deleted": true, ... } }

• Error: { "error": { "code": "...", "message": "..." } }

Collections take limit (default 50, max 100, clamped) and offset (default 0). meta.total is the full unfiltered count; meta.count is the number of records in the returned page.

Two independent layers, and they refuse differently.

Burst. Each key is throttled to 300 requests per minute, and a matching per-IP throttle applies too. Crossing either returns 429.

Daily quota. Every request spends one call from the company's daily allowance. The allowance is per company, not per key, so minting extra keys does not raise it, and it resets at midnight in your company's own time zone.

A plan with no access is not being rate-limited: its refusal is 403 plan_upgrade_required and carries no Retry-After, because waiting will never help. A plan that has access and has spent today's calls gets 429 rate_limit_exceeded with a Retry-After pointing at your company's next midnight. Treating the two as the same failure sends a well-behaved client into a retry loop that can never succeed.

X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset are set on every served response, not only on refusals, so your client can slow down before it reaches zero. On an uncapped plan the first two read unlimited.