Connectors
- GET
/rest/v1.0/companies/{company_id}/connectorsList saved connection metadata - GET
/rest/v1.0/companies/{company_id}/connectors/{id}Read connection metadata - GET
/rest/v1.0/companies/{company_id}/connectors/{id}/runsList extraction run health - GET
/rest/v1.0/companies/{company_id}/connectors/{id}/runs/{run_id}Read extraction run health
/rest/v1.0/companies/{company_id}/connectorsList saved connection metadata
Requires connectors:read for nonlegacy scoped tokens and an active same-company admin or superadmin. Suspended/expired workspace reads remain available. No cross-company support bypass.
Parameters
- company_idintegerpathrequired
- pageintegerquery
- per_pageintegerquery
- includestringquerySet to authentication to include safe persisted credential and refresh metadata. This does not verify provider authorization or token validity.
Response · 200 · object
- dataobject[]required
- data[].idstring (uuid)required
- data[].provider_labelstringrequired
- data[].environmentstringrequiredOne of: sandbox, production, unknown.
- data[].operational_statusstringrequiredOne of: active, paused, revoked, unknown.
- data[].authorizationstringrequired
- data[].setup_availablebooleanrequired
- data[].mutations_availablebooleanrequired
- data[].created_atstring (date-time)required
- data[].updated_atstring (date-time)required
- data[].authenticationobject
- totalintegerrequired
- pageintegerrequired
- per_pageintegerrequired
Errors
400Invalid pagination401Unauthenticated403Scope or admin/tenant access denied404Missing or foreign record429Rate limited503Metadata unavailable; SQL details redacted
Example request
Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/connectors" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/connectors/{id}Read connection metadata
Requires connectors:read for nonlegacy scoped tokens and an active same-company admin or superadmin. Suspended/expired workspace reads remain available. No cross-company support bypass.
Parameters
- company_idintegerpathrequired
- idstring (uuid)pathrequired
- includestringquerySet to authentication to include safe persisted credential and refresh metadata. This does not verify provider authorization or token validity.
Response · 200 · object
- idstring (uuid)required
- provider_labelstringrequired
- environmentstringrequiredOne of: sandbox, production, unknown.
- operational_statusstringrequiredOne of: active, paused, revoked, unknown.
- authorizationstringrequired
- setup_availablebooleanrequired
- mutations_availablebooleanrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- authenticationobject
- authentication.binding_statusstringrequiredOne of: not_configured, recorded, mismatch.
- authentication.credential_recordedbooleanrequired
- authentication.oauth_pendingbooleanrequired
- authentication.refresh_statestringrequiredOne of: none, claimed, request_started, uncertain.
- authentication.authorizationstringrequired
- authentication.token_expirystringrequired
- authentication.remote_revocationstringrequired
- authentication.updated_atstring (date-time) | nullrequired
Errors
400Invalid pagination401Unauthenticated403Scope or admin/tenant access denied404Missing or foreign record429Rate limited503Metadata unavailable; SQL details redacted
Example request
Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/connectors/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/connectors/{id}/runsList extraction run health
Requires connectors:read for nonlegacy scoped tokens and an active same-company admin or superadmin. Suspended/expired workspace reads remain available. No cross-company support bypass.
Parameters
- company_idintegerpathrequired
- idstring (uuid)pathrequired
- pageintegerquery
- per_pageintegerquery
- includestringquerySet to authentication to include safe persisted credential and refresh metadata. This does not verify provider authorization or token validity.
Response · 200 · object
- dataobject[]required
- data[].idstring (uuid)required
- data[].statusstringrequiredOne of: queued, running, paused, completed, cancelled, unknown.
- data[].healthstringrequiredOne of: error, partial, staged, queued, running, paused, cancelled, unknown.
- data[].pagesintegerrequired
- data[].staged_countintegerrequired
- data[].quarantine_countintegerrequired
- data[].error_codestring | nullrequired
- data[].adapter_versionstring | nullrequired
- data[].source_api_versionstring | nullrequired
- data[].authorizationstringrequired
- data[].coveragestringrequired
- data[].lag_secondsnullrequired
- data[].deprecationstringrequired
- data[].domain_appliednullrequired
- data[].created_atstring (date-time)required
- data[].updated_atstring (date-time)required
- data[].authenticationobject
- totalintegerrequired
- pageintegerrequired
- per_pageintegerrequired
- authenticationobject
- authentication.binding_statusstringrequiredOne of: not_configured, recorded, mismatch.
- authentication.credential_recordedbooleanrequired
- authentication.oauth_pendingbooleanrequired
- authentication.refresh_statestringrequiredOne of: none, claimed, request_started, uncertain.
- authentication.authorizationstringrequired
- authentication.token_expirystringrequired
- authentication.remote_revocationstringrequired
- authentication.updated_atstring (date-time) | nullrequired
Errors
400Invalid pagination401Unauthenticated403Scope or admin/tenant access denied404Missing or foreign record429Rate limited503Metadata unavailable; SQL details redacted
Example request
Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/connectors/1/runs" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/companies/{company_id}/connectors/{id}/runs/{run_id}Read extraction run health
Requires connectors:read for nonlegacy scoped tokens and an active same-company admin or superadmin. Suspended/expired workspace reads remain available. No cross-company support bypass.
Parameters
- company_idintegerpathrequired
- idstring (uuid)pathrequired
- run_idstring (uuid)pathrequired
- includestringquerySet to authentication to include safe persisted credential and refresh metadata. This does not verify provider authorization or token validity.
Response · 200 · object
- idstring (uuid)required
- statusstringrequiredOne of: queued, running, paused, completed, cancelled, unknown.
- healthstringrequiredOne of: error, partial, staged, queued, running, paused, cancelled, unknown.
- pagesintegerrequired
- staged_countintegerrequired
- quarantine_countintegerrequired
- error_codestring | nullrequired
- adapter_versionstring | nullrequired
- source_api_versionstring | nullrequired
- authorizationstringrequired
- coveragestringrequired
- lag_secondsnullrequired
- deprecationstringrequired
- domain_appliednullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
- authenticationobject
- authentication.binding_statusstringrequiredOne of: not_configured, recorded, mismatch.
- authentication.credential_recordedbooleanrequired
- authentication.oauth_pendingbooleanrequired
- authentication.refresh_statestringrequiredOne of: none, claimed, request_started, uncertain.
- authentication.authorizationstringrequired
- authentication.token_expirystringrequired
- authentication.remote_revocationstringrequired
- authentication.updated_atstring (date-time) | nullrequired
Errors
400Invalid pagination401Unauthenticated403Scope or admin/tenant access denied404Missing or foreign record429Rate limited503Metadata unavailable; SQL details redacted
Example request
Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/connectors/1/runs/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"