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.
| Operation | Method and path | Who may call it |
|---|---|---|
| List members | GET /api/orgs/{org}/members | read |
| Change a member | PATCH /api/orgs/{org}/members/{userId} | admin |
| Remove a member | DELETE /api/orgs/{org}/members/{userId} | admin |
| List pending invitations | GET /api/orgs/{org}/invitations | read |
| Invite a person | POST /api/orgs/{org}/invitations | admin |
| Revoke an invitation | DELETE /api/orgs/{org}/invitations/{id} | admin |
| Accept an invitation | POST /api/invitations/{token}/accept | console session |
| List the invitations waiting for the signed-in person | GET /api/me/invitations | console session |
| Accept an invitation waiting for the signed-in person | POST /api/me/invitations/{id}/accept | console 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
userId | string | yes | The member's userId, as listed by the members route. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
role | string | no | The new role. Only an owner can make someone an owner or change an owner's role. One of: owner, admin, member. |
seat | boolean | no | True 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
| Status | Code | When |
|---|---|---|
| 404 | not_found | No member of this organisation has that userId. |
| 403 | forbidden | An API key tried to change a role, or someone who is not an owner tried to grant or change an owner role. |
| 400 | last_owner | The change would leave the organisation without an owner. |
| 403 | step_up_required | Your 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
userId | string | yes | The 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
| Status | Code | When |
|---|---|---|
| 404 | not_found | No member of this organisation has that userId. |
| 403 | forbidden | The member is an owner and the caller is not. An API key is never an owner. |
| 400 | last_owner | The 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
email | string | yes | The address to invite. At most 200 characters. Only an account with this address can accept. |
role | string | no | The 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
| Status | Code | When |
|---|---|---|
| 400 | bad_request | The e-mail address is not valid. |
| 403 | forbidden | The role is owner and the caller is not an owner. |
| 409 | already_member | A 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The 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
| Status | Code | When |
|---|---|---|
| 404 | not_found | There 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
| Name | Type | Required | Description |
|---|---|---|---|
token | string | yes | The 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
| Status | Code | When |
|---|---|---|
| 404 | invalid_invitation | The invitation does not exist, has expired, was revoked, or was already accepted. |
| 403 | forbidden | The invitation was sent to a different e-mail address than the signed-in account's. |
| 403 | sso_session | The 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
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | The 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
| Status | Code | When |
|---|---|---|
| 404 | invalid_invitation | No such invitation is waiting for this person: it does not exist, has expired, was revoked, was already accepted, or was sent to another address. |
| 403 | org_suspended | The organisation that sent it is suspended. |
#Objects
The objects the operations above take and return.
#Member
A person who belongs to the organisation.
| Field | Type | Always present | Description |
|---|---|---|---|
userId | string | yes | The person's id. Use it in the member routes. |
email | string | yes | Their e-mail address. |
name | string | yes | Their display name. |
githubLogin | string | no | Their linked code-host login. Absent when none is linked. |
role | string | yes | Their role in the organisation. One of: owner, admin, member. |
seat | boolean | yes | True when they hold a pull request review seat, which is billable. |
lastActiveAt | string or null | yes | When they last used the organisation. Null when not recorded. |
joinedAt | string | yes | When they joined the organisation. |
#Invitation
An invitation to join the organisation that has not been accepted yet.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The invitation's id. |
email | string | yes | The address the invitation was sent to, in lower case. Only an account with this address can accept it. |
role | string | yes | The role the person gets when they accept. One of: owner, admin, member. |
invitedBy | string | yes | Who sent it: an e-mail address, or api-key:<name> for an API key. |
createdAt | string | yes | When it was sent. |
expiresAt | string | yes | When it stops working: seven days after it was sent. |
#InvitationWithLink
A new invitation together with the link that accepts it. This is the only time the link is returned.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The invitation's id. |
email | string | yes | The address the invitation was sent to, in lower case. Only an account with this address can accept it. |
role | string | yes | The role the person gets when they accept. One of: owner, admin, member. |
invitedBy | string | yes | Who sent it: an e-mail address, or api-key:<name> for an API key. |
createdAt | string | yes | When it was sent. |
expiresAt | string | yes | When it stops working: seven days after it was sent. |
acceptUrl | string | yes | The 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.
| Field | Type | Always present | Description |
|---|---|---|---|
user | User | yes | |
orgs | array of object | yes | The organisations this person belongs to. A single sign-on session lists only the organisation that issued it. |
orgs[].slug | string | yes | The organisation's slug, as used in API paths. |
orgs[].name | string | yes | The organisation's display name. |
orgs[].role | string | yes | This person's role in the organisation. One of: owner, admin, member. |
mfa | object | yes | The multi-factor state of this session. |
mfa.enrolled | boolean | yes | True when the account has multi-factor sign-in set up. |
mfa.verifiedAt | string or null | yes | When this session last passed a second-factor check. Null when it has not. |
method | string | yes | How this session signed in: github, single sign-on (sso), an e-mail link (link), a passkey, or dev on a development server. |
platformAdmin | boolean | no | Present, and true, only for the people who operate the service. |
workspaceCreation | string | yes | Whether 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.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The person's id. |
email | string | yes | Their e-mail address, in lower case. It identifies the account. |
name | string | yes | Their display name. |
githubLogin | string | no | Their linked code-host login, used to match pull request authors to seats. Absent when none is linked. |
createdAt | string | yes | When the account was created. |
Nullgap documentation