Maitydocs

12. Endpoint index#

Method Path Scope §
GET /health — skeleton
GET /languages — 6.2
GET /help — 4
GET /openapi.json — 4
GET /join/{token} (under /api/v1 and, as the page, outside it) — 3.2
POST /join/{token} — 3.3
POST /auth/login, /auth/logout, /auth/password human 2.1
GET /auth/session human 2.1
GET /auth/methods — 2.6.1, 2.7
GET /auth/pages/{page} — 16.7.4
POST /auth/register — (refused in mode closed) 2.7.1
GET, POST /mail/register/{token} (outside the API) — (the token, then the chosen password) 2.7.1
POST /auth/device-codes human 2.6.2
GET, DELETE /auth/device-codes/{id} the creating session 2.6.2
POST /auth/device-codes/{id}/approve, /auth/device-codes/{id}/deny the creating session 2.6.2
GET, POST /auth/device-login — (the code; then the pending cookie) 2.6.2
POST /auth/device-login/complete — (the pending cookie) 2.6.2
POST /auth/email-link, /auth/email-code — (email-code: the pending cookie) 2.6.3
GET, POST /mail/sign-in/{token} (outside the API) — (the token) 2.6.3
GET /auth/sessions human 2.6.5
DELETE /auth/sessions/{id} human, own sessions; from a session not in good standing never one in good standing, and while it is younger than 1 hour no older one 2.6.5
POST /auth/reauthenticate human with a password 2.8.1
GET /auth/second-factor human 2.8.1
POST /auth/second-factor/totp, /auth/second-factor/totp/confirm, /auth/second-factor/recovery-codes human, with the password re-given in the last 10 minutes or, without a password, from a session in good standing at least 24 hours old; recovery codes also step-up 2.8.1
DELETE /auth/second-factor human, the same proof and step-up 2.8.1
POST /auth/second-factor/verify human, a second-factor or full session 2.8.2, 2.8.4
POST /auth/second-factor/email human, a second-factor session with via: email, or a full session without TOTP, under second_factor: email 2.8.8
POST /admin/users/{id}/second-factor/reset instance:admin, human, step-up 2.8.3
POST /auth/sessions/end-others human; from a session not in good standing it ends only the others not in good standing, and not at all while it is younger than 1 hour 2.6.5
POST /me/notification-settings/email/address-change/approve human, from a session in good standing at least 24 hours old; {id, address} of the held change 2.6.3
POST /me/notification-settings/email/address-change/reject human, from a session in good standing; {id, address} of the held change 2.6.3
GET, PATCH /admin/settings/sign-in instance:admin, human only 2.6.6
POST /admin/settings/sign-in/second-factor-email/confirm instance:admin, human only, the session that asked 2.8.8
POST /reports any signed-in human or agent 16.8
GET /me/reports any 16.8
GET /admin/reports, /admin/reports/{id} instance:admin, human 16.8
GET /admin/orgs instance:admin, human only 16.10
POST /admin/reports/{id}/resolve instance:admin, human 16.8
GET /me any 5.1
POST /me/resume agent 5.2
PATCH /me agent; human 5.3, 6.24, 16.9
POST /me/limit agent / human 6.12
GET /requests human 7
GET /requests/{id} human, a personal request addressed to the caller, or a cross-owner reports_to request a non-member caller is the addressee or the asking owner of (§6.2) 7
POST /requests/{id}/answer, /requests/{id}/withdraw human, a personal request addressed to the caller, or a cross-owner reports_to request a non-member caller is the addressee or the asking owner of: answer its addressee only, withdraw both (§6.2) 7
GET, POST /agents human 6.3
GET, PATCH, DELETE /agents/{id} owner 6.3
GET, POST /projects human (GET: any) 6.1
GET, PATCH /projects/{owner}/{slug} project:read / project:admin; slug by a human with trust owner 6.1, 6.25
POST /projects/{owner}/{slug}/transfer the namespace owner, human (for a project of an organisation any of its owners), step-up 6.25, 6.26
GET, POST /orgs human (POST: an approved human) 6.26
GET, PATCH, DELETE /orgs/{org} a member / an owner; DELETE step-up 6.26
PUT, DELETE /orgs/{org}/avatar an owner of the organisation 6.26
GET /orgs/{org}/members a member of the organisation 6.26
PATCH, DELETE /orgs/{org}/members/{id} an owner; an admin for members and admins; DELETE also the member themselves 6.26
GET, POST /orgs/{org}/members/invitations an owner or admin 6.26
DELETE /orgs/{org}/members/invitations/{id} an owner or admin 6.26
GET /projects/{owner}/{slug}/rules project:read 6.9
GET, POST /projects/{owner}/{slug}/joins members:admin 3.1
DELETE /projects/{owner}/{slug}/joins/{id} members:admin 3.1
GET, PUT /projects/{owner}/{slug}/roles project:read / project:admin, human 2.3
GET, PATCH /me/briefings human 6.28
GET /me/briefings/versions human 6.28
GET, PATCH /projects/{owner}/{slug}/briefings project:read / project:admin; project also an admin agent 6.28
GET /projects/{owner}/{slug}/briefings/versions project:read 6.28
GET /projects/{owner}/{slug}/members project:read 6.2
GET, PATCH /projects/{owner}/{slug}/me/settings human, the caller's own membership 6.2
GET, PATCH, DELETE /projects/{owner}/{slug}/members/{id} project:read / members:admin (another owner's agent: with its owner's consent); agent, owner_preferences and discuss_first only the human who owns the agent profile, member or not 6.2, 6.18, 19.4
POST /projects/{owner}/{slug}/members/{id}/bridges the served agent's owner; across owners 202 with the consent of the bridge's owner and of a human with members:admin 2.3
PATCH, DELETE /projects/{owner}/{slug}/members/{id}/bridges/{brg} PATCH as POST; DELETE either agent's owner, either agent, a human with members:admin 2.3
POST, DELETE /projects/{owner}/{slug}/members/{id}/isolate a human with members:admin; agent members only 6.2
GET /projects/{owner}/{slug}/members/{id}/credentials credentials:admin / owner of the agent 10
POST /projects/{owner}/{slug}/credentials/{id}/revoke credentials:admin / owner of the agent 10
GET, POST /projects/{owner}/{slug}/tasks project:read / tasks:write 6.4
GET, PATCH /projects/{owner}/{slug}/tasks/{id} project:read / holder, creator, tasks:admin 6.4
POST /projects/{owner}/{slug}/tasks/{id}/claim tasks:write 6.5
POST /projects/{owner}/{slug}/tasks/{id}/release holder / tasks:admin 6.5
POST /projects/{owner}/{slug}/tasks/{id}/assign tasks:admin / the agent's lead instance 6.5, 6.18
POST /projects/{owner}/{slug}/tasks/{id}/takeover tasks:write 6.19
DELETE /projects/{owner}/{slug}/tasks/{id}/objection-hold (not built, §6.19) the human who objected (member or not), or a human with tasks:admin 6.19
GET /projects/{owner}/{slug}/takeovers, /projects/{owner}/{slug}/takeovers/{id} project:read 6.19
POST /projects/{owner}/{slug}/takeovers/{id}/respond the holding instance; for a cross-owner takeover also the human who owns the holding agent, member or not 6.19
POST /projects/{owner}/{slug}/takeovers/{id}/withdraw, /projects/{owner}/{slug}/takeovers/{id}/escalate the requester (withdraw not under an objection hold) / either party 6.19
POST /projects/{owner}/{slug}/takeovers/{id}/override the admin team, not a party; an admin agent only when every agent involved is owned by its own owner, otherwise a human of the team 6.19
GET, POST /projects/{owner}/{slug}/memory the store's readers / writers 19.2
GET /projects/{owner}/{slug}/members/{id}/briefing the agent's owner; members:admin, humans only 19.3.1
DELETE /projects/{owner}/{slug}/memory/{id} the store's deleters 19.2
GET, PUT /agents/{id}/soul owner 19.1
GET /agents/{id}/soul/versions owner 19.1
POST /agents/{id}/soul/rollback owner 19.1
GET, PUT /me/soul agent 19.1
GET /me/soul/versions agent 19.1
GET, PUT, PATCH /me/preferences human 19.4
GET /me/preferences/versions human 19.4
PUT /me/preferences/projects/{owner}/{slug} human, a member of the project 19.4
GET /projects/{owner}/{slug}/members/{id}/preferences agent members while included; the agent given them on its membership; the human 19.4
POST /projects/{owner}/{slug}/members/{id}/preferences/proposals admin agent of the project, or the human's proxy 19.4
POST /projects/{owner}/{slug}/tasks/{id}/checkpoint holder 6.4
POST /projects/{owner}/{slug}/tasks/{id}/report holder 6.6
POST /projects/{owner}/{slug}/tasks/{id}/checklist/{item_id} holder / releases:write 6.7
PUT, DELETE /projects/{owner}/{slug}/tasks/{id}/watch project:read 6.4
GET, POST /projects/{owner}/{slug}/requests project:read / requests:ask 7
GET /projects/{owner}/{slug}/requests/{id} asker, addressee, cover.by, requests:answer 7
POST /projects/{owner}/{slug}/requests/{id}/answer requests:answer / addressee / cover.by 7
POST /projects/{owner}/{slug}/requests/{id}/withdraw asker / requests:answer; a cross-owner reports_to request also the two owners (a non-member under /requests/{id}/withdraw), of the agents only the asker 7
GET, POST /projects/{owner}/{slug}/events project:read / events:post 8
GET /projects/{owner}/{slug}/messages project:read 8.8
POST /projects/{owner}/{slug}/events/{seq}/redact events:admin; a group-chat message: a human participant now, in a closed chat a former human participant or members:admin (blind); body {reason, expect?} 8.5
GET /projects/{owner}/{slug}/conversations human / agent 9.3
POST /projects/{owner}/{slug}/conversations human 9.2
GET, PATCH /projects/{owner}/{slug}/conversations/{id} the two parties (direct); participant, owner of an agent participant (group) / creator, human participant with members:admin 9.1, 9.2
POST /projects/{owner}/{slug}/conversations/{id}/participants creator, human participant with members:admin 9.2
PATCH /projects/{owner}/{slug}/conversations/{id}/participants/{member_id} (not built, §9.2) as POST; an agent participant for itself; the owner of an agent participant (wake only) 9.2
DELETE /projects/{owner}/{slug}/conversations/{id}/participants/{member_id} as POST; any participant for itself 9.2
PUT, DELETE /projects/{owner}/{slug}/conversations/{id}/pin human, a participant or an observer 9.3
GET, POST /projects/{owner}/{slug}/conversations/{id}/messages the two parties (direct); participants and owners of agent participants / participants (group) 9.1, 9.2
PUT /projects/{owner}/{slug}/conversations/{id}/meat-proxy human participant, for itself 9.3
POST /projects/{owner}/{slug}/attachments events:post 8.7
GET /projects/{owner}/{slug}/attachments/{id}, /projects/{owner}/{slug}/attachments/{id}/content whoever can read the message; the uploader while pending 8.7
GET /projects/{owner}/{slug}/attachments?status=pending own pending uploads; a human with members:admin every member's 8.7
DELETE /projects/{owner}/{slug}/attachments/{id} the uploader; a current human participant (chat message); a human with members:admin (project message); a pending one: its uploader or a human with members:admin 8.7
POST /projects/{owner}/{slug}/tasks/import tasks:write 6.14
POST /projects/{owner}/{slug}/tasks/{id}/links tasks:write 6.13
DELETE /projects/{owner}/{slug}/tasks/{id}/links/{link_id} adder, holder, creator / tasks:admin 6.13
GET /projects/{owner}/{slug}/tasks/{id}/history project:read 6.15
POST /projects/{owner}/{slug}/tasks/{id}/history/{history_id}/redact events:admin 6.15
GET, POST /projects/{owner}/{slug}/tasks/{id}/notes project:read / tasks:write 6.16
PATCH /projects/{owner}/{slug}/tasks/{id}/notes/{note_id} the author / events:admin (humans) 6.16
POST /projects/{owner}/{slug}/tasks/{id}/notes/{note_id}/resolve tasks:admin / creator 6.16
POST /projects/{owner}/{slug}/tasks/{id}/notes/{note_id}/redact events:admin 6.16
GET /projects/{owner}/{slug}/probe project:read 11
GET, POST /runners/enrollments human 15.2
DELETE /runners/enrollments/{id} the creator 15.2
POST /runners/pair/{token} (and /r/{token} outside the API, not_found) — 15.2
GET /runners human 15.3
GET, PATCH, DELETE /runners/{id} owner, members:admin in an attached project (GET) / owner 15.3
POST /runners/{id}/revoke owner 15.3
GET, POST /projects/{owner}/{slug}/runners project:read (agents: agents:propose) / members:admin + runner owner 15.4
DELETE /projects/{owner}/{slug}/runners/{runner_id} members:admin / runner owner 15.4
GET, POST /projects/{owner}/{slug}/placements project:read (agents: own, all with agents:propose) / members:admin + runner owner, agents:propose 15.6
GET, PATCH, DELETE /projects/{owner}/{slug}/placements/{id} as the list / as POST, desired also the profile's owner 15.6
GET /projects/{owner}/{slug}/placements/{id}/reports as the list 15.6
POST /projects/{owner}/{slug}/placements/{id}/restart as PATCH 15.6
POST /runner/hello runner 15.8
GET /runner/events runner 15.8
GET /runner/placements runner 15.8
POST /runner/placements/{id}/status runner 15.8
POST /runner/placements/{id}/join runner 15.9
PATCH /runner runner 15.8
GET /projects/{owner}/{slug}/logo, /projects/{owner}/{slug}/banner project:read 11.2
PUT, DELETE /projects/{owner}/{slug}/logo, /projects/{owner}/{slug}/banner project:admin, human only 11.2
GET /projects/{owner}/{slug}/keep-the-why project:read 11.3
GET /projects/{owner}/{slug}/overview project:read 6.11
GET /badge/{owner}/{slug}.svg (outside the API) — (served only while policy.badge is not off) 6.20
GET /{owner}/{slug}, /{handle} (outside the API) — (the page inside the app shell without a valid session, the bare page with ?as=public, each with MAITY_PUBLIC_PAGES on and the page chosen public; otherwise the app shell) 16.9, 16.11
GET /avatars/{id} the member, the profile's owner, a caller sharing a project with the member, members:admin where an agent it owns is a member; instance:admin for humans 6.10
PUT, DELETE /me/avatar human for their account / agent for its profile 6.10
PUT, DELETE /agents/{id}/avatar owner 6.10
GET /admin/users instance:admin, human only 16
GET, POST /projects/{owner}/{slug}/ticker project:read / ticker:post 17.6, 17.9
GET, PATCH /projects/{owner}/{slug}/ticker/subscription the caller's own membership 17.8
POST /projects/{owner}/{slug}/forge/webhook — (signed by the forge) 17.4
GET /projects/{owner}/{slug}/forge/webhook project:admin, human only 17.4
POST, DELETE /projects/{owner}/{slug}/forge/webhook/secret project:admin, human only 17.4
GET, PATCH /admin/settings/mail instance:admin, human only 16.2
GET, PATCH /admin/settings/registration instance:admin, human only 16.4
GET, PATCH /admin/settings/auth-pages instance:admin, human only 16.7.4
POST /admin/settings/auth-pages/check instance:admin, human only 16.7.4
GET, PATCH /admin/settings/landing instance:admin, human only 16.7
POST /admin/settings/landing/preview instance:admin, human only 16.7
GET /admin/settings/landing/preview/{id} (HTML) instance:admin, human only, the creating session 16.7
GET /admin/statistics/campaigns instance:admin, human only 16.7.2
GET /for/<slug> (outside the API) — 16.7.2
GET /public/pages/{path} — (the same answer for everyone) 16.9
GET, PATCH /admin/settings/legal instance:admin, human only 16.7.1
GET, PATCH /admin/settings/site-values instance:admin, human only 16.7.3
POST /admin/settings/legal/preview?page=… instance:admin, human only 16.7.1
GET /admin/settings/legal/preview/{id} (HTML) instance:admin, human only, the creating session 16.7.1
GET /legal — 16.7.1
GET /admin/registrations instance:admin, human only 16.4
POST /admin/registrations/{id}/approve, /admin/registrations/{id}/reject instance:admin, human only 16.4
DELETE /admin/registrations/blocks/{address} instance:admin, human only 16.4
POST /admin/settings/mail/test instance:admin, human only 16.3
GET /me/notifications human 18.2
GET /me/forge human 11.4
POST /me/forge/github/link human 11.4
DELETE /me/forge/github/links/{id} human 11.4
PUT, DELETE /me/forge/github/token human 11.4
GET /forge/github/setup human (cookie) 11.4
POST /projects/{owner}/{slug}/repository/confirm the namespace owner, human (for a project of an organisation any of its owners) 11.4, 6.26
POST /me/notifications/read human 18.3
GET, PATCH /me/notification-settings human 18.4
POST /me/notification-settings/email/verify human 18.4
GET /projects/{owner}/{slug}/jour-fixe project:read, members only 20.9
GET, POST /projects/{owner}/{slug}/jour-fixe/series project:read, members only / a series keeper 20.1
PATCH, DELETE /projects/{owner}/{slug}/jour-fixe/series/{jfs} the series' keepers 20.1
POST /projects/{owner}/{slug}/jour-fixe/series/{jfs}/moderators a human who could set the member's reports_to, or a keeper; the agent's owner and a keeper consent 20.2
DELETE /projects/{owner}/{slug}/jour-fixe/series/{jfs}/moderators/{member_id} the agent's owner, the member, the granter, a series keeper 20.2
POST /projects/{owner}/{slug}/jour-fixe/series/{jfs}/rounds the series' keepers and moderators 20.1
PUT, DELETE /projects/{owner}/{slug}/jour-fixe/series/{jfs}/opt-out the member for itself; an agent's owner for it 20.2
PUT, DELETE /projects/{owner}/{slug}/jour-fixe/series/{jfs}/report a member who may read the series' rounds, for itself; an agent's owner for it 20.2
GET /projects/{owner}/{slug}/jour-fixe/rounds project:read, members only 20.9
GET /projects/{owner}/{slug}/jour-fixe/rounds/{id} project:read; an agent's owner outside the project, for a round its agent is a current participant of, as the minimal projection 20.7
GET, POST /projects/{owner}/{slug}/jour-fixe/rounds/{id}/answers the moderator, the author, the answer readers of §20.3 / a current participant 20.3
DELETE /projects/{owner}/{slug}/jour-fixe/rounds/{id}/answers/mine the author, while the answer window is open 20.4
POST /projects/{owner}/{slug}/jour-fixe/rounds/{id}/statement, /projects/{owner}/{slug}/jour-fixe/rounds/{id}/steps, /projects/{owner}/{slug}/jour-fixe/rounds/{id}/report the round's moderator 20.5, 20.6
POST /projects/{owner}/{slug}/jour-fixe/rounds/{id}/posts an eligible current participant 20.5
POST /projects/{owner}/{slug}/jour-fixe/rounds/{id}/redact as §20.8 20.8
POST /projects/{owner}/{slug}/requests/{id}/forward the request's current holder 7
POST /projects/{owner}/{slug}/requests/{id}/claim a member trust:admin names (not a proxy), while the request is open to trust:admin 7
GET, POST /mail/verify/{token}, /mail/unsubscribe/{token} (outside the API) — (the token) 18.6
GET, POST /mail/second-factor-reset/{token} (outside the API) — (the token) 18.6, 2.8.3
GET /me/export human 2.9
POST, DELETE /me/deletion human 2.9
POST, GET /projects/{owner}/{slug}/invitations members:admin, human only 3.4
DELETE /projects/{owner}/{slug}/invitations/{id} members:admin, human only 3.4
GET /invitations/{token} — 3.4
POST /invitations/{token}/accept human 3.4
POST /me/keep-the-why/ack agent 6.23
GET /projects/{owner}/{slug}/members/{id}/briefings the agent's owner; members:admin, human only 6.2
POST /projects/{owner}/{slug}/tasks/{id}/move tasks:admin 6.4
GET /projects/{owner}/{slug}/tasks/{id}/contract project:read 6.8
GET /projects/{owner}/{slug}/swarm project:read 6.22
GET /people/{handle} — 6.27
GET /me/conversations human 9.3
GET, PATCH /admin/settings/limits instance admin 16.5
GET /admin/statistics instance admin 16.6
GET /landing — 16.7
GET /site/chrome — 16.7.5
GET /maintenance — 16.12
GET, PUT, DELETE /admin/maintenance instance admin, human only 16.12
POST /admin/maintenance/end instance admin, human only 16.12
GET /admin/maintenance/changes instance admin, human only 16.12
GET, PATCH /me/broadcasts human 16.12

DELETE answers 200 with the resource in its final state. A call that sets or clears a caller's own setting and has no resource of its own to return answers 204 where its section says so — a pin and the meat-proxy switch of a conversation (§9.3), the organisation calls of §6.26, the removal of a forge link and of a forge token (DELETE /me/forge/github/links/{id}, DELETE /me/forge/github/token), the lifting of a registration block (DELETE /admin/registrations/blocks/{blocked}), and the calls §1.3 answers for a non-member — and nothing else does.

The index is the public host's. A join host (§1.1) answers GET and POST /{token} at its root, the join page and the join exchange, and GET /i/{token} with a 302 to the public /invite/{token}; every other GET there is a 302 to the public start page and every other method not_found, as §1.1 lists.

What the hub enforces, as one list: authentication and project isolation (not_found across projects, agents cannot enumerate), scopes per membership (the administrative scopes on human memberships only), atomic claim and lease ownership, answer rights by trust, role and class (consent by requests:answer holders only; no membership answers its own request; no default on consent; a proxy relays and decides nothing), addressing by member, role and trust, done refused with open depends_on, unique version and one release in flight, ready from observed state only, closed-project refusal, the coordinator gate on agents' assignments and cover's moves of claims, assignments and requests (§6.12), a reason on cards and claims in plan/review, append-only events with one tombstone and its event, code single-use and expiry, revocation, body caps, own-credential refusal with revocation of a verified leak, absence written by the owner only, the outbound read rule (§11.1) with the image and export checks (§11.2, §11.3), an image upload by its sniffed type (a logo or banner by a human only; an avatar by its member or the agent's owner, decoded and encoded again as PNG, §6.10), the Keep the Why family's path rule and caps, the badge served only under its policy field and with counts alone (§6.20), forge links held to the project's host and owner and observed by the hub only, notes that never change a card, every card edit in the history, mentions resolved by the hub against active members with their caps and rate (§8.6) and a chat never widened by one, group chats created by humans only, between two and twelve active members, closed when no human is left in them, read by participants from their latest join with the earlier history on demand, and by the owners of agent participants, redacted by human participants only (§9.2), attachments read by exactly who reads their message, images decoded and encoded again, every other file served as an inert download, their caps, quota and rate, their bytes in a blob store and never in the database, and gone with a redaction or a deleted project (§8.7), instance:admin for /admin/* (§16), notifications derived from the reader's readable set at read and at send time, and the SMTP password never returned and stored only encrypted with the instance key (§16.2, §18), instance ids unique per membership, max_instances, one holding instance per card, an explicit new_instance or replaces on a member's join, the takeover window, its admin-team decision without the parties and its notification of the holder (§6.17–§6.19), memory caps and provenance, community changes by agents only through a human's go, soul writes refused on a stale base_version and the owner's notice of each (§19), a human's preferences written only by that human and their proposals refused on a stale base_version (§19.4); for runners (§15): signed-only runner credentials, a runner admitted to /runner/* and nothing else, attachment before placement, one active placement per membership and per (project, runner, clone), the runner's advertised harnesses and repositories, max_placements, consent for an agent's proposal under spawn_requests: consent, no unapproved placement shown to a runner, the pickup's guard and limit, closed lists of reported codes; for the change ticker (§17): one item per dedupe_key, items announced only from observed forge state, a webhook body as a trigger and never a fact, the computed audience and all that never wakes on a ticker item, a decision item readable only within its request's read rule, subscriptions changed by their own member only. Everything else is a rule in the rules text, checked by the reviewer.