Workers and connectors
Understand hosted worker lifecycle routes and the connector graph used to bring external systems into an organization.
Workers and connectors are separate systems. Workers run or represent a remote iPolloWork runtime. Connectors model external accounts, instances, targets, mappings, discovery, and sync events.
Worker provisioning, discovery, and sync all need a follow-up read against the returned resource ID.
- 01Create or select
Create a Worker or connector resource, or select an existing scoped object.
- 02Keep the ID
Persist the returned Worker, account, instance, target, or sync-event identifier.
- 03Observe
Read activity, runtime, discovery, mapping, or sync status from the matching route.
- 04Retry narrowly
Repair the owning boundary and retry the specific failed operation rather than duplicating resources.
Hosted workers
The /v1/workers resource family exposes worker records and operational sub-resources:
/v1/workers
/v1/workers/{id}
/v1/workers/{id}/activity-heartbeat
/v1/workers/{id}/runtime
/v1/workers/{id}/runtime/upgrade
/v1/workers/{id}/tokens
Use worker routes only when a deployment includes hosted or organization-managed workers. A local desktop workspace does not require a Cloud worker lifecycle request for normal work.
Connector graph
| Layer | API family | Meaning |
|---|---|---|
| Account | /v1/connector-accounts | Authorized external identity or connection account. |
| Instance | /v1/connector-instances | Configured connector integration with enable, disable, discovery, and targets. |
| Target | /v1/connector-targets | A scoped external target that may have mappings and resync activity. |
| Mapping | /v1/connector-mappings | A relationship between imported or synchronized resource representations. |
| Sync event | /v1/connector-sync-events | Observable sync work and retry state. |
The GitHub connector adds dedicated setup, installation, account, repository, and validation routes under /v1/connectors/github/*, plus a webhook endpoint at /v1/webhooks/connectors/github.
Operational sequence
- Establish and verify an external account.
- Create or configure a connector instance.
- Discover available targets before applying an import or synchronization selection.
- Store mappings and observe sync events.
- Retry a specific failed sync event rather than creating duplicate connections.
Use the live OpenAPI contract for exact request bodies, webhook verification, pagination, error responses, and version-specific fields.
For the full Worker readiness path and GitHub webhook boundary, continue with Runtime, workers, and webhooks.