Organizations API
Create and manage organizations, members, teams, invitations, blocks, domains, usage, plans and the audit log over REST.
Everything the organization settings pages do is one of these routes. For tokens, scopes, errors and paging, see Authentication, Token scopes, Errors and Paging. For the product side, see Organizations.
In every path, {org} is the organization handle. An old handle of a renamed organization still resolves.
Access rules
- Reads need the
org:readscope. Changes needorg:admin. Leaving an organization and answering your own invitations need theuserscope. - Most changes are for owners. A member who calls an owner-only route gets 403
only owners of this organization can do that. Someone who is not a member gets 404, so an organization's private parts are not revealed. - When an organization turns on two-factor, a member without a passkey or authenticator app gets 403 on every organization route except leaving it.
- A few routes are session only: a token gets 403
this action needs a browser session, not a token. They are marked below. - Errors from invalid input are 422 with the field named in the message.
Organizations
Create an organization
POST /api/orgs Needs org:admin. You become its first owner.
| Field | Type | Notes |
|---|---|---|
handle | string | Required. 1 to 39 letters, digits and hyphens, not starting or ending with a hyphen. Lowercased. Shares its namespace with people. |
name | string | Required. 1 to 100 characters. |
tagline | string | Optional. At most 200 characters. |
location | string | Optional. At most 100 characters. |
website | string | Optional. At most 200 characters. |
timeZone | string | Optional. An IANA name such as America/Los_Angeles. Default UTC. |
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
-d '{"handle":"acme","name":"Acme","timeZone":"America/Los_Angeles"}' \
https://sailfork.com/api/orgs The response is 201 with the organization view described in the next section. A taken handle is 409 handle is already taken.
Get an organization
GET /api/orgs/{org} The organization's public page as JSON. Signed-out callers can read it. A signed-in token needs org:read. Repositories, pinned repositories and the feed list only what the caller can read. The member list shows members who chose to be public, and every member when the caller is a member.
| Field | Meaning |
|---|---|
handle, name, tagline, location, website, timeZone | Profile fields. |
avatarUrl | The logo, or null. |
verified | true when a domain is verified. |
week | Two counters for the last 7 days: merged pull requests and pull requests opened by agents. |
pinned | Names of pinned repositories, in pin order. |
repos | Repository cards: name, about, visibility, language, crewShare, openPulls, openIssues, pushedAt. |
members | name, handle, role (Owner or Member), timeZone, city, hours, public. |
feed | The 30 newest events across its repositories: at, actor, agent, text, repo. |
files | The README and llms.txt text from the organization's profile repository. |
curl -H "Authorization: Bearer $SAILFORK_TOKEN" https://sailfork.com/api/orgs/acme {
"handle": "acme",
"name": "Acme",
"avatarUrl": null,
"tagline": "Tools for tide tables",
"verified": true,
"timeZone": "America/Los_Angeles",
"week": [
{ "label": "Merged this week", "value": "12" },
{ "label": "Opened by the crew", "value": "5" }
],
"pinned": ["ocean-landing"],
"repos": [
{ "name": "ocean-landing", "about": "Marketing site", "visibility": "public", "language": "TypeScript", "crewShare": 0.4, "openPulls": 3, "openIssues": 8, "pushedAt": "2026-11-09T18:02:11Z" }
],
"members": [
{ "name": "Fenil Sonani", "handle": "fenil", "role": "Owner", "timeZone": "America/Los_Angeles", "city": "San Francisco", "hours": [9, 17], "public": true }
],
"feed": []
} List your organizations
GET /api/me/orgs Needs org:read. Returns the organizations you belong to, ordered by name, with any scheduled for deletion last.
| Field | Meaning |
|---|---|
handle, name, avatarUrl | The organization. |
role | Your role: Owner or Member. |
joined | The date you joined, YYYY-MM-DD. |
onlyOwner | true when you are its only owner, so you cannot leave. |
repos | How many repositories it owns. |
deletionAt | When it will be deleted, or null. |
[
{ "handle": "acme", "name": "Acme", "avatarUrl": null, "role": "Owner", "joined": "2026-03-02", "onlyOwner": true, "repos": 4, "deletionAt": null }
] Get settings
GET /api/orgs/{org}/settings Needs org:read, and you must be a member. Returns the settings object that PATCH also returns.
curl -H "Authorization: Bearer $SAILFORK_TOKEN" https://sailfork.com/api/orgs/acme/settings {
"handle": "acme",
"name": "Acme",
"tagline": "Tools for tide tables",
"location": "San Francisco",
"website": "https://acme.example",
"timeZone": "America/Los_Angeles",
"baseAccess": "read",
"defaultRepoVisibility": "private",
"requireSecondFactor": false,
"deviceCopies": true,
"created": "2026-03-02",
"role": "Owner",
"deletionAt": null
} Update settings
PATCH /api/orgs/{org} Needs org:admin and an owner. Send only the fields you want to change. An unknown field is 422.
| Field | Type | Notes |
|---|---|---|
name | string | 1 to 100 characters. |
tagline | string | At most 200 characters. |
location | string | At most 100 characters. |
website | string | At most 200 characters. |
timeZone | string | An IANA time zone name. |
baseAccess | string | none, read or write. What every member gets on the organization's private repositories. |
defaultRepoVisibility | string | public or private. What the new-repository form starts on. |
requireSecondFactor | boolean | See Security settings. |
deviceCopies | boolean | See Security settings. |
curl -X PATCH -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
-d '{"baseAccess":"write","tagline":"Tools for tide tables"}' \
https://sailfork.com/api/orgs/acme The response is the settings object. Each change is written to the audit log.
Rename an organization
POST /api/orgs/{org}/handle Needs org:admin and an owner. Body: { "handle": "acme-labs" }. The old handle stays reserved and keeps leading to the organization, and clone URLs keep working. The response is the settings object. A bad handle is 422. A taken one is 409.
Delete an organization
Two routes, for two situations.
DELETE /api/orgs/{org} Deletes the organization now. Session only, owners only. It is 409 while the organization still owns repositories (Acme still owns 2 repositories: delete or transfer them first), or while it is held for review. Returns 204.
POST /api/orgs/{org}/deletion Schedules deletion in 14 days. Session only, owners only. The organization and everything in it, including repositories, members, teams and the audit log, is removed when the time comes. Calling it again keeps the first date. Returns { "deletionAt": "2026-11-24T19:30:00Z" }.
DELETE /api/orgs/{org}/deletion Cancels a scheduled deletion. Needs org:admin and an owner. Returns 204. It is 409 its deletion has started and can no longer be cancelled once the purge began.
Logo
POST /api/orgs/{org}/avatar
DELETE /api/orgs/{org}/avatar Both need org:admin and an owner. POST takes the raw image as the body with Content-Type: image/png, image/jpeg or image/webp, at most 5 MB. It is stored as a square WebP and returns { "avatarUrl": "..." }. Another content type is 415. An image that cannot be read is 422. DELETE returns 204.
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: image/png" \
--data-binary @logo.png https://sailfork.com/api/orgs/acme/avatar Members and roles
An organization has two roles. Owners manage everything. Members get the access that baseAccess and their teams grant. There is no route that adds a member directly: people join by accepting an invitation.
Change a role
PATCH /api/orgs/{org}/members/{handle} Needs org:admin and an owner. Body: { "role": "Owner" } or { "role": "Member" }, in any letter case. Returns { "handle", "name", "role" }. A change that leaves the person's role as it was changes nothing. Making the last owner a member is 409 an organization needs at least one owner: make someone else an owner first. A person who is not a member is 404.
Remove a member
DELETE /api/orgs/{org}/members/{handle} Needs org:admin and an owner. Removes the person from the organization and from all its teams. Returns 204. Removing the last owner is 409.
Leave an organization
DELETE /api/orgs/{org}/members/me Needs the user scope. You leave the organization and its teams. Returns 204. The only owner cannot leave (409). A required second factor does not stop you from leaving.
Teams
A team groups members and gives them access to repositories. A team has a slug (its id in paths), a name, an optional parent team, maintainers and members as handle lists, and repos, a map from repository name to read, write or admin. Maintainers are members who can also manage the team's members.
{
"slug": "web",
"name": "Web",
"parent": "engineering",
"maintainers": ["fenil"],
"members": ["fenil", "ada"],
"repos": { "ocean-landing": "write" }
} List and read teams
GET /api/orgs/{org}/teams
GET /api/orgs/{org}/teams/{team} Need org:read and membership. The first returns an array of teams ordered by name. The second returns one team, or 404.
Create a team
POST /api/orgs/{org}/teams Needs org:admin and an owner. Body: { name, slug?, parent? }. name is 1 to 60 characters. slug defaults to the lowercased name with hyphens. parent is the slug of an existing team. Returns 201 with the team. A slug already in use is 409. An unknown parent is 422.
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
-d '{"name":"Web","parent":"engineering"}' https://sailfork.com/api/orgs/acme/teams Update a team
PATCH /api/orgs/{org}/teams/{team} Needs org:admin and an owner. Body: { name?, parent? }. Send "parent": null to make it a top-level team. Nesting a team under itself or one of its children is 422. Returns the team.
Delete a team
DELETE /api/orgs/{org}/teams/{team} Needs org:admin and an owner. Returns 204.
Add or remove a team member
PUT /api/orgs/{org}/teams/{team}/members/{handle}
DELETE /api/orgs/{org}/teams/{team}/members/{handle} Need org:admin, and you must be an owner or a maintainer of that team (403 otherwise). PUT takes an optional body { "maintainer": true } and updates the role when the person is already on the team. It returns the team. The person must already be an organization member, or it is 422. DELETE returns 204, or 404 when the person is not on the team.
Give or take team access to a repository
PUT /api/orgs/{org}/teams/{team}/repos/{repo}
DELETE /api/orgs/{org}/teams/{team}/repos/{repo} Need org:admin and an owner. {repo} is a repository name in this organization. PUT takes { "permission": "read" | "write" | "admin" } and returns the team. A repository the organization does not own is 422. DELETE returns 204, or 404 when the team had no access.
Invitations
An invitation lasts 7 days. Nobody joins an organization without accepting one.
Invite someone
POST /api/orgs/{org}/invites Needs org:admin and an owner. Send either email or handle, plus an optional role (Owner or Member, default Member).
{ "handle": "ada" }sends an in-app invitation to that account.{ "email": "ada@example.com" }mails a link. If the address has no account yet, the link lets the person create one first.
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
-d '{"email":"ada@example.com","role":"Member"}' https://sailfork.com/api/orgs/acme/invites {
"invite": { "id": "6d1c3e0a-5b0e-4c8f-9d52-0d6f7a1b2c3d", "email": "ada@example.com", "handle": null, "role": "Member", "invitedBy": "Fenil Sonani", "sent": "2026-11-10T19:30:00Z" },
"mailed": true,
"link": "https://sailfork.com/invite/<token>"
} link is shown once. mailed is true only when a mail provider accepted the email, and false when mail is off, only written to the server log, or refused, so pass the link on yourself. Status codes: 201 on success, 409 when the person already belongs to the organization or already has a pending invitation, 422 for sending both or neither of email and handle, an address that is not an email, or an unknown handle.
List an organization's pending invitations
GET /api/orgs/{org}/invites Needs org:read and an owner. Returns the pending, unexpired invitations as { id, email, handle, role, invitedBy, sent }, newest first.
Revoke an invitation
DELETE /api/orgs/{org}/invites/{id} Needs org:admin and an owner. Returns 204, or 404 when there is no such pending invitation.
List your invitations
GET /api/me/invites Needs org:read. Returns the pending, unexpired invitations addressed to you for organizations you are not in: { id, handle, name, role, invitedBy, sent, verifyFirst }. verifyFirst is the email address that got the invitation when you have not verified it yet, and null otherwise.
[
{ "id": "6d1c3e0a-5b0e-4c8f-9d52-0d6f7a1b2c3d", "handle": "acme", "name": "Acme", "role": "Member", "invitedBy": "Fenil Sonani", "sent": "2026-11-10T19:30:00Z", "verifyFirst": null }
] Accept or decline an invitation
POST /api/invites/{id}/accept
POST /api/invites/{id}/decline Need the user scope. Declining returns 204. Accepting returns 200 with { "org", "role", "joined" }: role is the role you now hold, and joined is false when you already belonged to the organization and nothing changed. Accepting makes you a member and clears your other invitations to that organization. Both are 404 for an id that is not yours, expired or already used. Accepting an invitation that went to an address you have not verified is 403 verify <address> first; the invitation went to that address.
Preview and accept an invite link
GET /api/invite-links/{token}
POST /api/invite-links/{token}/accept {token} is the last part of the link that an email invitation returned. GET needs no sign-in. It returns { org, name, role, invitedBy, email, handle }, or 404 once the link expired, was revoked or was used. POST needs the user scope, adds you to the organization and returns { "org": "acme" }. An invitation that was addressed to an account answers 403 to any other account.
Blocks
An organization can keep a person out of all its repositories. A blocked person can still read public code, but cannot open issues or pull requests, comment, or be invited. Blocking also ends their collaborations and invitations on the organization's repositories.
GET /api/orgs/{org}/blocks
PUT /api/orgs/{org}/blocks/{handle}
DELETE /api/orgs/{org}/blocks/{handle} GET needs org:read. PUT and DELETE need org:admin. All need an owner. GET returns { handle, name, avatarUrl, blockedBy, at } for each blocked person. PUT returns the new list. DELETE returns 204, or 404 when the person was not blocked. Status codes for PUT: 422 for yourself or an unknown handle, and 409 is a member of this organization; remove them before blocking them for a member.
For blocks on your personal repositories, see Account API.
Domains
An organization proves it owns a domain with a DNS TXT record. Any verified domain sets the organization's verified badge.
{ "name": "acme.example", "verified": false, "since": null, "token": "sailfork-verify=3f9a1c07be", "checked": null } since is the verification date (YYYY-MM-DD). checked is the instant of the last check.
List domains
GET /api/orgs/{org}/domains Needs org:read and membership. Returns an array of domains.
Add a domain
POST /api/orgs/{org}/domains Needs org:admin and an owner. Body: { "name": "acme.example" }. A leading https://, a trailing slash or a trailing dot is stripped. Returns 201 with the domain and its token. A domain already listed is 409. A value that is not a bare domain is 422.
Verify a domain
POST /api/orgs/{org}/domains/{name}/verify Needs org:admin and an owner. Create a TXT record at _sailfork.<name> whose value is the domain's token, then call this route. It looks the record up through public DNS-over-HTTPS and returns the domain with verified and checked updated. A domain that is not listed is 404. A failed DNS lookup is 503, so retry later. No record yet is not an error: the response has verified: false.
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" \
https://sailfork.com/api/orgs/acme/domains/acme.example/verify Remove a domain
DELETE /api/orgs/{org}/domains/{name} Needs org:admin and an owner. Returns 204, or 404 when the domain is not listed.
Security settings
Three settings protect an organization's access, all through PATCH /api/orgs/{org} (see Update settings).
requireSecondFactor: trueshuts out every member who has no passkey or authenticator app, on the web, the API, git and SSH, with a 403 that names the requirement. Those members can still leave. It applies to owners too, so you must have one yourself first: otherwise the request is 409add a passkey or an authenticator app to your own account before requiring one. The audit entry records how many members lost access.baseAccesssets what every member can do on the organization's private repositories.deviceCopies: falsekeeps the organization's private repositories off members' devices. The browser normally keeps folders and files a member opened, so they open again without asking the server, and deletes them at sign-out. With this off, the server refuses those copies and a browser deletes what it already kept the next time the member opens the repository. On by default.
Merge rules
GET /api/orgs/{org}/merge-rules
PUT /api/orgs/{org}/merge-rules The default merge requirements for the organization's pull requests. GET needs org:read and membership. PUT needs org:admin and an owner, and replaces every field.
| Field | Type | Meaning |
|---|---|---|
approvals | integer | Approvals needed before a merge, 0 to 6. Other values are 422. |
dismissStale | boolean | A push after an approval voids it. |
upToDate | boolean | The branch must contain the base branch's tip. |
threadsResolved | boolean | Every code comment thread must be resolved. |
selfReview | boolean | The author must approve their own pull request (a self-review, which never counts toward approvals). Optional, defaults to false. |
curl -X PUT -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
-d '{"approvals":1,"dismissStale":true,"upToDate":false,"threadsResolved":true,"selfReview":false}' \
https://sailfork.com/api/orgs/acme/merge-rules An unknown field is 422. Each requirement that changes is written to the audit log.
Rulesets
GET /api/orgs/{org}/rulesets
PUT /api/orgs/{org}/rulesets Branch rules applied to many repositories at once, on top of each repository's own. Both need an owner: GET with org:read, PUT with org:admin. PUT replaces every ruleset; the body and the answer are { "rulesets": [...] }.
| Field | Type | Meaning |
|---|---|---|
name | string | 1 to 80 characters, unique within the organization. |
enforcement | off, dryRun or active | dryRun logs what it would refuse and refuses nothing. |
repos | string[] | 1 to 20 globs over repository names, * for all. Repositories created later match too. |
rules | BranchRule[] | The same rules as a repository's branch rules, except readers, which only a repository sets. |
bypass | { teams, people } | Team slugs and member handles let through; each bypass is logged. |
auditPushes | boolean | Writes every push to a matching repository to the audit log. |
curl -X PUT -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
-d '{"rulesets":[{"name":"main is protected","enforcement":"active","repos":["api-*"],"rules":[{"pattern":"main","blockForcePush":true,"blockDeletion":true,"requirePullRequest":true}],"bypass":{"teams":["release"],"people":[]},"auditPushes":false}]}' \
https://sailfork.com/api/orgs/acme/rulesets 422 for more than 20 rulesets, a repeated name, a bad glob, a reader list, a team that does not exist or a person who is not a member, each naming the ruleset. The audit log records ruleset.update, ruleset.would_block, ruleset.block, ruleset.bypass and, with auditPushes, push.
Audit log
GET /api/orgs/{org}/audit?before=&limit= Needs org:read and an owner. Returns who changed what, newest first, as { events, next }.
| Parameter | Type | Notes |
|---|---|---|
limit | integer | Default 50. Values are held between 1 and 200. |
before | string | The next of the previous page. Any other value is 422. |
| Event field | Meaning |
|---|---|
id, at | The event id and when it happened. |
kind | One of org, member, invite, access, rule, repo, domain, moderation. |
action | A machine name such as member.role, invite.create, team.create or org.update. |
target | What it applied to: a handle, team slug or repository name. |
actor, agent | Who did it, and whether an agent did. |
text | A sentence you can show to a person. |
meta | Extra details for the action, as an object. |
curl -H "Authorization: Bearer $SAILFORK_TOKEN" "https://sailfork.com/api/orgs/acme/audit?limit=2" {
"events": [
{ "id": "0b6e5c1e-84d2-4e55-a1a8-3f4f4c2c9e10", "at": "2026-11-10T19:31:02Z", "kind": "invite", "actor": "Fenil Sonani", "agent": false, "text": "Invited ada@example.com as a member", "action": "invite.create", "target": "ada@example.com", "meta": { "role": "member" } }
],
"next": "1794347462000000_0b6e5c1e-84d2-4e55-a1a8-3f4f4c2c9e10"
} next is null on the last page. For your own account's log, see Account API.
Usage and plan
Get usage
GET /api/orgs/{org}/usage?month=YYYY-MM Needs org:read and an owner. month defaults to the current UTC month; a value that is not YYYY-MM is 422.
| Field | Meaning |
|---|---|
month | The month, YYYY-MM. |
changes, freeChanges, billableChanges | Files changed through caissons with a token, the free allowance, and the difference, never below 0. |
pricePer1000ChangesCents, estimatedCents | The price per thousand changes and the estimate, in integer cents. |
currency | USD. |
sandboxes | Sandboxes members started this month. |
sandboxVcpuMinutes | vCPUs times minutes they ran, rounded up. Not billed yet. |
curl -H "Authorization: Bearer $SAILFORK_TOKEN" "https://sailfork.com/api/orgs/acme/usage?month=2026-11" {
"month": "2026-11",
"changes": 4210,
"freeChanges": 10000,
"billableChanges": 0,
"pricePer1000ChangesCents": 200,
"estimatedCents": 0,
"currency": "USD",
"sandboxes": 38,
"sandboxVcpuMinutes": 2290
} Get billing
GET /api/orgs/{org}/billing Needs org:read and an owner. Returns the plan, billing cycle, storage and invoices.
| Field | Meaning |
|---|---|
plan | free or team. |
seats | Member count. |
cycleStart, cycleDays | The current billing cycle. |
storageGiB, storageBytes | Repository storage in use. |
billingEmails | The owners' addresses that receive receipts. |
invoices | Finished bills: id, number, period, status, paid, subtotalCents, taxCents, cents, currency, url (Stripe's hosted page). |
payments | live, subscribed, status, cycleEnd, cancelAtCycleEnd, pendingPlan, pendingPlanAt, billingName, billingCountry, consentVersion and offers (plan, cents, consentText). |
methods and history are always empty arrays. Money is integer cents.
Change the plan
PUT /api/orgs/{org}/billing/plan Session only, owners only. Body: { "plan": "free" } or { "plan": "team" }; any other value is 422. Returns { plan, pendingPlan, pendingPlanAt }. A downgrade stays pending until the paid cycle ends, and the response shows it in pendingPlan. A move to a paid plan that needs a payment is 409. Starting that payment goes through the billing page, not the API.
curl -X PUT -H "Cookie: sf_session=$SF_SESSION" -H "Content-Type: application/json" \
-d '{"plan":"free"}' https://sailfork.com/api/orgs/acme/billing/plan