Nullgap.dev Docs

API reference

People

Members, roles, seats and invitations.

Paths are relative to the address of your Nullgap console. Authentication, errors, paging and rate limits are the same for every call and are described in the API overview.

OperationMethod and pathWho may call it
List membersGET /api/orgs/{org}/membersread
Change a memberPATCH /api/orgs/{org}/members/{userId}admin
Remove a memberDELETE /api/orgs/{org}/members/{userId}admin
List pending invitationsGET /api/orgs/{org}/invitationsread
Invite a personPOST /api/orgs/{org}/invitationsadmin
Revoke an invitationDELETE /api/orgs/{org}/invitations/{id}admin
Accept an invitationPOST /api/invitations/{token}/acceptconsole session
List the invitations waiting for the signed-in personGET /api/me/invitationsconsole session
Accept an invitation waiting for the signed-in personPOST /api/me/invitations/{id}/acceptconsole session

#List members

GET /api/orgs/{org}/members

Answers everyone in the organisation, in the order they joined. This is a plain list, not a paged one.

Who may call it: An API key with the read scope or higher.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Example request

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/members"

Answer (200, application/json)

Every member, earliest joined first.

An array of Member.

[
  {
    "userId": "usr_4c1d9a7be203",
    "email": "dana@acme.example",
    "name": "Dana Okafor",
    "githubLogin": "dana-okafor",
    "role": "admin",
    "seat": true,
    "lastActiveAt": "2026-11-15T16:42:00.000Z",
    "joinedAt": "2026-09-01T08:20:00.000Z"
  }
]

#Change a member

PATCH /api/orgs/{org}/members/{userId}

Changes a member's role, assigns or removes their pull request review seat, or both. Changing a role needs a person signed in to the console (an API key is refused) with a recent second-factor check when their account has one; sending the role the member already has changes nothing and is allowed. Assigning or removing a seat works with an admin API key. A seat is billable.

Who may call it: An API key with the admin scope.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
userIdstringyesThe member's userId, as listed by the members route.

Request body (application/json)

FieldTypeRequiredDescription
rolestringnoThe new role. Only an owner can make someone an owner or change an owner's role. One of: owner, admin, member.
seatbooleannoTrue to assign a pull request review seat, false to remove it.

Example request

curl -s -X PATCH -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role":"admin","seat":true}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/members/userId"

Answer (200, application/json)

A Member object.

{
  "userId": "usr_4c1d9a7be203",
  "email": "dana@acme.example",
  "name": "Dana Okafor",
  "githubLogin": "dana-okafor",
  "role": "admin",
  "seat": true,
  "lastActiveAt": "2026-11-15T16:42:00.000Z",
  "joinedAt": "2026-09-01T08:20:00.000Z"
}

Errors specific to this call

StatusCodeWhen
404not_foundNo member of this organisation has that userId.
403forbiddenAn API key tried to change a role, or someone who is not an owner tried to grant or change an owner role.
400last_ownerThe change would leave the organisation without an owner.
403step_up_requiredYour account has multi-factor sign-in and this session has not passed a second-factor check in the last 15 minutes. Confirm with your authenticator and try again.

#Remove a member

DELETE /api/orgs/{org}/members/{userId}

Removes a person from the organisation. Their seat is released and any Slack identity they linked is removed with them. Their account and their memberships of other organisations are not touched.

Who may call it: An API key with the admin scope.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
userIdstringyesThe member's userId, as listed by the members route.

Example request

curl -s -X DELETE -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/members/userId"

Answer (200, application/json)

An empty object.

{}

Errors specific to this call

StatusCodeWhen
404not_foundNo member of this organisation has that userId.
403forbiddenThe member is an owner and the caller is not. An API key is never an owner.
400last_ownerThe member is the organisation's only owner.

#List pending invitations

GET /api/orgs/{org}/invitations

Answers the invitations that have not been accepted and have not expired. This is a plain list, not a paged one.

Who may call it: An API key with the read scope or higher.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Example request

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/invitations"

Answer (200, application/json)

The pending invitations.

An array of Invitation.

[
  {
    "id": "inv_a81f0c3d92e4",
    "email": "sam@acme.example",
    "role": "member",
    "invitedBy": "dana@acme.example",
    "createdAt": "2026-11-16T09:30:00.000Z",
    "expiresAt": "2026-11-23T09:30:00.000Z"
  }
]

#Invite a person

POST /api/orgs/{org}/invitations

Creates an invitation that lasts seven days and e-mails the link when the server can send mail. The link is also in the answer, once: it is not stored and no other route returns it. Inviting the same address again creates a second invitation; the earlier one keeps working until it expires or is revoked.

Who may call it: An API key with the admin scope.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

FieldTypeRequiredDescription
emailstringyesThe address to invite. At most 200 characters. Only an account with this address can accept.
rolestringnoThe role they get when they accept. Only an owner can invite an owner. Default member.

Example request

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"sam@acme.example","role":"member"}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/invitations"

Answer (200, application/json)

A InvitationWithLink object.

{
  "id": "inv_a81f0c3d92e4",
  "email": "sam@acme.example",
  "role": "member",
  "invitedBy": "dana@acme.example",
  "createdAt": "2026-11-16T09:30:00.000Z",
  "expiresAt": "2026-11-23T09:30:00.000Z",
  "acceptUrl": "https://app.nullgap.example/invite/Qm3xT8vLr2nB5wZc7YkH4sJdF6aGe1UoKi0PqRtXvA9"
}

Errors specific to this call

StatusCodeWhen
400bad_requestThe e-mail address is not valid.
403forbiddenThe role is owner and the caller is not an owner.
409already_memberA person with that address is already a member.

#Revoke an invitation

DELETE /api/orgs/{org}/invitations/{id}

Removes a pending invitation. Its link stops working at once.

Who may call it: An API key with the admin scope.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id.

Example request

curl -s -X DELETE -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/invitations/ID"

Answer (200, application/json)

An empty object.

{}

Errors specific to this call

StatusCodeWhen
404not_foundThere is no invitation with that id in this organisation.

#Accept an invitation

POST /api/invitations/{token}/accept

Makes the signed-in person a member of the organisation that sent the invitation, with the role it names. An invitation works once. The answer is the person's session with the new organisation listed; its method and mfa.verifiedAt are not filled in from the current sign-in here, so read those from GET /api/session.

Who may call it: A signed-in person in the console. This is about your own account, so no API key may call it.

Path parameters

NameTypeRequiredDescription
tokenstringyesThe token from the invitation link: the last part of the acceptUrl returned when the invitation was created.

Answer (200, application/json)

A Session object.

{
  "user": {
    "id": "usr_4c1d9a7be203",
    "email": "dana@acme.example",
    "name": "Dana Okafor",
    "githubLogin": "dana-okafor",
    "createdAt": "2026-09-01T08:15:00.000Z"
  },
  "orgs": [
    {
      "slug": "acme",
      "name": "Acme",
      "role": "owner"
    }
  ],
  "mfa": {
    "enrolled": true,
    "verifiedAt": "2026-11-16T09:12:00.000Z"
  },
  "method": "passkey",
  "workspaceCreation": "open"
}

Errors specific to this call

StatusCodeWhen
404invalid_invitationThe invitation does not exist, has expired, was revoked, or was already accepted.
403forbiddenThe invitation was sent to a different e-mail address than the signed-in account's.
403sso_sessionThe session signed in through single sign-on, which may not accept invitations.

#List the invitations waiting for the signed-in person

GET /api/me/invitations

Answers the invitations sent to the e-mail address the person signed in with that have not expired, so someone who signed in without following the link in the invitation e-mail can still join their team. Invitations from a suspended organisation are left out. A single-sign-on session is answered with an empty list.

Who may call it: A signed-in person in the console. This is about your own account, so no API key may call it.

Answer (200, application/json)

An array of object.

[
  {
    "id": "string",
    "organisation": "string",
    "role": "owner",
    "expiresAt": "2026-11-16T09:30:00.000Z"
  }
]

#Accept an invitation waiting for the signed-in person

POST /api/me/invitations/{id}/accept

Makes the signed-in person a member of the organisation that sent the invitation, with the role it names. Only an invitation sent to the address the person signed in with can be accepted this way. The answer is the person's session with the new organisation listed.

Who may call it: A signed-in person in the console. This is about your own account, so no API key may call it.

Path parameters

NameTypeRequiredDescription
idstringyesThe invitation, from the list of waiting invitations.

Answer (200, application/json)

A Session object.

{
  "user": {
    "id": "usr_4c1d9a7be203",
    "email": "dana@acme.example",
    "name": "Dana Okafor",
    "githubLogin": "dana-okafor",
    "createdAt": "2026-09-01T08:15:00.000Z"
  },
  "orgs": [
    {
      "slug": "acme",
      "name": "Acme",
      "role": "owner"
    }
  ],
  "mfa": {
    "enrolled": true,
    "verifiedAt": "2026-11-16T09:12:00.000Z"
  },
  "method": "passkey",
  "workspaceCreation": "open"
}

Errors specific to this call

StatusCodeWhen
404invalid_invitationNo such invitation is waiting for this person: it does not exist, has expired, was revoked, was already accepted, or was sent to another address.
403org_suspendedThe organisation that sent it is suspended.

#Objects

The objects the operations above take and return.

#Member

A person who belongs to the organisation.

FieldTypeAlways presentDescription
userIdstringyesThe person's id. Use it in the member routes.
emailstringyesTheir e-mail address.
namestringyesTheir display name.
githubLoginstringnoTheir linked code-host login. Absent when none is linked.
rolestringyesTheir role in the organisation. One of: owner, admin, member.
seatbooleanyesTrue when they hold a pull request review seat, which is billable.
lastActiveAtstring or nullyesWhen they last used the organisation. Null when not recorded.
joinedAtstringyesWhen they joined the organisation.

#Invitation

An invitation to join the organisation that has not been accepted yet.

FieldTypeAlways presentDescription
idstringyesThe invitation's id.
emailstringyesThe address the invitation was sent to, in lower case. Only an account with this address can accept it.
rolestringyesThe role the person gets when they accept. One of: owner, admin, member.
invitedBystringyesWho sent it: an e-mail address, or api-key:<name> for an API key.
createdAtstringyesWhen it was sent.
expiresAtstringyesWhen it stops working: seven days after it was sent.

A new invitation together with the link that accepts it. This is the only time the link is returned.

FieldTypeAlways presentDescription
idstringyesThe invitation's id.
emailstringyesThe address the invitation was sent to, in lower case. Only an account with this address can accept it.
rolestringyesThe role the person gets when they accept. One of: owner, admin, member.
invitedBystringyesWho sent it: an e-mail address, or api-key:<name> for an API key.
createdAtstringyesWhen it was sent.
expiresAtstringyesWhen it stops working: seven days after it was sent.
acceptUrlstringyesThe link the invited person opens to accept. Present only in the answer to the request that created the invitation. Store or pass it on now: it cannot be read again.

#Session

The signed-in person and the organisations they can open.

FieldTypeAlways presentDescription
userUseryes
orgsarray of objectyesThe organisations this person belongs to. A single sign-on session lists only the organisation that issued it.
orgs[].slugstringyesThe organisation's slug, as used in API paths.
orgs[].namestringyesThe organisation's display name.
orgs[].rolestringyesThis person's role in the organisation. One of: owner, admin, member.
mfaobjectyesThe multi-factor state of this session.
mfa.enrolledbooleanyesTrue when the account has multi-factor sign-in set up.
mfa.verifiedAtstring or nullyesWhen this session last passed a second-factor check. Null when it has not.
methodstringyesHow this session signed in: github, single sign-on (sso), an e-mail link (link), a passkey, or dev on a development server.
platformAdminbooleannoPresent, and true, only for the people who operate the service.
workspaceCreationstringyesWhether a signed-in person may create a workspace with POST /api/orgs (open), or new workspaces are set up for invited clients only (invite-only); then join one through an invitation.

#User

A person with a Nullgap account.

FieldTypeAlways presentDescription
idstringyesThe person's id.
emailstringyesTheir e-mail address, in lower case. It identifies the account.
namestringyesTheir display name.
githubLoginstringnoTheir linked code-host login, used to match pull request authors to seats. Absent when none is linked.
createdAtstringyesWhen the account was created.

Nullgap documentation