Esc

↑↓ move↵ openIndex · Pagefind
REST reference · Core Tools

Connectors

4 endpoints4 implementedAll modules →
  1. GET /rest/v1.0/companies/{company_id}/connectorsList saved connection metadata
  2. GET /rest/v1.0/companies/{company_id}/connectors/{id}Read connection metadata
  3. GET /rest/v1.0/companies/{company_id}/connectors/{id}/runsList extraction run health
  4. GET /rest/v1.0/companies/{company_id}/connectors/{id}/runs/{run_id}Read extraction run health
GET /rest/v1.0/companies/{company_id}/connectors

List 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.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • page
    integerquery
  • per_page
    integerquery
  • include
    stringquery
    Set to authentication to include safe persisted credential and refresh metadata. This does not verify provider authorization or token validity.

Response · 200 · object

  • data
    object[]required
  • data[].id
    string (uuid)required
  • data[].provider_label
    stringrequired
  • data[].environment
    stringrequired
    One of: sandbox, production, unknown.
  • data[].operational_status
    stringrequired
    One of: active, paused, revoked, unknown.
  • data[].authorization
    stringrequired
  • data[].setup_available
    booleanrequired
  • data[].mutations_available
    booleanrequired
  • data[].created_at
    string (date-time)required
  • data[].updated_at
    string (date-time)required
  • data[].authentication
    object
  • total
    integerrequired
  • page
    integerrequired
  • per_page
    integerrequired

Errors

  • 400Invalid pagination
  • 401Unauthenticated
  • 403Scope or admin/tenant access denied
  • 404Missing or foreign record
  • 429Rate limited
  • 503Metadata 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"
GET /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.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    string (uuid)pathrequired
  • include
    stringquery
    Set to authentication to include safe persisted credential and refresh metadata. This does not verify provider authorization or token validity.

Response · 200 · object

  • id
    string (uuid)required
  • provider_label
    stringrequired
  • environment
    stringrequired
    One of: sandbox, production, unknown.
  • operational_status
    stringrequired
    One of: active, paused, revoked, unknown.
  • authorization
    stringrequired
  • setup_available
    booleanrequired
  • mutations_available
    booleanrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • authentication
    object
  • authentication.binding_status
    stringrequired
    One of: not_configured, recorded, mismatch.
  • authentication.credential_recorded
    booleanrequired
  • authentication.oauth_pending
    booleanrequired
  • authentication.refresh_state
    stringrequired
    One of: none, claimed, request_started, uncertain.
  • authentication.authorization
    stringrequired
  • authentication.token_expiry
    stringrequired
  • authentication.remote_revocation
    stringrequired
  • authentication.updated_at
    string (date-time) | nullrequired

Errors

  • 400Invalid pagination
  • 401Unauthenticated
  • 403Scope or admin/tenant access denied
  • 404Missing or foreign record
  • 429Rate limited
  • 503Metadata 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"
GET /rest/v1.0/companies/{company_id}/connectors/{id}/runs

List 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.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    string (uuid)pathrequired
  • page
    integerquery
  • per_page
    integerquery
  • include
    stringquery
    Set to authentication to include safe persisted credential and refresh metadata. This does not verify provider authorization or token validity.

Response · 200 · object

  • data
    object[]required
  • data[].id
    string (uuid)required
  • data[].status
    stringrequired
    One of: queued, running, paused, completed, cancelled, unknown.
  • data[].health
    stringrequired
    One of: error, partial, staged, queued, running, paused, cancelled, unknown.
  • data[].pages
    integerrequired
  • data[].staged_count
    integerrequired
  • data[].quarantine_count
    integerrequired
  • data[].error_code
    string | nullrequired
  • data[].adapter_version
    string | nullrequired
  • data[].source_api_version
    string | nullrequired
  • data[].authorization
    stringrequired
  • data[].coverage
    stringrequired
  • data[].lag_seconds
    nullrequired
  • data[].deprecation
    stringrequired
  • data[].domain_applied
    nullrequired
  • data[].created_at
    string (date-time)required
  • data[].updated_at
    string (date-time)required
  • data[].authentication
    object
  • total
    integerrequired
  • page
    integerrequired
  • per_page
    integerrequired
  • authentication
    object
  • authentication.binding_status
    stringrequired
    One of: not_configured, recorded, mismatch.
  • authentication.credential_recorded
    booleanrequired
  • authentication.oauth_pending
    booleanrequired
  • authentication.refresh_state
    stringrequired
    One of: none, claimed, request_started, uncertain.
  • authentication.authorization
    stringrequired
  • authentication.token_expiry
    stringrequired
  • authentication.remote_revocation
    stringrequired
  • authentication.updated_at
    string (date-time) | nullrequired

Errors

  • 400Invalid pagination
  • 401Unauthenticated
  • 403Scope or admin/tenant access denied
  • 404Missing or foreign record
  • 429Rate limited
  • 503Metadata 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"
GET /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.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    string (uuid)pathrequired
  • run_id
    string (uuid)pathrequired
  • include
    stringquery
    Set to authentication to include safe persisted credential and refresh metadata. This does not verify provider authorization or token validity.

Response · 200 · object

  • id
    string (uuid)required
  • status
    stringrequired
    One of: queued, running, paused, completed, cancelled, unknown.
  • health
    stringrequired
    One of: error, partial, staged, queued, running, paused, cancelled, unknown.
  • pages
    integerrequired
  • staged_count
    integerrequired
  • quarantine_count
    integerrequired
  • error_code
    string | nullrequired
  • adapter_version
    string | nullrequired
  • source_api_version
    string | nullrequired
  • authorization
    stringrequired
  • coverage
    stringrequired
  • lag_seconds
    nullrequired
  • deprecation
    stringrequired
  • domain_applied
    nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • authentication
    object
  • authentication.binding_status
    stringrequired
    One of: not_configured, recorded, mismatch.
  • authentication.credential_recorded
    booleanrequired
  • authentication.oauth_pending
    booleanrequired
  • authentication.refresh_state
    stringrequired
    One of: none, claimed, request_started, uncertain.
  • authentication.authorization
    stringrequired
  • authentication.token_expiry
    stringrequired
  • authentication.remote_revocation
    stringrequired
  • authentication.updated_at
    string (date-time) | nullrequired

Errors

  • 400Invalid pagination
  • 401Unauthenticated
  • 403Scope or admin/tenant access denied
  • 404Missing or foreign record
  • 429Rate limited
  • 503Metadata 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"

Ask the OS

Reading this page

Ask anything about this page. Answers use what you're reading as context.

Suggested

    AI · may be imperfect · sample data where shown

    Open file