# ProjectSend API guide The API lets an external tool act on your installation: list and download files, upload new ones, share them with clients, and manage client accounts and groups. Everything here describes **v1**, mounted at `/api/v1`. The machine-readable specification is at `GET /api/v1/openapi.json` and can be imported straight into Postman, Insomnia or a code generator. --- ## Getting started 1. Sign in and go to **Settings → API tokens**. 2. Create a token, tick only the permissions the tool needs, and give it an expiry. 3. Copy the token immediately — it is shown once and never again. Only a hash is stored. Then: ```bash curl -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json" \ https://your-install.example.com/api/v1/me ``` `GET /api/v1/me` is the first call worth making. It tells you who the token belongs to, which abilities it *effectively* has, which edition this installation runs, and which optional modules are available. --- ## Authentication Bearer tokens only: ``` Authorization: Bearer 1|psend_xxxxxxxxxxxxxxxxxxxx ``` There is no cookie or session authentication on `/api/*`, and no password-login endpoint. Tokens are created in the web interface, by a person who has already signed in and confirmed their password. That is a deliberate limitation: it keeps passwords off the API entirely. **Staff accounts only.** Client accounts cannot hold a working token in v1. Three things must hold for a call to succeed, on every request: | | | |---|---| | The token carries the ability | Chosen when the token was created or last edited | | The owner still holds the permission | Re-checked live — a demoted account's token loses the ability immediately, without anyone revoking it | | This edition has the feature | Community-only features are unavailable on cloud installs and vice versa | A token can therefore never do more than the person who created it, and never more than it could on the day it was minted. ### Expiry and revocation Every token has an expiry (default 90 days, maximum 365). "Never expires" exists but is off by default — a token nobody ever rotates is a password nobody ever changes. Revoke from the settings page, or let a token retire itself: ```bash curl -X DELETE -H "Authorization: Bearer YOUR_TOKEN" \ https://your-install.example.com/api/v1/tokens/current ``` That revokes only the calling token. Revoking someone else's is deliberately a web-only action. --- ## Abilities An ability is one of the installation's permission keys. The token creation screen lists only the ones you hold *and* that the API can currently act on, so what you see there is the authoritative list for your account. | Ability | Unlocks | |---|---| | `upload` | list files, upload | | `edit_files` / `edit_others_files` | read and edit file metadata, share files | | `delete_files` / `delete_others_files` | delete files | | `set_file_expiration_date` | set `expires_at` when editing | | `set_file_categories` | set `categories` when editing | | `limit_downloads` | set `download_limit` and `download_limit_scope` when editing | | `upload_public` | set `public` when editing | | `upload` / `edit_files` / `edit_others_files` | read and write a file's comments | | `manage_clients` | list clients | | `create_clients` / `edit_clients` / `delete_clients` | create, read and edit, delete clients; `edit_clients` also removes a client's two-factor authentication | | `manage_groups` | list groups | | `moderate_comments` | list what is awaiting approval, and approve it | | `manage_users` | list staff accounts and the roles you may assign — **Community only** | | `create_users` / `edit_users` / `delete_users` | create, read and edit, delete staff accounts; `edit_users` also removes an account's two-factor authentication — **Community only** | There is no ability for *writing* a comment. Who may comment is an installation setting rather than a per-role permission, so the file abilities are the gate — the same question the web asks, which is "can you see this file". Removing somebody *else's* comment sits there too, because the same endpoint also lets an author remove their own within the editing window and that is not moderation; it additionally requires the token's owner to hold `moderate_comments`, checked live against the account rather than carried by the token. | `create_groups` / `edit_groups` / `delete_groups` | create, read and edit (including membership), delete groups | Where an endpoint accepts several — `edit_files` *or* `edit_others_files` — holding either is enough, and which one applies to a given file depends on whether you uploaded it. Every operation in the OpenAPI document names its own requirement. --- ## Responses Successful responses wrap the payload in `data`: ```json { "data": { "id": 12, "name": "Quarterly report" } } ``` List endpoints add cursor pagination: ```json { "data": [ … ], "links": { "next": "…?cursor=eyJ…" }, "meta": { … } } ``` ### Errors Errors are [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem documents, served as `application/problem+json`: ```json { "type": "validation_failed", "title": "The given data was invalid.", "status": 422, "errors": { "name": ["The name field is required."] } } ``` `type` is a stable slug you can branch on. `title` and `detail` are prose and may be reworded. | Status | `type` | Means | |---|---|---| | 401 | `unauthenticated` | Missing, malformed, expired or revoked token | | 403 | `forbidden` | The token, the account, or the edition lacks what this call needs | | 404 | `not_found` | No such resource, or none you may see | | 413 | `payload_too_large` | Upload part over the size limit | | 422 | `validation_failed` | See `errors` | | 429 | `too_many_requests` | Slow down; honour `Retry-After` | --- ## Rate limits Limits are per token, so one integration cannot exhaust another's allowance. Every response carries: ``` X-RateLimit-Limit: 120 X-RateLimit-Remaining: 118 ``` and a `Retry-After` header on 429. Uploads have their own, tighter bucket. > **Self-hosting behind a proxy?** Set `TRUSTED_PROXIES`. Without it every request appears to come > from the proxy, so unauthenticated rate limits collapse into one shared bucket and the download IP > log records the proxy instead of the caller. --- ## Reading a list, and polling for changes All list endpoints accept `per_page` (capped) and `cursor`. Pass the `links.next` URL back verbatim to walk forward. To watch for changes — the usual reason an automation tool calls an API on a timer — pass `updated_since`: ```bash curl -H "Authorization: Bearer YOUR_TOKEN" \ "https://your-install.example.com/api/v1/files?updated_since=2026-08-06T09:00:00Z" ``` With `updated_since` the walk is ordered oldest-first by last-modified time, so new and edited rows always arrive at the end and paging forward visits every row exactly once. Keep the highest `updated_at` you have seen and pass it on the next poll. The boundary is inclusive, so you will occasionally re-see the row exactly on your watermark; de-duplicate by `id`. That is the safe direction of the trade — excluding it could drop a row that shares a timestamp with another. **Polling cannot see deletions.** A deleted row simply stops appearing. If you need to react to deletions, that is what webhooks will be for; they are not built yet. --- ## Uploading Two ways, and the right one depends on the file. ### One request ```bash curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \ -F "file=@report.pdf" \ -F "name=Quarterly report" \ https://your-install.example.com/api/v1/files ``` Simple, and fine up to this installation's configured maximum upload size. There is no resume: a dropped connection means starting again. The stored content type is detected from the bytes, not from what you declare. ### Resumable, in parts For large files or unreliable connections. Four steps: 1. `POST /uploads` with `filename` and `size` → returns an `uploadId`. 2. For each part, `GET /uploads/{id}/parts/{n}/sign` → returns a short-lived signed URL; `PUT` the part's bytes to it. Parts may go in any order, and `GET /uploads/{id}/parts` lists what has arrived, so an interrupted upload resumes rather than restarts. 3. `POST /uploads/{id}/complete` → assembles the parts and returns the created file. 4. `DELETE /uploads/{id}` abandons an upload you no longer want. The size you declare in step 1 is checked again against the assembled bytes at step 3, so it is a courtesy, not a promise the server trusts. --- ## Sharing a file Sharing is a file plus a target: ```bash curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"type":"client","id":42}' \ https://your-install.example.com/api/v1/files/12/assignments ``` `type` is `client` or `group`. This is idempotent — assigning twice changes nothing — so retrying a request that may already have succeeded is safe. It also does everything the web interface does: the recipient gets an in-app notification, and the share email follows on the usual delay. `DELETE` with the same body revokes the share. ### Files that are new versions of other files A file can be marked as a new version of an earlier one: ```bash curl -X PUT -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"previous_file_id":11}' \ https://your-install.example.com/api/v1/files/12/version ``` **A new version is shared with exactly the people the original is shared with.** It has no recipients of its own, so assigning it returns `422` and names the file to assign instead — every version follows that one. Any recipients the file already had are moved onto the original when you link it, so nobody loses access. `DELETE /files/12/version` removes the link. The file then keeps a copy of the recipients it was inheriting, so unlinking does not revoke anything either. Every file carries `is_revision`, `sharing_root_id`, `previous_version` and `next_version`. The last two are narrowed to what your token may see: a counterpart outside your reach reads as `null`. --- ## Staff accounts `/users` manages the people who administer the installation, and the role assigned to each of them. Clients are a different population with their own `/clients` endpoints and never appear here. **Community only.** Every endpoint under `/users` and `/roles` answers `403` with `type: capability_unavailable` on a managed installation, where staff accounts are created outside the application instead. The paths are still registered there, and still in this document, so that the specification is identical on every install — the refusal tells you why, where a missing route would not. Two abilities are needed for each call: `manage_users` to reach the area at all, then the one for the action (`create_users`, `edit_users`, `delete_users`). That mirrors the web UI, where the whole section sits behind `manage_users` and each button behind its own key. ### Two rules that will refuse you **You cannot hand out authority you do not hold.** `role_id` must name a role you could grant yourself: a caller who is not an administrator may not create one, nor assign any role carrying a permission they lack, nor touch an account whose role already outranks them (that one is a `403`). `GET /roles` lists exactly what is available to you, so the safe move is to read it rather than guess an id. **The installation always keeps an active administrator.** Demoting, deactivating or deleting the last one is a `422`. So is deactivating or deleting yourself, from either surface. ### Changing a role The assigned role is a field on the account, so `PATCH /users/{user}` with `role_id` is the whole operation. `assigned_clients` only means anything for a `client_scoped` role; moving to any other role clears it, whether or not you mention it. Creating and deleting *roles themselves* is deliberately not on the API: a role is a security boundary, and changing one is a deliberate act performed in the UI. ## Deleting a client If the client owns files or folders, you must say what happens to them: ```bash curl -X DELETE -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"content_action":"reassign","reassign_to_id":3}' \ https://your-install.example.com/api/v1/clients/42 ``` `content_action` is `cascade_delete` or `reassign`. There is no default: one would silently destroy the files, the other would silently hand them to somebody else. `GET /clients/{id}` reports the counts so you can decide first. A client owning nothing deletes with no body at all. --- ## Unlocking an account whose second factor is lost Two-factor authentication has a failure mode that nothing else in the API does: when the authenticator app and the recovery codes are both gone, the account cannot be opened by its holder *or* by anybody else. `DELETE` the second factor to put the account back to password-only sign-in: ```bash curl -X DELETE -H "Authorization: Bearer YOUR_TOKEN" \ https://your-install.example.com/api/v1/clients/42/two-factor curl -X DELETE -H "Authorization: Bearer YOUR_TOKEN" \ https://your-install.example.com/api/v1/users/7/two-factor ``` `edit_clients` and `edit_users` respectively — this changes how an account signs in, it does not remove one, so it is not the `delete_*` key. Both answer `204` whether or not a second factor was actually in force, and the staff route additionally refuses (`403`) an account whose role outranks the caller's, exactly like `PATCH` does. Two things always happen, and neither is optional: the account holder is emailed that it happened, and the call is recorded in the activity log against the token's owner. If the installation enforces two-factor authentication for that population, the account is asked to enrol again on its next sign-in — this un-sticks an account, it does not exempt one. `two_factor_enabled` on `GET /clients`, `GET /clients/{client}`, `GET /users` and `GET /users/{user}` tells you whether there is anything to remove. --- ## Retries and duplicate requests Assignments and group membership are idempotent. **Creating a file or a client is not** — a retried `POST` that actually succeeded the first time creates a second one. Until idempotency keys exist, check before retrying a create you are unsure about. --- ## Module endpoints Some installations carry optional modules that add their own endpoints under `/api/v1/modules/{module}/…`. `GET /api/v1/me` lists which are present, so a tool can adapt rather than guess. Everything documented above — authentication, abilities, error format, rate limits — applies to them unchanged; the core supplies all of it rather than each module restating it. ### For module authors Register from your package's service provider, listening by string class name so your package stays buildable without the host application present: ```php Event::listen('App\Modules\Api\Events\RegisteringApiModules', function ($event): void { $event->register( slug: 'branding', routes: __DIR__.'/api-routes.php', capability: 'branding.customize', ); }); ``` The core supplies the prefix, the route-name namespace, the authentication stack and the capability gate. Your routes declare paths, controllers, and a `token-can:` middleware naming permissions from the core vocabulary. A slug must be unique and lowercase; a clash throws at boot rather than silently shadowing. Module endpoints are deliberately absent from the document above — `OpenApiContractTest` skips `api/v1/modules/*` — so each package documents its own surface in its own repository. The `branding` module's endpoints are in `packages/cloud-modules/docs/api.md`. --- ## Versioning `/api/v1` is a frozen contract. Additive changes only: new endpoints, new optional parameters, new response fields. Removing or renaming a field, tightening validation, or changing a status code is breaking and would arrive as `/api/v2`. Anything scheduled for removal ships `Deprecation` and `Sunset` headers first. `docs/api-changelog.md` records every change. --- ## Not in v1 Recorded so they read as decisions rather than gaps: - **Client-user tokens.** Only staff accounts can hold one. - **Password login.** Tokens come from the web interface. - **Webhooks.** Poll instead; see above. - **Idempotency keys.** See "Retries" above. - **Share links, notifications, thumbnails, settings.** - **Creating and deleting roles.** `GET /roles` reads them and `role_id` assigns one; defining a role's permission set stays in the UI. --- ## Keeping this document true Anyone shipping a feature or a fix — API-related or not — should run through asking whether the change needs an API change at all. For anyone adding an endpoint: 1. Route in `routes/api.php` inside the auth group, with a `token-can:` naming the same permission its `routes/web.php` twin uses. 2. A `JsonResource` with an explicit field allowlist — never `$model->toArray()`. 3. Authorization through the domain's existing policy or scope. The token ability is an *additional* gate, never a replacement. 4. A feature test, including the negative case for a client-scoped staff token. 5. Rerun `php artisan scramble:export`, add a row above if it changes the ability table, and add a changelog entry. The token creation screen needs no update — it derives its list by scanning routes for `token-can:`. Note that **docblocks on controller methods under an `Api` namespace are published as the reference**. Write them for the reader; keep implementation notes in `//` comments inside the method.