API reference · TeamTeams
Teams and account
Who a token acts as, the teams it reaches, a team's settings, overview and notifications.
Call GET /v1/me first: it confirms the token works and lists the one team (and project, for a project-limited token) it reaches. Every other route is under /v1/teams/{team}, where {team} is the team's slug or its team_ id. Members, invites, tokens and the team's security rules are managed in the dashboard: an API token can't reach them (see Authentication).
The team object
Fields
idstringrequirednamestringrequiredslugstringrequiredavatar_urlstring or nullA path on this API (
/v1/teams/{id}/avatar?v=…) for an uploaded avatar.default_regionstringrolestringrequiredOne of
owner,admin,member,viewer.require_two_factorbooleanMembers without two-factor are refused on this team's routes (403).
session_max_age_daysintegerA member whose session started longer ago is refused on this team (403) until they sign in again. The settings page offers 1, 7 and 30: every session ends after 30 days anyway, so a longer limit never applies.
invitersstringowners: owners and admins invite.members: members may too (as member or viewer only).One of
owners,members.sign_in_methodsarray of stringHow members may have signed in. A member whose session used another method (or one from before methods were recorded) is refused on this team (403) until they sign in again with one of these.
planstringrequiredOne of
free,pro.billing_alertnull or BillingAlertThe owners' billing notice (see
GET .../billingbanner), so the app shell can show it without another call. Null for everyone else and most of the time.Show 6 child fieldsHide child fields
kindstringrequiredAlways
downgraded.atstringamount_ngninteger or nullchargestringOne of
automatic,manual.grace_ends_atstringends_atstring
created_atstringrequired
Current user
Current user, with their teams and each team's newest projects, so the app can render its shell from one call.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Response 200
The signed-in user with their teams, each with its newest projects.idstringrequiredemailstringrequirednamestringrequiredusernamestring or nullTheir handle: unique, lowercase letters, numbers and dashes. Null until they set one.
avatar_urlstring or nullA path on this API (
/v1/users/{id}/avatar?v=…) for an uploaded photo, or an absolute URL from a sign-in provider.two_factor_enabledbooleanWhether the person has two-factor on. On a team member it is as of their last visit.
sign_in_methodsarray of stringThe OAuth providers linked to this account. Email link is always available and is not listed here.
time_zonestring or nullTheir IANA time zone for clocks and dates. Null until they set one.
product_updatesbooleanWhether they opted in to product-update emails.
sessionobjectThis session, as a team's sign-in method and session length rules see it.
Show 2 child fieldsHide child fields
methodstring or nullapi_tokenwhen the bearer is an API token. Null for a session from before methods were recorded.One of
email,github,gitlab,bitbucket,api_token.started_atstring or nullWhen the session signed in, or when the API token was made.
tokenobjectOnly when the bearer is an API token (
orb_live_…), what it may do. Absent for a session.Show 5 child fieldsHide child fields
idstringrequiredteam_idstringrequiredThe one team the token acts in.
accessstringrequiredOne of
full,read.project_idstring or nullrequiredThe one project the token is limited to, or null for every project of the team.
created_atstringrequired
teamsarray of objectrequiredThe teams the caller belongs to (all of
GET /v1/teams), each with a preview of its projects.Show 15 child fieldsHide child fields
idstringrequirednamestringrequiredslugstringrequiredavatar_urlstring or nullA path on this API (
/v1/teams/{id}/avatar?v=…) for an uploaded avatar.default_regionstringrolestringrequiredOne of
owner,admin,member,viewer.require_two_factorbooleanMembers without two-factor are refused on this team's routes (403).
session_max_age_daysintegerA member whose session started longer ago is refused on this team (403) until they sign in again. The settings page offers 1, 7 and 30: every session ends after 30 days anyway, so a longer limit never applies.
invitersstringowners: owners and admins invite.members: members may too (as member or viewer only).One of
owners,members.sign_in_methodsarray of stringHow members may have signed in. A member whose session used another method (or one from before methods were recorded) is refused on this team (403) until they sign in again with one of these.
planstringrequiredOne of
free,pro.billing_alertnull or BillingAlertThe owners' billing notice (see
GET .../billingbanner), so the app shell can show it without another call. Null for everyone else and most of the time.Show 6 child fieldsHide child fields
kindstringrequiredAlways
downgraded.atstringamount_ngninteger or nullchargestringOne of
automatic,manual.grace_ends_atstringends_atstring
created_atstringrequiredproject_countintegerrequiredAll projects in the team.
projectsarray of ProjectrequiredThe newest 20 projects, in the order of
GET /v1/teams/{team}/projects. Compare withproject_count, and call that endpoint for the rest.Show 22 child fieldsHide child fields
idstringrequiredslugstringrequirednamestringrequiredfree_addressstringrequiredHost name,
<slug>.theorbits.app.workloadWorkloadrequiredShow 14 child fieldsHide child fields
typestringrequiredAlways
container.output_directorystringspa_fallbackbooleanDefaults to
false.frameworkstringmemory_mbintegerAt least 128.
timeout_secondsintegerAt least 1.
commandarray of stringreplicasintegerAt least 1. Defaults to
1.schedulestring or nullCron expression for scheduled jobs; null for a continuous worker.
portintegerFrom 1 to 65535.
health_check_pathstringDefaults to
/.start_commandarray of stringimagestring or nullPrebuilt image reference. Mutually exclusive with
dockerfile_path.dockerfile_pathstring or null
sourcenull or SourceShow 4 child fieldsHide child fields
providerstringrequiredOne of
github,gitlab,bitbucket,gitbucket.repositorystringrequiredproduction_branchstringrequiredDefaults to
main.root_directorystringDefaults to
./.
source_kindstringupload: deployed by dropping files (POST .../uploads);sourceis null and there is no repository.One of
git,upload. Defaults togit.buildBuildConfigShow 7 child fieldsHide child fields
frameworkstring or nullinstall_commandstring or nullnull means detected default.
build_commandstring or nulloutput_directorystring or nullignore_commandstring or nullThe ignored build step: run after cloning, in the repository (the commit and the one before it), as the build runs; exit 0 skips building this commit (the deployment ends
canceled, saying why), anything else builds it. Two minutes at most, then it builds. It seesORBITS_GIT_COMMIT_SHA,ORBITS_GIT_COMMIT_REFandORBITS_ENV, and theirVERCEL_*names. Example:git diff --quiet HEAD^ HEAD -- ./apps/storefront.changed_byobject or nullWho last changed a build setting ("Changed by Tunde Bakare yesterday").
Show 2 child fieldsHide child fields
idstringnamestring
changed_atstring or null
framework_versionstring or nullShown next to the framework on the overview header, e.g.
15.node_versionstringregionstringrequiredstatusstringrequiredWhat the project cards and the project switcher show.
pendingmeans nothing has been deployed yet.building,readyandfailedfollow the latest deployment (a canceled latest one falls back to production:ready, orpendingif nothing served yet).One of
pending,building,ready,failed,paused.pausedbooleangitGitSettingsrequiredShow 3 child fieldsHide child fields
deploy_on_pushbooleanrequiredPushes to the production branch go to production; other branches get a preview.
preview_pull_requestsbooleanrequiredEach pull request gets its own address.
comment_on_pull_requestsbooleanrequiredPost the preview link on the pull request and update it on every push.
preview_protectionstringWho may open previews (production stays public).
password: the edge asks for the project's preview password and remembers it for 12 hours.One of
none,team_members,password. Defaults toteam_members.production_urlstring or nulllatest_deployment_idstring or nulllatest_deploymentnull or LatestDeploymentShow 8 child fieldsHide child fields
idstringrequiredstatestringrequiredqueuedwaits for a builder; the screens show it as building.One of
queued,building,ready,failed,canceled.branchstring or nullcommit_shastring or nullcommit_messagestring or nullauthorobject or nullShow 2 child fieldsHide child fields
namestringavatar_urlstring or null
failure_reasonstring or nullcreated_atstringrequired
thumbnail_urlstring or nullAPI path of the screenshot of what production serves, for the project card (the
screenshot_urlof that deployment). Null until production has one. Fetch it with the session, like any API call.thumbnail_colorstring or nullThe screenshot's most common strong colour, which the project card glows in. Null without a screenshot, or when the page is all black, white and grey.
created_atstringrequiredupdated_atstring
curl "https://api.theorbits.app/v1/me" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"id": "usr_01jc8x6e4mq2v7r9y3t5b0zp8w",
"email": "ada@example.com",
"name": "my-app",
"username": null,
"avatar_url": "https://my-app.theorbits.app",
"two_factor_enabled": false,
"sign_in_methods": [
"github"
],
"time_zone": null,
"product_updates": false,
"session": {
"method": "email",
"started_at": "2026-11-10T09:30:00Z"
},
"token": {
"id": "usr_01jc8x6e4mq2v7r9y3t5b0zp8w",
"team_id": "team_01jc8x6e4mq2v7r9y3t5b0zp8w",
"access": "full",
"project_id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w",
"created_at": "2026-11-10T09:30:00Z"
},
"teams": [
{
"id": "team_01jc8x6e4mq2v7r9y3t5b0zp8w",
"name": "My Team",
"slug": "my-app",
"avatar_url": "https://my-app.theorbits.app",
"default_region": "abj-1",
"role": "owner",
"require_two_factor": false,
"session_max_age_days": 1,
"inviters": "owners",
"sign_in_methods": [
"email"
],
"plan": "free",
"billing_alert": {
"kind": null,
"at": null,
"amount_ngn": null,
"charge": null
},
"created_at": "2026-11-10T09:30:00Z",
"project_count": 1,
"projects": [
{
"id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w",
"slug": "my-app",
"name": "my-app",
"free_address": "storefront.theorbits.app",
"workload": null,
"source": null,
"source_kind": "git",
"build": {
"framework": null,
"install_command": null,
"build_command": null,
"output_directory": null,
"ignore_command": null,
"changed_by": null,
"changed_at": null
},
"framework_version": "15",
"node_version": "22.x",
"region": "abj-1",
"status": "pending",
"paused": false,
"git": {
"deploy_on_push": null,
"preview_pull_requests": null,
"comment_on_pull_requests": null
},
"preview_protection": "team_members",
"production_url": "https://my-app.theorbits.app",
"latest_deployment_id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
"latest_deployment": null,
"thumbnail_url": "https://my-app.theorbits.app",
"thumbnail_color": "#7c3aed",
"created_at": "2026-11-10T09:30:00Z",
"updated_at": "2026-11-10T09:30:00Z"
}
]
}
]
}Teams the caller belongs to
Teams the caller belongs to.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Query parameters
limitintegerFrom 1 to 100. Defaults to
25.cursorstring
Response 200
Teams.next_cursorstring or nullitemsarray of TeamrequiredShow 13 child fieldsHide child fields
idstringrequirednamestringrequiredslugstringrequiredavatar_urlstring or nullA path on this API (
/v1/teams/{id}/avatar?v=…) for an uploaded avatar.default_regionstringrolestringrequiredOne of
owner,admin,member,viewer.require_two_factorbooleanMembers without two-factor are refused on this team's routes (403).
session_max_age_daysintegerA member whose session started longer ago is refused on this team (403) until they sign in again. The settings page offers 1, 7 and 30: every session ends after 30 days anyway, so a longer limit never applies.
invitersstringowners: owners and admins invite.members: members may too (as member or viewer only).One of
owners,members.sign_in_methodsarray of stringHow members may have signed in. A member whose session used another method (or one from before methods were recorded) is refused on this team (403) until they sign in again with one of these.
planstringrequiredOne of
free,pro.billing_alertnull or BillingAlertThe owners' billing notice (see
GET .../billingbanner), so the app shell can show it without another call. Null for everyone else and most of the time.Show 6 child fieldsHide child fields
kindstringrequiredAlways
downgraded.atstringamount_ngninteger or nullchargestringOne of
automatic,manual.grace_ends_atstringends_atstring
created_atstringrequired
curl "https://api.theorbits.app/v1/teams" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"next_cursor": null,
"items": [
{
"id": "team_01jc8x6e4mq2v7r9y3t5b0zp8w",
"name": "My Team",
"slug": "my-app",
"avatar_url": "https://my-app.theorbits.app",
"default_region": "abj-1",
"role": "owner",
"require_two_factor": false,
"session_max_age_days": 1,
"inviters": "owners",
"sign_in_methods": [
"email"
],
"plan": "free",
"billing_alert": {
"kind": "upcoming",
"at": "2026-11-10T09:30:00Z",
"amount_ngn": null,
"charge": "automatic"
},
"created_at": "2026-11-10T09:30:00Z"
}
]
}Get a team
Get a team.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.
Response 200
The team, with its members and pending email invites.idstringrequirednamestringrequiredslugstringrequiredavatar_urlstring or nullA path on this API (
/v1/teams/{id}/avatar?v=…) for an uploaded avatar.default_regionstringrolestringrequiredOne of
owner,admin,member,viewer.require_two_factorbooleanMembers without two-factor are refused on this team's routes (403).
session_max_age_daysintegerA member whose session started longer ago is refused on this team (403) until they sign in again. The settings page offers 1, 7 and 30: every session ends after 30 days anyway, so a longer limit never applies.
invitersstringowners: owners and admins invite.members: members may too (as member or viewer only).One of
owners,members.sign_in_methodsarray of stringHow members may have signed in. A member whose session used another method (or one from before methods were recorded) is refused on this team (403) until they sign in again with one of these.
planstringrequiredOne of
free,pro.billing_alertnull or BillingAlertThe owners' billing notice (see
GET .../billingbanner), so the app shell can show it without another call. Null for everyone else and most of the time.Show 6 child fieldsHide child fields
kindstringrequiredAlways
downgraded.atstringamount_ngninteger or nullchargestringOne of
automatic,manual.grace_ends_atstringends_atstring
created_atstringrequirednotificationsNotificationRulesSettings > Notifications: one switch per event and channel. Email goes to everyone who can deploy (owners, admins and members). A Slack switch decides whether that event goes to Slack; the Slack integration's page decides the channel (
PATCH /v1/teams/{team}/integrations/slack).deploy.failed: a production or preview build fails.deploy.live: a production deploy goes live (off until turned on).domain.attention: a domain's DNS stops pointing at Orbits, its certificate can't be issued, or one within 14 days of expiring hasn't renewed; email goes to everyone who can deploy. A domain still not set up an hour after adding it also gets its own DNS email, to whoever added it (the same switch turns it off).member.joined: someone joins (not told to themselves).weekly: Mondays at 9:00 Lagos, the past Monday to Sunday across the team's projects; on Slack it is a short post (visitors, deploys, build time) in the channel picked fordeploy.live, or any channel the Slack page has.Show 5 child fieldsHide child fields
deploy.failedNotificationSwitchesrequiredShow 2 child fieldsHide child fields
emailbooleanrequiredslackbooleanrequired
deploy.liveNotificationSwitchesrequiredShow 2 child fieldsHide child fields
emailbooleanrequiredslackbooleanrequired
domain.attentionNotificationSwitchesrequiredShow 2 child fieldsHide child fields
emailbooleanrequiredslackbooleanrequired
member.joinedNotificationSwitchesrequiredShow 2 child fieldsHide child fields
emailbooleanrequiredslackbooleanrequired
weeklyNotificationSwitchesrequiredShow 2 child fieldsHide child fields
emailbooleanrequiredslackbooleanrequired
membersarray of MemberrequiredActive members, then pending email invites (
status: invited). Same rows asGET /v1/teams/{team}/memberswithoutq.Show 6 child fieldsHide child fields
userUserrequiredShow 6 child fieldsHide child fields
idstringrequiredemailstringrequirednamestringrequiredusernamestring or nullTheir handle: unique, lowercase letters, numbers and dashes. Null until they set one.
avatar_urlstring or nullA path on this API (
/v1/users/{id}/avatar?v=…) for an uploaded photo, or an absolute URL from a sign-in provider.two_factor_enabledbooleanWhether the person has two-factor on. On a team member it is as of their last visit.
rolestringrequiredOne of
owner,admin,member,viewer.statusstringrequiredOne of
active,invited.invite_idstringPresent only for invited rows; use it for resend and revoke operations.
joined_atstring or nulllast_active_atstring or nullWhen the person last used this team with their session (not an API token), accurate to the minute. Null for a pending invite and for anyone who hasn't used the team since this was recorded; show it as "Never" only for an active member who really hasn't.
Errors
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
Every code is explained in Errors.
curl "https://api.theorbits.app/v1/teams/my-team" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"id": "team_01jc8x6e4mq2v7r9y3t5b0zp8w",
"name": "My Team",
"slug": "my-app",
"avatar_url": "https://my-app.theorbits.app",
"default_region": "abj-1",
"role": "owner",
"require_two_factor": false,
"session_max_age_days": 1,
"inviters": "owners",
"sign_in_methods": [
"email"
],
"plan": "free",
"billing_alert": {
"kind": "upcoming",
"at": "2026-11-10T09:30:00Z",
"amount_ngn": null,
"charge": "automatic"
},
"created_at": "2026-11-10T09:30:00Z",
"notifications": {
"deploy.failed": {
"email": "ada@example.com",
"slack": false
},
"deploy.live": {
"email": "ada@example.com",
"slack": false
},
"domain.attention": {
"email": "ada@example.com",
"slack": false
},
"member.joined": {
"email": "ada@example.com",
"slack": false
},
"weekly": {
"email": "ada@example.com",
"slack": false
}
},
"members": [
{
"user": {
"id": "usr_01jc8x6e4mq2v7r9y3t5b0zp8w",
"email": "ada@example.com",
"name": "my-app",
"username": null,
"avatar_url": "https://my-app.theorbits.app",
"two_factor_enabled": false
},
"role": "owner",
"status": "active",
"invite_id": "invite-id",
"joined_at": "2026-11-10T09:30:00Z",
"last_active_at": "2026-11-10T09:30:00Z"
}
]
}Rename, change slug, avatar, default region, or security rules
Rename, change slug, avatar, default region, or security rules.
Changing the slug breaks old dashboard links. All settings require an owner or admin.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.
Body
application/jsonnamestringslugstringavatar_urlstring or nulldefault_regionstringAbuja is the only region in v1.
One of
abj-1.require_two_factorbooleansession_max_age_daysintegerFrom 1 to 365.
invitersstringOne of
owners,members.sign_in_methodsarray of string422 when it leaves out the method the caller signed in with.
notificationsobjectOnly the switches that change, as
{"deploy.live": {"email": true}}; the rest stay. 422 onnotificationsfor an unknown event or channel.
Response 200
Updated.idstringrequirednamestringrequiredslugstringrequiredavatar_urlstring or nullA path on this API (
/v1/teams/{id}/avatar?v=…) for an uploaded avatar.default_regionstringrolestringrequiredOne of
owner,admin,member,viewer.require_two_factorbooleanMembers without two-factor are refused on this team's routes (403).
session_max_age_daysintegerA member whose session started longer ago is refused on this team (403) until they sign in again. The settings page offers 1, 7 and 30: every session ends after 30 days anyway, so a longer limit never applies.
invitersstringowners: owners and admins invite.members: members may too (as member or viewer only).One of
owners,members.sign_in_methodsarray of stringHow members may have signed in. A member whose session used another method (or one from before methods were recorded) is refused on this team (403) until they sign in again with one of these.
planstringrequiredOne of
free,pro.billing_alertnull or BillingAlertThe owners' billing notice (see
GET .../billingbanner), so the app shell can show it without another call. Null for everyone else and most of the time.Show 6 child fieldsHide child fields
kindstringrequiredAlways
downgraded.atstringamount_ngninteger or nullchargestringOne of
automatic,manual.grace_ends_atstringends_atstring
created_atstringrequired
Errors
- 403Authenticated but not allowed in this team.
- 409The request conflicts with current state.
- 422Validation failed, or the Idempotency-Key was reused with a different body.
Every code is explained in Errors.
curl -X PATCH "https://api.theorbits.app/v1/teams/my-team" \
-H "Authorization: Bearer $ORBITS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "My Team",
"slug": "my-app",
"avatar_url": "https://my-app.theorbits.app",
"default_region": "abj-1",
"require_two_factor": false,
"session_max_age_days": 1,
"inviters": "owners",
"sign_in_methods": [
"email"
],
"notifications": {}
}'{
"id": "team_01jc8x6e4mq2v7r9y3t5b0zp8w",
"name": "My Team",
"slug": "my-app",
"avatar_url": "https://my-app.theorbits.app",
"default_region": "abj-1",
"role": "owner",
"require_two_factor": false,
"session_max_age_days": 1,
"inviters": "owners",
"sign_in_methods": [
"email"
],
"plan": "free",
"billing_alert": {
"kind": "upcoming",
"at": "2026-11-10T09:30:00Z",
"amount_ngn": null,
"charge": "automatic"
},
"created_at": "2026-11-10T09:30:00Z"
}Dashboard overview for a time range
Dashboard overview for a time range, worked out when asked. deployments.total counts deployments started in the range, and delta_vs_previous compares it with the range before (the 24 hours, 7 or 30 days before that). average_build_seconds is the mean build of those that went ready, 0 when none did. requests.total counts requests to any of the team's deployments, production and previews, in the range; month_to_date since midnight on the 1st in Lagos. Both are 0 while the log store can't be reached. projects.failing and needs_attention are the projects whose latest deployment failed. series cuts the range into equal slices, oldest first (7 for 24h and 7d, 4 for 30d), and gives each one's deployments, average ready build (0 when none) and requests, so series.deployments adds up to deployments.total.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.
Query parameters
rangestringOne of
24h,7d,30d. Defaults to24h.
Response 200
Aggregated figures and recent items.rangestringrequiredlogs_availablebooleanrequiredFalse while the log store can't be reached:
requestsandseries.requestsare then zeros, not a quiet day. Show them as unavailable.projectsobjectrequiredShow 2 child fieldsHide child fields
totalintegerfailinginteger
deploymentsobjectrequiredShow 2 child fieldsHide child fields
totalintegerdelta_vs_previousinteger
average_build_secondsnumberrequestsobjectrequiredShow 2 child fieldsHide child fields
totalintegermonth_to_dateinteger
seriesobjectThe range in equal slices, oldest first.
Show 3 child fieldsHide child fields
deploymentsarray of integerrequiredaverage_build_secondsarray of numberrequiredrequestsarray of integerrequired
needs_attentionarray of objectShow 3 child fieldsHide child fields
kindstringrequiredmessagestringrequiredlinkstring
curl "https://api.theorbits.app/v1/teams/my-team/overview" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"range": "range",
"logs_available": false,
"projects": {
"total": 1,
"failing": 1
},
"deployments": {
"total": 1,
"delta_vs_previous": 1
},
"average_build_seconds": 1,
"requests": {
"total": 1,
"month_to_date": 1
},
"series": {
"deployments": [
1
],
"average_build_seconds": [
1
],
"requests": [
1
]
},
"needs_attention": [
{
"kind": "kind",
"message": "message",
"link": "link"
}
]
}Notifications for the caller in this team
The top bar's notifications: the team activity lines worth a nudge, newest first, with whether the caller has read each. They are a failed deployment (deployment.failed), a domain going live (domain.live) or stopping pointing at Orbits (domain.misconfigured), a certificate that couldn't be issued or isn't renewing (domain.certificate.failed), a member joining (team.member.added, but not the caller's own) and an alert firing (alert.fired). The list goes back 30 days, and no further than when the caller joined the team. unread_count counts the unread ones, up to 100, whatever the page.
Permissions: Any team member. A non-member gets 404.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.
Query parameters
limitintegerFrom 1 to 50. Defaults to
20.cursorstringunreadbooleanOnly the ones the caller hasn't read.
Response 200
Notifications.next_cursorstring or nullitemsarray of NotificationrequiredShow 8 child fieldsHide child fields
idstringrequiredtypestringrequiredThe event it came from.
One of
deployment.failed,domain.live,domain.misconfigured,domain.certificate.failed,team.member.added,alert.fired.titlestringrequireddetailstring or nullrequiredThe second line: a failed deploy's reason and branch (just
On mainfor one recorded before reasons were kept), who invited a new member, or what to do about a domain.linkstring or nullrequiredA path of this API to open as the app's own page; null when there's nowhere to go.
projectnull or objectrequiredShow 3 child fieldsHide child fields
idstringrequiredslugstringrequirednamestringrequired
readbooleanrequiredcreated_atstringrequired
unread_countintegerrequiredThe caller's unread notifications, up to 100.
At most 100.
Errors
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 422Validation failed, or the Idempotency-Key was reused with a different body.
Every code is explained in Errors.
curl "https://api.theorbits.app/v1/teams/my-team/notifications" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"next_cursor": null,
"items": [
{
"id": "act_01jc8x6e4mq2v7r9y3t5b0zp8w",
"type": "deployment.failed",
"title": "store failed to deploy",
"detail": "Missing module 'mdsvex' · main",
"link": "/teams/rsty-org/projects/store/deployments/dpl_1",
"project": {
"id": "id",
"slug": "my-app",
"name": "my-app"
},
"read": false,
"created_at": "2026-11-10T09:30:00Z"
}
],
"unread_count": 1
}Mark notifications read
Marks notifications read for the caller only. Send ids (from GET /v1/teams/{team}/notifications) for some, or all: true for every one up to now; with all, ids is ignored. Ids of another team's notifications are ignored.
Permissions: Any team member, for their own notifications. A non-member gets 404.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….Idempotency-KeystringrequiredA new value, such as a UUID, for each change. Resend with the same value and body to retry safely.
From 8 to 128 characters.
Path parameters
teamstringrequiredTeam slug or
team_id.
Body
application/jsonidsarray of stringAt most 100 items.
allboolean
Response 204
Marked. No body.
Errors
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 422Validation failed, or the Idempotency-Key was reused with a different body.
Every code is explained in Errors.
curl -X POST "https://api.theorbits.app/v1/teams/my-team/notifications" \
-H "Authorization: Bearer $ORBITS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"ids": [
"ids"
],
"all": false
}'