App API
Surplus has no general-purpose public API. The web app talks to its own server through its app API: JSON requests on the app's own origin, under /api, one path and method per call (for example GET /api/donors/{id} to read a donor and PATCH /api/donors/{id} to update one). It is built for the web app and changes with it, so it is not a supported integration surface. For programmatic access, use the read-only MCP integration, or coordinate with Sharing Excess on what you need.
The only plain HTTP endpoints are a few public, read-only ones under /public that Sharing Excess's own website uses for Find Food and the impact numbers. They return only what the public map shows, and browsers may read them cross-origin only from Sharing Excess's own sites.
How a call works
- One origin. The app, its API, authentication (
/auth), MCP (/mcp), and stored files (/files) all answer on the app's own URL,https://surplus.sharingexcess.comin production. Staging and personal dev environments use their ownsurplus.*.sharingexcess.comhosts. - Every call has one contract. Each call is defined once, with oRPC, as a typed contract: its method, its path under
/api, and the schemas of its input and output. The server implements that contract and the web app's client is built from it, so the two can't drift. - Every call is authorized before it runs. The server checks the session, then the caller's access to every record the call names, before it validates the input or runs any business logic. A call it can't decide is refused.
- Input and output are validated against the contract's schemas at the boundary, so a malformed request or a response that drifts from its schema never gets through.
- Cross-site calls are refused. The app API answers only the app's own pages; requests from other sites are rejected, and no CORS headers are sent. The public
/publicendpoints are the exception, for Sharing Excess's own sites only.
Authentication
The web app signs in with a passwordless emailed code, through its authentication endpoints under /auth, which are the only part of the system that issues sessions:
- Request a one-time code for an email address.
- Validate the code to receive a session token as an HttpOnly cookie for the app's own host.
- Every API call carries the cookie automatically. The server verifies the token's signature; only
/authissues one.
Permissions are not embedded in the token — the server loads the user's current role on every request, so access changes take effect immediately. MCP uses a separate OAuth path — see MCP integration.
Full auth and role details: Access control.
Validation and errors
- Malformed input returns 400 with the schema's own message, before any business logic runs.
- Missing or invalid sessions receive 401; suspended accounts and calls the user may not make receive 403; a record that doesn't exist returns 404; a duplicate returns 409.
- Errors return JSON with a code, the status, a safe message, and a
requestId(in itsdata) for correlation — never internal stack traces. The app shows the first characters of it (ref: 290d0300) so a report can be traced.
Rate limits
| Scope | Limit |
|---|---|
| Global (per IP) | 100 requests / 10 seconds |
| Signed-in admins and advisors (per user, instead of per IP) | 300 requests / 10 seconds |
| Sign-in code request | 5 / 15 minutes per email + IP |
| Sign-in code validate | 10 / 15 minutes per email |
Exceeding a limit returns 429 with a Retry-After header.
Files and attachments
Uploaded files are never public bucket URLs. Every response that names a file also gives its URL in the field beside the path (logoFilePath → logoFileUrl, filePath → fileUrl), served by the app at /files after it checks the session, and for attachments a signature for the signed-in user. Use the URL as it is; attachment URLs expire within 20 minutes. See Access control — file access.
Next steps
- Domain model — understand the entities in responses
- MCP integration — read-only programmatic access for admin and advisor accounts
- Security overview — full control documentation
