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:read scope. Changes need org:admin. Leaving an organization and answering your own invitations need the user scope.
  • 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.

FieldTypeNotes
handlestringRequired. 1 to 39 letters, digits and hyphens, not starting or ending with a hyphen. Lowercased. Shares its namespace with people.
namestringRequired. 1 to 100 characters.
taglinestringOptional. At most 200 characters.
locationstringOptional. At most 100 characters.
websitestringOptional. At most 200 characters.
timeZonestringOptional. 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.

FieldMeaning
handle, name, tagline, location, website, timeZoneProfile fields.
avatarUrlThe logo, or null.
verifiedtrue when a domain is verified.
weekTwo counters for the last 7 days: merged pull requests and pull requests opened by agents.
pinnedNames of pinned repositories, in pin order.
reposRepository cards: name, about, visibility, language, crewShare, openPulls, openIssues, pushedAt.
membersname, handle, role (Owner or Member), timeZone, city, hours, public.
feedThe 30 newest events across its repositories: at, actor, agent, text, repo.
filesThe 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.

FieldMeaning
handle, name, avatarUrlThe organization.
roleYour role: Owner or Member.
joinedThe date you joined, YYYY-MM-DD.
onlyOwnertrue when you are its only owner, so you cannot leave.
reposHow many repositories it owns.
deletionAtWhen 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.

FieldTypeNotes
namestring1 to 100 characters.
taglinestringAt most 200 characters.
locationstringAt most 100 characters.
websitestringAt most 200 characters.
timeZonestringAn IANA time zone name.
baseAccessstringnone, read or write. What every member gets on the organization's private repositories.
defaultRepoVisibilitystringpublic or private. What the new-repository form starts on.
requireSecondFactorbooleanSee Security settings.
deviceCopiesbooleanSee 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.

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.

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: true shuts 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 409 add a passkey or an authenticator app to your own account before requiring one. The audit entry records how many members lost access.
  • baseAccess sets what every member can do on the organization's private repositories.
  • deviceCopies: false keeps 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.

FieldTypeMeaning
approvalsintegerApprovals needed before a merge, 0 to 6. Other values are 422.
dismissStalebooleanA push after an approval voids it.
upToDatebooleanThe branch must contain the base branch's tip.
threadsResolvedbooleanEvery code comment thread must be resolved.
selfReviewbooleanThe 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": [...] }.

FieldTypeMeaning
namestring1 to 80 characters, unique within the organization.
enforcementoff, dryRun or activedryRun logs what it would refuse and refuses nothing.
reposstring[]1 to 20 globs over repository names, * for all. Repositories created later match too.
rulesBranchRule[]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.
auditPushesbooleanWrites 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 }.

ParameterTypeNotes
limitintegerDefault 50. Values are held between 1 and 200.
beforestringThe next of the previous page. Any other value is 422.
Event fieldMeaning
id, atThe event id and when it happened.
kindOne of org, member, invite, access, rule, repo, domain, moderation.
actionA machine name such as member.role, invite.create, team.create or org.update.
targetWhat it applied to: a handle, team slug or repository name.
actor, agentWho did it, and whether an agent did.
textA sentence you can show to a person.
metaExtra 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.

FieldMeaning
monthThe month, YYYY-MM.
changes, freeChanges, billableChangesFiles changed through caissons with a token, the free allowance, and the difference, never below 0.
pricePer1000ChangesCents, estimatedCentsThe price per thousand changes and the estimate, in integer cents.
currencyUSD.
sandboxesSandboxes members started this month.
sandboxVcpuMinutesvCPUs 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.

FieldMeaning
planfree or team.
seatsMember count.
cycleStart, cycleDaysThe current billing cycle.
storageGiB, storageBytesRepository storage in use.
billingEmailsThe owners' addresses that receive receipts.
invoicesFinished bills: id, number, period, status, paid, subtotalCents, taxCents, cents, currency, url (Stripe's hosted page).
paymentslive, 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

Loading Sailfork