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
200data 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).
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/
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)
Key
Required
Default
config
optional or conditional
none
execution_payload
optional or conditional
none
instance_id
optional or conditional
none
node_type
optional or conditional
none
space_id
optional or conditional
none
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
200data and meta envelope
{
"data": "..."
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
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)
Key
Required
Default
config
optional or conditional
none
force_refresh
optional or conditional
none
instance_id
optional or conditional
none
max_stale_seconds
optional or conditional
0
node_type
optional or conditional
none
space_id
optional or conditional
none
ttl_seconds
optional or conditional
300
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.
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)
Key
Required
Default
action
optional or conditional
none
config
optional or conditional
none
connector_slug
optional or conditional
none
description
optional or conditional
none
instance_id
optional or conditional
none
name
optional or conditional
none
paused
optional or conditional
none
secret_id
optional or conditional
none
space_id
optional or conditional
none
visibility
optional or conditional
none
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.
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/
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
Name
Default
category
none
connected_only
none
connector_slug
none
include_native
none
Responses
200data 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).
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)
Key
Required
Default
config
optional or conditional
none
current_value
optional or conditional
none
field
optional or conditional
none
force_refresh
optional or conditional
none
instance_id
optional or conditional
none
node_type
optional or conditional
none
search
optional or conditional
none
space_id
optional or conditional
none
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
200data and meta envelope
{
"data": "...",
"meta": "..."
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
We use strictly necessary cookies to run this site. With your permission we also use analytics cookies
(Google Analytics and our own visit tracking) to see which pages work. Read the
Cookie notice.