Uses: Python · TypeScript · CLI · REST API
supportsObjectSelection on the application, or useSelectDBObjects on the connection.
The sequence is refresh → poll → browse → select → poll again.
cURL samples assume
BASE=https://api.engini.io/v1 and AUTH="x-api-key: $ENGINI_API_KEY" - the setup from the REST walkthrough. Steps 1-2 are shown raw first because the polling contract is where the surprises live; the SDK and CLI wrap both steps in one call (the CodeGroup in step 2).1. Trigger a refresh
Refresh is asynchronous. An empty200 means accepted, not finished.
Async triggers can return a gateway
502/503/504 while the job is still accepted server-side. Don’t treat that as failure - the status poll is the source of truth. Both SDKs already tolerate this.2. Poll until it settles
3. Browse what’s available
offset/top, up to 1000 per page) - see paging large catalogs. The SDKs and CLI page for you.
4. Select
Selecting triggers another refresh, so wait forrefresh-status again before assuming the new objects are queryable:
errorCode OBJECT_STRUCTURE_UPDATE_FAILED (rebuilding the selected objects’ structure failed) or OBJECT_SYNC_FAILED (syncing individual objects failed), and the reasons in message. The selection is still saved; fix the cause and select again. message is human-readable, may be truncated (1000 characters), and must not be parsed - only errorCode is contract. The SDKs raise EnginiValidationError.
For OBJECT_STRUCTURE_UPDATE_FAILED the text also reaches refresh-status (error) and the connection’s connectionError, capped at 250 characters. OBJECT_SYNC_FAILED is not recorded there, so refresh-status can still read Ok after a sync-only failure: trust the 400.
Adding to an existing selection
A useful side effect
A completed refresh is the strongest health signal a connection can give you - stronger thancheck, which can return an inconclusive empty 200. A refresh that finishes proves the credential actually authenticated against the provider. If you only run one verification after creating a connection, make it this one.