Skip to content
StartupBuilderby Startups.Studio
Business
Changelog
Core grammarSource

Integration

An Integration is an outside Source connected to a System with credentials, at Studio, Startup, or Customer scope.

Properties

PropertyTypeRequiredDescription
scopestringrequiredOne of studio, startup, or customer.
syncstringWhich side leads a sync connector: platform or provider.
modestringrequiredHow records move: mirror writes db.sb out to the outside tool; import turns edits there into Changes. db.sb is the record in both.
statestringrequiredWhere the connected account stands; read fresh before every call.
venuestringThe id of the ad, social or app-store venue the account is on, when it is on one.
accountstringThe outside account’s own id, such as an ad account, a workspace or a repository.
grantsstring[]The outside permissions the account holder approved: the narrowest set its Verbs need.
connectedByPartyWho approved the connection; a Human’s own account is used only under that Human’s Mandate.
environmentstringA test Integration reaches only the upstream’s test account, as a Stripe test account does.
expiresAtdatetimeWhen access lapses unless refreshed.
refreshedAtdatetimeWhen the platform last renewed the outside token.
lastErrorstringThe error slug of the last failed call or refresh, cleared by the next success.
cursorstringWhere the last sync run stopped, so the next run reads only what changed.
Inherited from Source: 2 properties
PropertyTypeRequiredDescription
acquiredstringrequiredOne of owned, wrapped, or recruited.
termstextThe terms the Startup holds the right to use and resell it under.

Object

JSON
{
  "$id": "https://api.sb/petpantry.shop/integrations/integration_1",
  "$type": "Integration",
  "acquired": "owned",
  "terms": "Resale allowed under the provider’s published API terms; 10,000 calls a month included.",
  "scope": "studio",
  "sync": "Example sync",
  "mode": "mirror",
  "state": "connecting",
  "venue": "Example venue",
  "account": "Example account",
  "grants": [
    "Example grants"
  ],
  "connectedBy": "party_1",
  "environment": "test",
  "expiresAt": "2026-10-22T12:00:00Z",
  "refreshedAt": "2026-10-22T12:00:00Z",
  "lastError": "Example last error",
  "cursor": "Example cursor"
}

Relationships

Lifecycle

Integration lifecycle: connecting, connected, needsReauth, paused, revoked (ends)connecting → connected: Integration.connectconnecting → revoked: Integration.revokeconnected → needsReauth: Integration.refreshconnected → paused: Integration.pauseconnected → revoked: Integration.revokeneedsReauth → connected: Integration.reconnectneedsReauth → revoked: Integration.revokepaused → connected: Integration.resumepaused → revoked: Integration.revokeconnectingconnectedneedsReauthpausedrevoked
StateMeaningMoves to
connecting (first)Waiting for the account holder to approve the outside account.connected by Integration.connect; revoked by Integration.revoke
connectedCalls and syncs run with a live token.needsReauth by Integration.refresh; paused by Integration.pause; revoked by Integration.revoke
needsReauthThe upstream refused a refresh, so calls wait until the account holder approves again.connected by Integration.reconnect; revoked by Integration.revoke
pausedEvery call stops, and the token and cursor are kept.connected by Integration.resume; revoked by Integration.revoke
revokedIts token is revoked with the upstream; every record it brought in stays.None: it ends here.

Verbs

  1. createCreates an Integration.
    POST /{namespace}/integrationsdoIntegration.created
  2. getReturns one Integration by id.
    GET /{namespace}/integrations/{id}readNo Event
  3. listReturns Integrations, newest first, one page at a time.
    GET /{namespace}/integrationsreadNo Event
  4. updateChanges the given properties of an Integration.
    PATCH /{namespace}/integrations/{id}doIntegration.updated
  5. deleteDeletes an Integration; its history is kept.
    DELETE /{namespace}/integrations/{id}doIntegration.deleted
  6. callCall sends one request to an upstream through an Integration, with its token filled in server-side, for endpoints no Mapping covers.
    POST /{namespace}/integrations/{integration}/calldoIntegration.called
  7. connectConnect asks an account holder to approve an outside account for one System and records the grants they approve.
    POST /{namespace}/integrations/connectdoIntegration.connected
  8. pausePause stops every call through an Integration at once and keeps its token and cursor.
    POST /{namespace}/integrations/{integration}/pausedoIntegration.paused
  9. reconnectReconnect re-approves an Integration in place, keeping its id and cursor, so nothing re-imports.
    POST /{namespace}/integrations/{integration}/reconnectdoIntegration.reconnected
  10. refreshRefresh renews an Integration’s outside token before it expires; a refused refresh moves it to `needsReauth`.
    POST /{namespace}/integrations/{integration}/refreshdoIntegration.refreshed
  11. resumeResume restarts a paused Integration from its cursor and releases the Actions that waited on it.
    POST /{namespace}/integrations/{integration}/resumedoIntegration.resumed
  12. revokeRevoke ends an Integration at once: its token is revoked with the upstream, and every record it brought in stays.
    POST /{namespace}/integrations/{integration}/revokedoIntegration.revoked
  13. syncSync exchanges records between a System and its connector, and the declared leader wins every conflict.
    POST /{namespace}/integrations/{integration}/syncdoIntegration.synced

Permissions

Which Access level may call each Verb. One-way Verbs wait their delay window.

Operationowneradminmemberviewer
Integration.createYesYesYesNo
Integration.getYesYesYesYes
Integration.listYesYesYesYes
Integration.updateYesYesYesNo
Integration.deleteYesYesYesNo
Integration.callYesNoNoNo
Integration.connectYesYesYesNo
Integration.pauseYesYesYesNo
Integration.reconnectYesYesYesNo
Integration.refreshYesYesYesNo
Integration.resumeYesYesYesNo
Integration.revokeYesYesYesNo
Integration.syncYesYesYesNo

Call it

Text
Sync the latest integration.

Example

A bookkeeping service connects each client's bank feed as an Integration at Customer scope. The feed syncs nightly into the client's own Tenant, and db.sb stays the record.

Source.update

Previous Page

Integration.call

Next Page