A plain-language guide for site users lives at /api-guide (resources/views/pages/api-guide-tw.blade.php). Keep it in step with this file and routes/api.php.
- Visit the API docs endpoint https://your-domain.com/api/docs for a full list of available endpoints.
- Generated using Swagger js referencing
public/postmanfolder.
- Currently requires a basic auth username and password to access the API.
- You can also request a user token to access the API.
- You can query the API using basic auth or a user token.
- To authenticate using basic auth, include the
Authorizationheader with the valueBasic base64(username:password). - To authenticate using a user token, include the
Authorizationheader with the valueBearer your_user_token. - To acquire a user token, call
POST /api/tokens/createwith basic auth credentials. When requesting a token, include in the body atoken_namekey with the desired name for the token.
All /api/* routes go through the api rate limiter (RouteServiceProvider::configureRateLimiting):
| Caller | Limit | Keyed by |
|---|---|---|
| Authenticated (basic auth or bearer token) | 240 requests / minute | user id |
Anonymous (e.g. /api/search, /api/calendar-events) |
120 requests / minute | IP address |
POST /api/{events,entities,series}/{id}/photos/from-url |
20 requests / minute, on top of the general limit | user id |
| Failed basic auth attempts | 20 failures / minute | IP address |
- Responses carry
X-RateLimit-LimitandX-RateLimit-Remaining. Over the limit you get429with aRetry-Afterheader (seconds). - After 20 failed basic auth attempts from one IP, basic auth from that IP is refused with
429for the rest of the minute, even with the correct password. Successful logins don't count. This applies toauth.eitherroutes andPOST /api/tokens/create. AuthenticateEitherimplementsAuthenticatesRequestsso Laravel's middleware priority runs it beforeThrottleRequests. That's what lets the limiter see the user. Don't remove the interface, or every basic auth caller falls back to the per-IP limit.- Counters live in the default cache store (
CACHE_DRIVER), so they're per server unless the cache is shared.
- After registration, users will receive a verification email with a signed URL.
- The email verification endpoint is:
GET /api/email/verify/{id}/{hash} - This endpoint requires a valid signed URL (generated by the system) with the user ID and email hash.
- The endpoint will return a JSON response with a success or error message.
- No authentication is required for this endpoint, but it requires a valid signature and hash.
- Creating or updating content needs a verified email, as on the web (#2314). An unverified account gets
403with{"message": "Your email address is not verified."}from the create, update and photo routes of events, entities (and their contacts, links, locations and photos), series, tags, threads, posts, blogs, links and locations. Nothing is written. - Reads, follow/unfollow, attend and
POST /api/tokens/createstill work for an unverified account, so a client can sign in and show a "verify your email" state. - The 403 is JSON even without an
Accept: application/jsonheader (App\Http\Middleware\EnsureEmailIsVerified); web routes still redirect to the verification page. WriteRouteAuthorizationTest::UNVERIFIED_ALLOWEDlists the API write routes that don't need a verified email. A new API write route must refuse an unverified user unless it's added there.
You can apply filters to routes using the following:
- To filter by a specific field, use the field name as the key and the value as the value.
- Example:
GET /api/events?filters[name]=Event Name
- Example:
- To order by a specific field, use the field name as the key and the value as the value.
- Example:
GET /api/events?sort=model.property&direction=asc
- Example:
- To filter events by multiple tags you can provide a comma separated list or repeat the
filters[tag]parameter.GET /api/events?filters[tag]=music,art- When you need events that contain all of the supplied tags, use
filters[tag_all]instead. GET /api/events?filters[tag_all]=music,art
tag_list on the event, entity, series, post, blog and thread create/update endpoints accepts a mix of existing tag ids and free-text names.
- Ids are matched by primary key.
- Names are slugged and matched to an existing tag by slug, so
"diy","DIY"and"Diy"all resolve to the existingDiytag. - A tag is created only when no id or slug matches. Sending an existing tag's name never creates a duplicate.
PUT /api/events/{event}withtag_listis a full sync (a missing key detaches all tags);PATCHonly syncs whentag_listis present.
A short-run event (a play, a festival weekend) keeps its first date in start_at and its other dates in showings. An event with one date has an empty showings.
POST /api/events
{ "name": "...", "start_at": "2027-03-01 20:00:00",
"showings": [
{ "start_at": "2027-03-04 19:00:00" },
{ "start_at": "2027-03-06 14:00:00", "end_at": "2027-03-06 16:00:00", "door_at": "2027-03-06 13:30:00" }
] }
- Each showing must start after
start_at, no two may share a start, and there can be at most 60. PUTreplaces the showings with what it sends (none removes them all);PATCHonly touches them whenshowingsis present.- Responses carry
showings,last_start_at(the final date's start) andnext_start_at(the first date still to come, elsestart_at). filters[start_at]and/api/events/by-date/...match an event on any of its dates, and sorting byevents.start_atwith a start filter orders by each event's next date in range.
POST /api/events/{id}/photos (and the entity / series equivalents) take a multipart file upload. Each has a sibling that accepts a public https URL instead, for callers that cannot hold the bytes themselves (browser automation blocked by CORS, sandboxed agents, importers):
POST /api/events/{id}/photos/from-url
POST /api/entities/{id}/photos/from-url
POST /api/series/{id}/photos/from-url
{ "url": "https://example.com/flyer.jpg" }
Behaviour matches the upload endpoint: same ownership rule (owner or admin), first photo becomes primary, followers are notified on an event's first photo, 201 with the photo's API representation. The differences are the guards on the fetch itself, all of which return 422 with a message:
httpsonly, on every hop; at most 3 redirects.- The host must resolve to a public address. Loopback, link-local (including cloud metadata), RFC1918 / ULA and other reserved ranges are refused, and every redirect target is re-checked.
- 5 MB cap (the same as the web uploader), enforced while downloading rather than from
Content-Length. - The downloaded bytes are sniffed and must be a jpg, jpeg, png, gif or webp image, regardless of the URL extension or
Content-Typeheader. - 10 s connect / 20 s total timeout.
The stored file name is derived from the last path segment of the final URL, sanitized and given the sniffed extension. The route is rate limited to 20 requests per minute per user, separately from the rest of the API.
curl -u user:pass -H 'Accept: application/json' \
-d 'url=https://example.com/flyer.jpg' \
https://arcane.city/api/events/123/photos/from-url