Menu
GET connectors/v1/available/ Service tier

GET available/: the connector catalog, flagged with the org's state.

Registry data is org-independent; when org context is present each entry also carries connected so a consumer can render connect-vs-use UI without a second call.

URL

  • Service tierhttps://automations.mattering.io/api/internal/connectors/v1/available/

Responses

200 data and meta envelope

{
  "data": "...",
  "meta": {
    "total": 0
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Example

curl -X GET "https://automations.mattering.io/api/internal/connectors/v1/available/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com"

Source: AutomationsCore/connectors_api_views.py (connectors_api_views.available)

GET connectors/v1/credentials/ Service tier

GET credentials/: the credentials this person may attach to a connection.

Query: connector (a slug: only credentials of the type it takes), space_id (a workspace: its own plus shared ones), limit (default 50, max 200), offset. A credential is listed when the person sees it on the Secrets page AND holds a use grant on it (connector_manage. attachable_secrets). Rows carry names, types and dates only; values and field contents never leave the secret store.

This read is not paginated. It returns at most 64 rows and does not report a total, so a result of exactly 64 may be truncated.

URL

  • Service tierhttps://automations.mattering.io/api/internal/connectors/v1/credentials/

Query parameters

NameDefault
connectornone
space_idnone

Responses

200 data and meta envelope

{
  "data": [
    {
      "id": "...",
      "name": "...",
      "credential_type": "...",
      "credential_label": "...",
      "fits_connectors": "...",
      "fits_connector_count": 0,
      "added_by_you": true,
      "added_by": "you",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z",
      "used_by_connections": "...",
      "fits": true
    }
  ],
  "meta": {
    "total": 0,
    "limit": 0,
    "offset": 0,
    "returned": 0,
    "has_more": true
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
404unknown_connector

Example

curl -X GET "https://automations.mattering.io/api/internal/connectors/v1/credentials/?connector=...&space_id=..." \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com"

Source: AutomationsCore/connectors_api_views.py (connectors_api_views.credentials)

POST connectors/v1/execute/ Service tier

POST execute/: run one connector/node operation for the acting user.

Body: {node_type, config, space_id?, instance_id?}. Secret markers in config resolve inside this service against the actor's grants; raw values never appear in the response. Long-running worker nodes are subject to the sync dispatch budget (570s): callers should honor the platform timeout ladder or use the nodes' async_mode where offered.

instance_id pins which of the org's connections for this connector runs the operation (ids from GET instances/). Without it the platform picks : space-scoped, then org-wide, then most-recently-updated: which is fine for an org with one connection and arbitrary for an org with two.

URL

  • Service tierhttps://automations.mattering.io/api/internal/connectors/v1/execute/

Body keys (JSON)

KeyRequiredDefault
configoptional or conditionalnone
execution_payloadoptional or conditionalnone
instance_idoptional or conditionalnone
node_typeoptional or conditionalnone
space_idoptional or conditionalnone

Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.

Responses

200 data and meta envelope

{
  "data": "..."
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400execution_rejected
400invalid_instance_pin
400missing_node_type
400missing_org_context
403connector_not_available
403unknown_actor
404unknown_node_type

Example

curl -X POST "https://automations.mattering.io/api/internal/connectors/v1/execute/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com" \
  -H "Content-Type: application/json" \
  -d '{
  "config": "...",
  "execution_payload": "...",
  "instance_id": "...",
  "node_type": "...",
  "space_id": "..."
}'

Source: AutomationsCore/connectors_api_views.py (connectors_api_views.execute)

POST connectors/v1/fetch/ Service tier

POST fetch/: cached read for surfaces that re-render.

Body: {node_type, config, space_id?, instance_id?, ttl_seconds?, max_stale_seconds?, force_refresh?}. Returns {data, fetched_at, stale, age_seconds, cached}.

instance_id pins which of the org's connections serves the read (from GET instances/). A surface that TELLS a viewer whose connection it is looking through must pin, or the claim is only true while the org has one connection. An unusable pin is a 400, never a quiet swap.

Semantics:
  - fresh (age < ttl)                        returns cached payload, stale=false
  - stale but within max_stale_seconds       returns cached payload, stale=true
    (opt-in only; the caller is telling us it wants instant paint and will
    trigger its own refresh: this service has no task queue, so nothing
    revalidates in the background)
  - otherwise, or force_refresh              returns live execution, then cache

A widget wired to execute/ instead of fetch/ is a rate-limit and billing defect, not a style preference.

URL

  • Service tierhttps://automations.mattering.io/api/internal/connectors/v1/fetch/

Body keys (JSON)

KeyRequiredDefault
configoptional or conditionalnone
force_refreshoptional or conditionalnone
instance_idoptional or conditionalnone
max_stale_secondsoptional or conditional0
node_typeoptional or conditionalnone
space_idoptional or conditionalnone
ttl_secondsoptional or conditional300

Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.

Responses

200 data and meta envelope

{
  "data": {
    "...": "..."
  },
  "meta": {
    "...": "..."
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400bad_request
400execution_rejected
400missing_node_type
400missing_org_context
403unknown_actor
404unknown_node_type

Example

curl -X POST "https://automations.mattering.io/api/internal/connectors/v1/fetch/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com" \
  -H "Content-Type: application/json" \
  -d '{
  "config": "...",
  "force_refresh": "...",
  "instance_id": "...",
  "max_stale_seconds": 0,
  "node_type": "...",
  "space_id": "...",
  "ttl_seconds": 300
}'

Source: AutomationsCore/connectors_api_views.py (connectors_api_views.fetch)

GET connectors/v1/instances/ Service tier

GET instances/: the org's connector instances (no secret material).

URL

  • Service tierhttps://automations.mattering.io/api/internal/connectors/v1/instances/

Responses

200 data and meta envelope

{
  "data": [
    {
      "id": "...",
      "connector_slug": "...",
      "name": "...",
      "status": "...",
      "space_id": "...",
      "last_auth_test_ok": "...",
      "last_auth_test_at": "2026-01-01T00:00:00Z",
      "created_at": "2026-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "total": 0
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400missing_org_context

Example

curl -X GET "https://automations.mattering.io/api/internal/connectors/v1/instances/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com"

Source: AutomationsCore/connectors_api_views.py (connectors_api_views.instances)

POST connectors/v1/instances/manage/ Service tier

POST instances/manage/: create or change a connection AS the person.

Body ``{action: "create", connector_slug, name?, description?, secret_id?, visibility?, config?, space_id?}: a new connection. visibility`` defaults to me (an agent acts for one person); org only when they asked for the whole organization. Without secret_id the connection is created waiting for a credential the person adds in its setup.

Body ``{action: "update", instance_id, name?, description?, visibility?, secret_id?, paused?, config?}``: change a connection this person can see. A visibility change is the connection owner's alone. There is no delete here: removing a connection stays in the Connectors page.

Enforced: same organization; the credential is one this person may attach (visible on the Secrets page and a use grant) and of the type the connector takes; the plan cap on connected accounts; names unique per connector (409 against a connection they can see, a free variant against hidden ones); no credential-shaped name, description or option. When a credential is attached and the connector has an auth test, it runs as this person. Returns the connection's summary, never secret material.

This read is not paginated. It returns at most 64 rows and does not report a total, so a result of exactly 64 may be truncated.

URL

  • Service tierhttps://automations.mattering.io/api/internal/connectors/v1/instances/manage/

Body keys (JSON)

KeyRequiredDefault
actionoptional or conditionalnone
configoptional or conditionalnone
connector_slugoptional or conditionalnone
descriptionoptional or conditionalnone
instance_idoptional or conditionalnone
nameoptional or conditionalnone
pausedoptional or conditionalnone
secret_idoptional or conditionalnone
space_idoptional or conditionalnone
visibilityoptional or conditionalnone

Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.

Responses

200 data and meta envelope

{
  "data": {
    "id": "...",
    "connector_slug": "...",
    "display_name": "...",
    "name": "...",
    "description": "...",
    "status": "...",
    "visibility": "...",
    "is_usable": true,
    "has_credential": true,
    "last_test_ok": "...",
    "last_test_at": "2026-01-01T00:00:00Z",
    "test_detail": "...",
    "yours": true,
    "credential_id": "...",
    "credential_name": "..."
  },
  "meta": {
    "updated": true,
    "renamed": false,
    "tested": true
  }
}

201 data and meta envelope

{
  "data": {
    "id": "...",
    "connector_slug": "...",
    "display_name": "...",
    "name": "...",
    "description": "...",
    "status": "...",
    "visibility": "...",
    "is_usable": true,
    "has_credential": true,
    "last_test_ok": "...",
    "last_test_at": "2026-01-01T00:00:00Z",
    "test_detail": "...",
    "yours": true,
    "credential_id": "...",
    "credential_name": "..."
  },
  "meta": {
    "created": true,
    "renamed": "...",
    "tested": true
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400invalid_action

Example

curl -X POST "https://automations.mattering.io/api/internal/connectors/v1/instances/manage/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "...",
  "config": "...",
  "connector_slug": "...",
  "description": "...",
  "instance_id": "...",
  "name": "...",
  "paused": "...",
  "secret_id": "..."
}'

Source: AutomationsCore/connectors_api_views.py (connectors_api_views.manage_instance)

POST connectors/v1/instances/{instance_id}/disconnect/ Service tier

POST instances/<id>/disconnect/: end a connection for good.

For the apps whose own disconnect flow ends a connection they made through the OAuth door (Sales mailbox, Calendar, Agents email account): revokes the token at the provider (Google: only for the last live connection of that Google account on that OAuth client, the shared-grant rule in connector_disconnect), destroys the stored secret, marks the connection deleted. Fail-soft on the provider and Secret Manager; the outcomes come back in data.

Auth: X-Internal-Secret is REQUIRED here (a signed-in browser session is not enough, unlike the rest of /api/internal/), plus X-Internal-Org-Id and X-Internal-User-Email. An "Only me" connection is disconnected only as the person who made it. Optional body {connector_slug}: refused with 409 when the connection is another connector's (a stale id pointing somewhere unexpected).

Answers ``{data: {id, connector_slug, status, revoke, secret, already_disconnected}, meta: {}}``. Repeating the call is a no-op.

This read is not paginated. It returns at most 64 rows and does not report a total, so a result of exactly 64 may be truncated.

URL

  • Service tierhttps://automations.mattering.io/api/internal/connectors/v1/instances/{instance_id}/disconnect/

Path parameters

NameType
instance_iduuid

Responses

200 data and meta envelope

{
  "data": "...",
  "meta": {
    "app": "automations"
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400missing_org_context
401unauthorized
403not_owner
404not_found
409connector_mismatch

Example

curl -X POST "https://automations.mattering.io/api/internal/connectors/v1/instances/INSTANCE_ID/disconnect/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com"

Source: AutomationsCore/connectors_api_views.py (connectors_api_views.disconnect_instance)

POST connectors/v1/instances/{instance_id}/test/ Service tier

POST instances/<id>/test/: re-run the connector's auth test.

Delegates to the connectors UI test view (same persistence of last_auth_test_* and status flips), re-wrapped in the v1 envelope.

URL

  • Service tierhttps://automations.mattering.io/api/internal/connectors/v1/instances/{instance_id}/test/

Path parameters

NameType
instance_iduuid

Responses

200 data and meta envelope

{
  "data": "..."
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
502test_failed

Example

curl -X POST "https://automations.mattering.io/api/internal/connectors/v1/instances/INSTANCE_ID/test/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com"

Source: AutomationsCore/connectors_api_views.py (connectors_api_views.test_instance)

GET connectors/v1/nodes/ Service tier

GET nodes/: node schemas, so consumers render config forms generically.

Without this, an app that wants a user to configure a connector-backed surface has to hardcode node parameters or reach into the automations registry it cannot see. Each entry carries the same config_schema the automations canvas builds its config panel from, plus sample_output for cold-start output paths: the schema IS the config UI.

**Reads only, by default.** category defaults to query; pass category=action for write nodes or category=all for both. This default is a safety property, not a convenience. Consumers pick a node from this list and then RE-RUN it: a dataset refreshes on a schedule, a widget re-renders per viewer: so an action node reached through a read-shaped surface executes repeatedly. Analytics shipped offering "GSC Delete Site" as a dataset source, which on a refresh schedule deletes a property over and over. Every consumer would have to remember to filter; defaulting to reads means only the surfaces that genuinely write (a Forms submission action) have to say so explicitly.

Filters: connector_slug (one connector's nodes), connected_only=1 (only nodes whose connector the org has active; nodes with no connector always pass). Native/productivity nodes are excluded by default because consumers of this surface are asking about connector capability; pass include_native=1 for the full registry.

URL

  • Service tierhttps://automations.mattering.io/api/internal/connectors/v1/nodes/

Query parameters

NameDefault
categorynone
connected_onlynone
connector_slugnone
include_nativenone

Responses

200 data and meta envelope

{
  "data": [],
  "meta": {
    "total": 0
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400bad_request
400missing_org_context

Example

curl -X GET "https://automations.mattering.io/api/internal/connectors/v1/nodes/?category=...&connected_only=...&connector_slug=..." \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com"

Source: AutomationsCore/connectors_api_views.py (connectors_api_views.nodes)

POST connectors/v1/options/ Service tier

POST options/: populate one config field's choices from live data.

Body: {node_type, field, config?, search?, space_id?, instance_id?}. config is the partially-filled form, which dependent pickers read (choose a base, then that base's tables). instance_id pins which connection the choices are read from.

This is what turns "Base id (starts with 'app') ... get it from Airtable: List Bases" from an instruction the user has to follow by hand into a dropdown. Fields without an options_source stay free text, so the same config panel renders both without branching.

URL

  • Service tierhttps://automations.mattering.io/api/internal/connectors/v1/options/

Body keys (JSON)

KeyRequiredDefault
configoptional or conditionalnone
current_valueoptional or conditionalnone
fieldoptional or conditionalnone
force_refreshoptional or conditionalnone
instance_idoptional or conditionalnone
node_typeoptional or conditionalnone
searchoptional or conditionalnone
space_idoptional or conditionalnone

Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.

Responses

200 data and meta envelope

{
  "data": "...",
  "meta": "..."
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400bad_request
400missing_org_context
400options_unavailable
403unknown_actor

Example

curl -X POST "https://automations.mattering.io/api/internal/connectors/v1/options/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com" \
  -H "Content-Type: application/json" \
  -d '{
  "config": "...",
  "current_value": "...",
  "field": "...",
  "force_refresh": "...",
  "instance_id": "...",
  "node_type": "...",
  "search": "...",
  "space_id": "..."
}'

Source: AutomationsCore/connectors_api_views.py (connectors_api_views.options)

All Automations resources
Start Free Explore our Products