LinkedIn (linkedin)

Category: io | Form: | Symbol: In

One LinkedIn account — find leads, connect, message, and post on behalf of the account holder

Represents a single LinkedIn account with a typed op surface (find-companies, find-people, fetch-profile, enrich-lead, visit-profile, draft/send-connection-request, draft/send-dm, list-inbox, draft/publish-post, list-feed). Identity is fixed per element (account_handle, owner_user_id); the executor that actually performs ops is swappable via spec.executor_policy — default mcp, with optional per-op overrides to browser or api. For mcp executor, configure spec.mcp.command/args/env_refs to point at a LinkedIn MCP server (forked from adhikasp/mcp-linkedin). For browser executor, configure spec.browser.browser_ref pointing at a tools/user-browser or tools/browser element with an authorized LinkedIn session. Write ops (send-, publish-) require prior approval via the sales-board approve-linkedin-touch flow — this element refuses to send drafts that haven’t been approved. Common mistake: mismatched executor and config (e.g. executor=mcp but spec.mcp is absent, or executor=browser but browser.browser_ref is unset).

Guide

One LinkedIn account — find leads, connect, message, and post on behalf of the account holder

What It Does

LinkedIn is an io connector element that represents a single LinkedIn account with a typed operation surface. One element equals one account: the identity (account_handle, owner_user_id) is fixed per element, while the executor that actually performs operations is swappable. It covers four phases of activity — discovery (search companies/people, fetch profiles, read feed/inbox), human-approved outreach (visit, connect, DM), posting & engagement (post, comment, react), and account diagnostics.

Operations are executor-agnostic. The LinkedInHandler dispatches each op to one of three executors selected by spec.executor_policy: mcp (default — a forked adhikasp/mcp-linkedin MCP server), browser (a tools/user-browser or tools/browser element holding an authorized session), or api (not implemented in MVP). The default applies to all ops, with optional per-op overrides (e.g. route write ops through the browser).

Write ops are gated. draft-* ops persist a draft and make no network call; an approval flow flips the draft to approved; only then will the matching send-* / publish-* op execute. Sending refuses unless the referenced draft is approved (LINKEDIN_DRAFT_NOT_APPROVED). Outbound activity is rate-limited per account via configurable spec.rate_limits, with counters kept in the per-circle social_call_log table.

Element Definition

Property	Value
Type	linkedin
Category	io
Form	atom
Handler	LinkedInHandler
Shell role	connector
Auth methods	bearer, none
Delivery mode	async (retry: exponential, max 2)
Streaming	not supported

Properties

Field	Type	Default	Description
account_handle	string	—	LinkedIn handle (slug from profile URL), e.g. iggy-lapalme. Required.
display_name	string	—	Human-readable account name (UI only, not sent to LinkedIn)
owner_user_id	string (uuid)	—	Triform user who owns the account and approves its writes. Required.
executor_policy.default	enum	mcp	Default executor: mcp, browser, or api
executor_policy.overrides	object	—	Per-op executor override (op name → executor)
mcp.mode	enum	dedicated	dedicated (one subprocess per element) or shared (one pod cluster-wide)
mcp.transport	enum	stdio	stdio spawns a local process; http/sse connect to a running server
mcp.command / mcp.args	string / array	—	Executable + args for stdio transport
mcp.url	string	—	Endpoint for http/sse transport
mcp.env_refs	object	—	Env var name → modifiers/variable slug for credentials
mcp.tools_allowlist	array	—	Optional restriction on which MCP tools the element may invoke
browser.browser_ref	string	—	tools/user-browser or tools/browser element slug
browser.mode	enum	user_browser	user_browser (Triform Connect) or headless (Browserless + cookies)
default_region_urn	string	—	LinkedIn geoUrn used as default region filter for searches
request_jitter_ms	array	[500, 2000]	Random delay range (min, max) between successive calls
rate_limits.calls_per_hour	integer	100	All calls combined per rolling hour (0 = unlimited)
rate_limits.calls_per_day	integer	500	All calls per rolling 24h
rate_limits.profile_visits_per_day	integer	80	Profile fetches (visit/fetch profile)
rate_limits.follows_per_day	integer	20	Connection requests
rate_limits.messages_per_day	integer	30	Direct messages

Runtime-written lifecycle fields (hidden from the UI): authenticated, auth_state, needs_reauth, last_error.

Ports

Output port schemas defined in contract.yaml:

• LinkedInPerson — canonical output of find-people / fetch-profile (required: profile_url, name)
• LinkedInCompany — output of find-companies (required: url, name)
• LinkedInTouchResult — result of a send-* write op (touch_id, kind, status, executor, external_id)

Capabilities

linkedin-discovery, linkedin-enrich, linkedin-connect, linkedin-dm, linkedin-publish, linkedin-inbox, executor-pluggable.

Attaches: rate-limit, auth-policy, evaluator. Uses: variable, user-browser, chromeless.

Error Codes

Code	Class	Retryable	Meaning
LINKEDIN_AUTH_FAILED	auth	no	Login failed — credentials invalid or account challenged
LINKEDIN_AUTH_EXPIRED	auth	no	Session expired — reload LinkedIn and re-authenticate
LINKEDIN_CAPTCHA_REQUIRED	auth	no	CAPTCHA / login challenge — owner must resolve in a real browser
LINKEDIN_SESSION_EXPIRED	auth	no	Authorized user-browser session expired
LINKEDIN_RATE_LIMITED	internal	yes	LinkedIn or the rate-limit modifier rejected the call
LINKEDIN_OP_NOT_ON_EXECUTOR	validation	no	Op not implemented by the selected executor
LINKEDIN_DRAFT_NOT_APPROVED	validation	no	Tried to send a draft that was not approved
LINKEDIN_MCP_UNREACHABLE	internal	yes	MCP server failed to start or is not responding
LINKEDIN_BROWSER_UNREACHABLE	internal	yes	Browser ref did not resolve or is disconnected
LINKEDIN_BROWSER_FETCH_UNREACHABLE	internal	yes	Triform Connect extension not detected / pod timed out
LINKEDIN_BROWSER_FETCH_STATUS	internal	no	LinkedIn returned a non-success HTTP status
LINKEDIN_PROFILE_NOT_FOUND	validation	no	Profile does not exist or is not visible to this account
LINKEDIN_BODY_TOO_LONG	validation	no	Text exceeds LinkedIn’s limit (connect-note 300, dm 8000, post 3000)

Operations

All op paths are invoked as POST /api/{circle}/{slug}/ops/{op} (except health, which is GET). Auth level is the per-op auth field from ops.yaml.

Discovery (read)

• find-companies — POST find-companies — Search LinkedIn for companies matching keywords (capped at limit, default 25). Returns LinkedInCompany records; persists nothing. Auth: read.
• find-people — POST find-people — Search for people by keywords, company_handle, job_titles, or region_urn (capped at limit, default 25). Returns LinkedInPerson records. Auth: read.
• fetch-profile — POST fetch-profile — Fetch a full LinkedInPerson for a single profile_url or handle. Auth: read.
• list-feed — POST list-feed — Read recent feed posts (limit default 10). Source for phase-4 engagement drafting. Auth: read.
• list-inbox — POST list-inbox — Read recent inbox threads (limit default 20). Used to detect replies. Auth: read.
• preview-search-url — POST preview-search-url — Dry-run a linkedin.com/search/... URL; returns {vertical, total, sample} with no storage. Skips per-result profile fetches. Auth: read.
• get-activity-stats — POST get-activity-stats — Usage + rate-limit counters for the account (current-period counters, configured caps, hourly/daily history). Pure read over social_call_log; consumes no rate budget. Auth: read.

Outreach (human-approved writes)

• visit-profile — POST visit-profile — Deliberate profile view (appears in “who viewed your profile”). Writes a touch with status=sent — visits do not require approval. Requires pursuit_id. Auth: write.
• draft-connection-request — POST draft-connection-request — Draft a connection request (optional note, max 300 chars). No network call. Requires pursuit_id, profile_url. Auth: write.
• send-connection-request — POST send-connection-request — Execute an approved connection-request draft (refuses unless the draft is approved). Requires draft_id. Rate-limited. Auth: write.
• draft-dm — POST draft-dm — Draft a direct message (body max 8000 chars). Recipient typically a 1st connection. Requires pursuit_id, profile_url, body. Auth: write.
• send-dm — POST send-dm — Execute an approved DM draft. Requires draft_id. Rate-limited. Auth: write.

Posting & engagement (draft / approve / publish)

• draft-post — POST draft-post — Draft a post (body max 3000 chars, optional attachment_refs by file element slug). Requires body. Auth: write.
• publish-post — POST publish-post — Publish an approved post draft. Requires draft_id. Rate-limited. Auth: write.
• draft-comment — POST draft-comment — Draft a comment on a post (body max 1250 chars). Requires target_urn, body. Auth: write.
• draft-reaction — POST draft-reaction — Draft a reaction (reaction_type: like, celebrate, support, love, insightful, funny). Requires target_urn, reaction_type. Auth: write.

Bulk ingest

• ingest-search-url — POST ingest-search-url — Scrape all results from a linkedin.com/search/... URL: people land as cards on a boards/sales-board (target_sales_board), companies as data/organizations (target_orgs); content/jobs returned inline. Paginates up to max_results (default 200, max 2000). Optional fetch_profiles enriches each row. Requires search_url. Auth: write.

Draft admin (platform-agnostic)

• approve-draft — POST approve-draft — Flip a draft from status=draft to status=approved (authorizes the send). Requires draft_id. Auth: write.
• list-drafts — POST list-drafts — List drafts for the element, optionally filtered by status (limit default 50). Auth: read.
• capture-cookies — POST capture-cookies — Capture the browser’s cookies for LinkedIn into a modifiers/variable (default name {element_slug}-cookies) and return the variable slug + env var name for wiring into spec.mcp.env_refs. Reads the live cookie jar synced by the Triform Connect extension; no client-side extraction. Auth: write.

Diagnostics

• health — GET health — Test whether the configured executor(s) can reach LinkedIn with the configured auth. Returns per-executor status (ready, challenged, expired, unreachable, not_configured). Drives the connector panel’s connection badge (polled every 300s). Auth: read.

Quick Start

Create a LinkedIn element with the MCP executor (the default), wiring credentials through a modifiers/variable:

{
  "account_handle": "iggy-lapalme",
  "owner_user_id": "<triform-user-uuid>",
  "executor_policy": { "default": "mcp" },
  "mcp": {
    "transport": "stdio",
    "command": "uvx",
    "args": ["mcp-linkedin"],
    "env_refs": { "LINKEDIN_COOKIE_JAR": "my-linkedin-cookies" }
  }
}

Find people at a company (read op):

POST /api/{circle}/{slug}/ops/find-people
{ "keywords": "platform engineer", "company_handle": "triform", "limit": 10 }

Draft, approve, then send a connection request (the approved-draft gate):

POST /api/{circle}/{slug}/ops/draft-connection-request
{ "pursuit_id": "<uuid>", "profile_url": "https://www.linkedin.com/in/jane-doe/", "note": "Hi Jane —" }

POST /api/{circle}/{slug}/ops/approve-draft
{ "draft_id": "<uuid-from-draft>" }

POST /api/{circle}/{slug}/ops/send-connection-request
{ "draft_id": "<uuid-from-draft>" }

Common Mistakes

• Mismatched executor and config. executor_policy.default = mcp requires mcp.transport (plus mcp.command/args for stdio, or mcp.url for http/sse); default = browser requires browser.browser_ref to point at a tools/user-browser or tools/browser element. The validation rules mcp_config_when_mcp_default and browser_config_when_browser_default reject the mismatch.
• Choosing the api executor. It requires LinkedIn partner approval and is not implemented in MVP — ops return LINKEDIN_OP_NOT_ON_EXECUTOR.
• Sending an unapproved draft. send-* / publish-* refuse unless the referenced draft has status=approved — fail with LINKEDIN_DRAFT_NOT_APPROVED. Run approve-draft first.
• Missing identity. account_handle and owner_user_id are both required (identity_required) — a LinkedIn element represents one specific account and attributes writes to its owner.
• Over-length bodies. Connect-note 300, DM 8000, post 3000, comment 1250 — exceeding the limit yields LINKEDIN_BODY_TOO_LONG.
• Pushing rate limits. Defaults are conservative observed-safe points; LinkedIn’s silent throttle kicks in around 500–1000 calls per cookie per day, and bumping caps too far risks cookie invalidation.

Relationships

• Attaches to: rate-limit, auth-policy, evaluator
• Uses: variable, user-browser, chromeless

Capabilities

• linkedin-discovery: Search companies and people on LinkedIn
• linkedin-enrich: Enrich a lead with LinkedIn profile data
• linkedin-connect: Send connection requests (gated by approval)
• linkedin-dm: Send direct messages (gated by approval)
• linkedin-publish: Publish posts, comments, reactions (gated by approval)
• linkedin-inbox: Read inbox and conversations
• executor-pluggable: Operations are transported via mcp, browser, or api — swappable per op

Properties

Property	Type	Default	Description
account_handle	string	—	LinkedIn handle (slug from profile URL), e.g. ‘iggy-lapalme’
display_name	string	—	Human-readable account name (shown in UI, not sent to LinkedIn)
owner_user_id	string	—	Triform user who owns this LinkedIn account and approves writes from it
executor_policy	object	—	How LinkedIn operations are transported to LinkedIn
mcp	object	—	MCP server transport configuration (used when executor=mcp)
browser	object	—	Browser transport configuration (used when executor=browser)
default_region_urn	string	—	LinkedIn geoUrn used as default region filter for searches (e.g. Sweden)
request_jitter_ms	array	[500,2000]	Random delay range (min, max) between successive LinkedIn calls, to avoid rhythmic patterns
rate_limits	object	—	Caps on outbound LinkedIn activity per account, per rolling period
authenticated	boolean	false	True when at least one configured executor reports status: ready from the health op. Writer: SocialMcpExecutor health handler.
auth_state	string	""	Worst-actionable lifecycle state across executors. expired / challenged / unreachable take priority over ready so the UI surfaces the reconnect signal.
needs_reauth	boolean	false	True when auth_state is expired or challenged — the UI uses this to show a Reconnect CTA on the connection badge.
last_error	object	—	Last operation error — { code, message }. Cleared on next successful op. Read by ConnectorPanel ErrorBanner via spec.last_error.

Operations

activity

Get /ops/activity | Auth: Read

Get activity events for this element

Scope depends on element capabilities: individual elements query by element_id, project-form elements with activity-scope-members include member activities, circle-level elements with activity-scope-all query the entire circle. Gracefully returns empty list if activities table is missing (old circles).

approve-draft

Post /ops/approve-draft | Auth: Write

Flip a draft from status=draft to status=approved (authorizes send)

attachments

Get /ops/attachments | Auth: Read

List all modifiers and resources attached to this element

Returns both modifiers (policy enforcement) and resources (data injection) with is_modifier flag to distinguish. Items in the generated MODIFIER_TYPES list are modifiers; everything else is a resource. Includes cascade_policy and version pin info.

batch_stats

Get /ops/batch_stats | Auth: Read

Get per-element statistics for all children of this element

Returns per-child stats plus an aggregate. Most meaningful on compound or manifest form elements (repositories, circles, projects); atoms have no children so the result is an empty children array with a zeroed aggregate. Uses efficient GROUP BY SQL. Weighted averages for eval scores.

capture-cookies

Post /ops/capture-cookies | Auth: Write

Capture the browser’s cookies for this platform into a variable — zero client-side work

Default flow (no input needed): reads the live cookie jar the Triform Connect extension already syncs into physics, filters to this platform’s domain, serializes as a JSON array, upserts a modifiers/variable named {element_slug}-cookies, and returns the variable_slug + env_var_name pair for wiring into spec.mcp.env_refs. ONE CLICK — no client-side extraction required. Optional overrides: cookie_jar (caller-supplied pre-extracted jar) and variable_slug (override the default name). Returns value_bytes, cookie_count, and source (bridge_registry or caller_supplied).

compose

Post /ops/compose | Auth: Execute

Batch add and remove modifiers on this element in a single call

Declarative composition: add modifiers by ref path (slug or path@version) and remove by attachment ID, all in one atomic call on the target element. Each ‘add’ entry resolves the source element, validates topology, attaches with optional priority and cascade policy. Each ‘remove’ entry deletes the attachment row. Returns a summary of what was added and removed. Example: compose({ add: [{ref: “my-prompt”}, {ref: “rate-limit/api@v2”, priority: 50}], remove: [{attachment_id: “uuid”}] })

context

Get /ops/context | Auth: Read

Get connected elements (graph traversal)

Graph traversal showing all connected elements with their relationship type (contains, contained_by, references, referenced_by, attaches, etc.). Use ?depth=N to control traversal depth (default 1) and ?types=actor,data to filter by element types.

create

Post /ops/create | Auth: Write

Create child element

POST to the parent path — element_type goes in the request body, NOT the URL. Both element_type and slug are required and must be non-empty. Name is derived from slug if omitted. Writes to both Git and PostgreSQL. All elements are stored flat under the circle — no intermediate library wrapper rows.

delete

Delete /ops/delete | Auth: Admin

Delete element (soft delete)

Soft delete — sets state to ‘deleted’ but retains the record. Cannot delete elements that have children (has_no_bond precondition) or active runs. Requires admin auth and confirmation.

disable

Post /ops/disable | Auth: Admin

Disable element (hides and prevents use)

Idempotent — safe to call on already-disabled elements. Optionally pass a reason string. Disabled elements cannot be invoked or executed. Inverse of enable.

draft-comment

Post /ops/draft-comment | Auth: Write

Draft a comment on a LinkedIn post (requires approval)

Writes a post_drafts row with kind=comment and target_urn set to the parent post. Body capped at 1250 chars per LinkedIn’s comment limit.

draft-connection-request

Post /ops/draft-connection-request | Auth: Write

Draft a LinkedIn connection request (requires approval to send)

Writes a row to pursuit_linkedin_touches with kind=connection_request, status=draft. Body is optional (a note with the request) and capped at 300 chars per LinkedIn’s limit. No network call to LinkedIn. Approval via the sales-board approve-linkedin-touch flow flips status to sent and triggers send-connection-request on this element.

draft-dm

Post /ops/draft-dm | Auth: Write

Draft a LinkedIn direct message (requires approval to send)

Writes pursuit_linkedin_touches row with kind=message, status=draft. Body capped at 8000 chars. The recipient must be reachable — typically a 1st connection; LinkedIn restricts DMs to non-connections in most cases.

draft-post

Post /ops/draft-post | Auth: Write

Draft a LinkedIn post (requires approval to publish)

Writes a row to the post_drafts table (separate from pursuit_linkedin_touches because posts are not pursuit-bound). Body capped at 3000 chars. Images and documents are attached by reference (file element slugs).

draft-reaction

Post /ops/draft-reaction | Auth: Write

Draft a reaction on a LinkedIn post (requires approval)

Writes a post_drafts row with kind=reaction and reaction_type (like, celebrate, support, love, insightful, funny). Short approval flow — a reaction is lighter weight than a comment.

enable

Post /ops/enable | Auth: Admin

Enable element (makes usable and visible)

Idempotent — safe to call on already-enabled elements. Transitions element to ready/enabled state. Cannot enable deleted elements. Inverse of disable.

export_bundle

Get /ops/export/bundle | Auth: Read

Export element as downloadable git bundle

On non-root-namespace elements, returns a binary git bundle. On root-namespace (circle) elements, dispatch hands off to the circle’s own export_bundle op, which returns a multi-element JSON envelope with one base64 bundle per child element — this is intentional, not an error.

fetch-profile

Post /ops/fetch-profile | Auth: Read

Fetch the structured profile of a single LinkedIn person

Given a profile URL or handle, returns a full LinkedInPerson record plus experience/education if the executor supports it. The MCP executor uses linkedin-api’s get_profile; the browser executor reads Voyager identity endpoints with DOM fallback. Does NOT persist.

find-companies

Post /ops/find-companies | Auth: Read

Search LinkedIn for companies matching a query

Returns structured LinkedInCompany records. Keyword search against LinkedIn’s company index. Results are capped at limit (default 25). Does NOT persist anything — callers decide whether to upsert into data/organizations. Note: region and size filters are not exposed by the MCP tool signature (search_companies accepts keywords + limit only); apply those filters client-side on the returned results or use ingest-search-url with a pre-filtered linkedin.com/search URL instead.

find-people

Post /ops/find-people | Auth: Read

Search LinkedIn for people matching criteria

Returns structured LinkedInPerson records. Can target a specific company (by handle or URL), keyword-search the whole graph, or filter by job title. Respects spec.default_region_urn. Results are capped at limit (default 25). Does NOT persist — callers typically feed results into ingest-search-url (which publishes cards on a sales-board).

get

Get /ops/get | Auth: Read

Get element details

Element is already resolved by the routing layer — this returns the cached element, not a fresh DB query. Use the path /api/{circle}/{slug} to address elements.

get-activity-stats

Post /ops/get-activity-stats | Auth: Read

Usage + rate-limit counters for this LinkedIn account — powers the activity dashboard

Pure read op over the per-circle social_call_log table — does NOT consume any rate budget. Returns the current-period counters (calls_last_hour, calls_today, profile_visits_today, follows_today, messages_today, posts_today), the configured spec.rate_limits caps, and two history series: hourly over the last 24 hours and daily over the last 30 days. The portal charts these as stacked-area activity graphs per element.

health

Get /ops/health | Auth: Read

Check executor reachability and session state

Tests whether the configured executor(s) can reach LinkedIn with the configured auth. Returns per-executor status (mcp, browser) with connected/challenged/expired state. Useful for the card-face indicator and for catching CAPTCHA-required states early.

import_bundle

Post /ops/import/bundle | Auth: Write

Import git bundle into element

Accepts a base64-encoded git bundle in the JSON bundle_base64 field. Use overwrite=true to replace existing elements with same slug (default skips duplicates). Imported elements get new UUIDs. Returns counts of imported/skipped elements and any errors.

ingest-search-url

Post /ops/ingest-search-url | Auth: Write

Scrape all results from a LinkedIn search URL — people land as cards on a sales-board, companies as Organizations

Paste a linkedin.com/search/results/{people|companies|content|jobs}/ URL from your browser, pre-filtered however you want. The op runs the search via Voyager, optionally enriches each result with a full profile/company fetch, and persists by vertical:

people → cards on the sales-board’s first column (target_sales_board) companies → data/organizations (target_orgs) content → returned inline, not stored jobs → returned inline, not stored

Idempotent on re-runs — orgs dedup on org_no/domain/name. People cards are not deduped at ingest (cards are per-pursuit; the inbox composer or research-prospect can resolve duplicates downstream). Pair with preview-search-url to gauge size before committing to a full ingest.

intention

Get /ops/intention | Auth: Read

Get element intention with full inheritance chain

Returns three levels: direct (this element’s intention), inherited (from category and root), and resolved (final merged intention). Useful for understanding an element’s purpose in context of its hierarchy.

list-drafts

Post /ops/list-drafts | Auth: Read

List drafts for this element (optionally filter by status)

list-feed

Post /ops/list-feed | Auth: Read

Read the account’s LinkedIn feed

Returns recent feed posts (by the network the account holder follows). Used in phase 4 as the source for engagement drafting (comment/react). Results are transient — nothing is persisted.

list-inbox

Post /ops/list-inbox | Auth: Read

Read recent LinkedIn inbox threads

Returns recent conversations. Used to detect replies and surface them on the sales-board (cards in the inbox column may carry a prospect_linkedin_url that links back to a thread). Does NOT persist. Note: the MCP get_conversations tool does not expose an unread_only filter; filter client-side on the returned threads if needed.

preview-search-url

Post /ops/preview-search-url | Auth: Read

Dry-run a LinkedIn search URL — returns vertical + count + sample, no storage

Powers the two-phase ingest UX: paste a linkedin.com/search/… URL, get back {vertical, total, sample} so the user sees how many results exist before committing to a full ingest + profile enrichment. Skips per-result profile fetches — cheap and fast. Works on all search verticals (people, companies, content, jobs). For unsupported verticals (currently content — linkedin-api doesn’t expose post search), returns supported: false with a note instead of failing.

promote

Post /ops/promote | Auth: Admin

Promote element configuration to a target environment

Only for manifest-form elements (projects). Environments advance: dev → demo → live. dev→demo requires member+ role, demo→live requires admin. Freezes member versions at promotion time (creates snapshot). Persists environment config to spec.environments.

publish-post

Post /ops/publish-post | Auth: Write

Publish an approved post draft

Refuses unless the draft row is approved. Publishes via the selected executor. Rate-limited. On success, records the LinkedIn post urn.

readme

Get /ops/readme | Auth: Read

Get element README.md content

Reads README.md from the element’s git repository. Returns empty content (not an error) if no README exists. Always returns markdown format.

readme_update

Post /ops/readme_update | Auth: Write

Update element README.md content

Creates or overwrites README.md in the element’s git repo. Commits to the draft branch. Content must be provided as a markdown string.

receive

Post /ops/receive | Auth: None

Receive incoming external traffic

Entry point for external traffic reaching this IO element. Declared auth: none to bypass platform auth — element-level auth is enforced by IoReceiveExecutor before dispatching into the flow graph. The flow/app that wires this element as an entry point determines what happens next.

remove-modifier

Post /ops/remove-modifier | Auth: Execute

Remove an attached modifier from this element by attachment ID

Removes a modifier/resource attachment by its row ID. The ID comes from the attachments or context API. This is the reverse of attach — called on the target element, not the source.

restore

Post /ops/restore | Auth: Admin

Restore element to a specific version

Automatically snapshots the current state before restoring (creates a ‘Before restore to vN’ version entry). Writes restored spec to git as .triform/spec.yaml. Git failures warn but don’t fail the operation — DB state is authoritative. Cannot restore deleted elements.

schema

Get /ops/schema | Auth: Read

Get element input/output schema (MCP tools/list compatible)

Returns type-level port schemas from the TypeRegistry — not instance-specific overrides. Includes direction (input/output), required flag, and JSON schema per port. Useful for understanding what data an element accepts and produces.

send

Post /ops/send | Auth: Execute

Send a message/request to external system

Explicitly sends payload to the configured external target. For HTTP elements, POSTs to the target URL. For chat platforms, sends via the platform API. Put data in the payload field. Returns send status and response details.

send-connection-request

Post /ops/send-connection-request | Auth: Write

Execute an approved connection-request draft

Refuses unless the referenced platform_drafts row has status=approved (i.e. was approved via approve-draft). Sends via the selected executor. On success, records external_id and sent_at. Rate-limited by the rate-limit modifier attached to this op.

send-dm

Post /ops/send-dm | Auth: Write

Execute an approved DM draft

Refuses unless the platform_drafts row is approved (approved via approve-draft). Sends via the selected executor. Rate-limited. On success, records LinkedIn message urn as external_id.

source

Get /ops/source | Auth: Read

Get any file’s content from the element’s git repository

Reads an arbitrary file from the element’s CAS-backed git tree by its relative path. Same store as readme, just generalized. Path safety: rejects .. traversal, leading /, and null bytes. Use this to view main.py for action elements, asset files for SPAs, etc. Returns empty content (not an error) if the file doesn’t exist.

source_branches

Get /ops/source/branches | Auth: Read

List Source branches for this element

Returns the standard draft/demo/live Source branches, their current commits, and promotion relationships. Use GET /api/{element_path}/ops/source/branches.

source_promote

Post /ops/source/promote | Auth: Write

Promote Source branch forward

Promotes draft to demo or demo to live through the generated element op path. Direct Git pushes to demo/live are blocked by Source policy.

source_repair

Post /ops/source/repair | Auth: Write

Inspect or repair the element Source index

Runs Source repair through the element operation path. Defaults to dry_run=true; set dry_run=false only after reviewing a dry-run report.

source_status

Get /ops/source/status | Auth: Read

Get Source control status for this element

Returns the branch-aware clone URL, checkout commands, current draft commit, child source-link count, portable export summary, Source health, warnings, and auth hints for the addressed element. Use the element-first path: GET /api/{element_path}/ops/source/status.

source_validate

Post /ops/source/validate | Auth: Read

Validate Source branch contents

Validates a Source branch before accepting local Git workflow changes or promotion. Defaults to branch=draft and rejects runtime data, generated output, secret material, and unreadable CAS refs.

stats

Get /ops/stats | Auth: Read

Get aggregate statistics for this element

Health status is computed: error if errors_per_day > 5 or success_rate < 0.8, warning if errors_per_day > 0 or success_rate < 0.95. Firing alerts escalate health to error/warning. Default period is ‘day’. Returns runs_per_day, success_rate, avg_duration_ms, and more.

test_connection

Post /ops/test-connection | Auth: Execute

Test connection configuration

Validates the element’s configuration locally without making an actual external connection. Checks that required credentials are set, URLs are valid, etc. Returns success boolean and error details. Safe to call repeatedly.

tree

Get /ops/tree | Auth: Read

Get the element’s position in the graph — ancestors, children, references, and subtree statistics

Uses per-circle ElementGraph cache for O(1) lookups. Returns ancestors (containment chain), children (direct), members (references), referenced_by (reverse refs), attachments, and subtree stats. Default depth is 3, max is 10. Pass ?include_metadata=true for name/state on each node.

update

Patch /ops/update | Auth: Write

Update element

Partial update — send only the fields you want to change. spec, name, and intention are all independently optional. spec MUST be a JSON object when present; deep-merged into the existing spec by default. Empty {"spec":{}} preserves existing spec content but still records a new version (no-op for content, not for version state). To clear/replace the entire spec wholesale send {"spec":{...},"deep":false}. List-typed spec fields use replace semantics (the patch list replaces the existing list, no array merging). Coordinates Git + DB writes. Slug cannot be changed after creation.

update_meta

Patch /ops/update_meta | Auth: Write

Update element metadata (lightweight merge — does NOT bump version or snapshot spec)

Shallow JSONB merge into element.meta. Top-level keys in the provided value replace existing meta values; other keys are preserved. Used for UI metadata like canvas positions, panel state, viewer preferences. Wire-shape op_name is update_meta (distinct from update) so SSE subscribers + the cache auto-invalidator can distinguish lightweight metadata changes from spec edits without inspecting the payload. The MutatingElementStore wrapper stamps this op_name on the lifecycle event emitted by update_element_meta storage calls.

version

Get /ops/version | Auth: Read

Get current version or full history

Returns current version by default. Pass ?history=true for full version history (up to ?limit=N, default 50). Versions are backed by the element_versions table. Every spec update creates a new version entry.

visit-profile

Post /ops/visit-profile | Auth: Write

Visit a LinkedIn profile (appears in ‘who viewed your profile’)

Performs a deliberate profile view as a low-pressure touch. Writes a row to pursuit_linkedin_touches with kind=visit, status=sent (visits do not require approval — the account holder explicitly requested the visit by invoking this op). Rate-limited to avoid looking like a crawler.

Error Codes

Code	Class	Retryable	Description
LINKEDIN_AUTH_FAILED	auth	no	LinkedIn login failed — env_refs credentials invalid or account challenged
LINKEDIN_AUTH_EXPIRED	auth	no	LinkedIn session expired — reload LinkedIn and re-authenticate
LINKEDIN_CAPTCHA_REQUIRED	auth	no	LinkedIn presented a CAPTCHA or login challenge — account owner must resolve in a real browser
LINKEDIN_SESSION_EXPIRED	auth	no	Authorized user-browser session expired — account owner must reconnect
LINKEDIN_RATE_LIMITED	internal	yes	LinkedIn or local rate-limit modifier rejected the call
LINKEDIN_OP_NOT_ON_EXECUTOR	validation	no	Requested op is not implemented by the selected executor (e.g. publish-post not on MCP yet)
LINKEDIN_DRAFT_NOT_APPROVED	validation	no	Attempted to send a draft that has not been approved via approve-linkedin-touch
LINKEDIN_MCP_UNREACHABLE	internal	yes	MCP server process failed to start or is not responding
LINKEDIN_BROWSER_UNREACHABLE	internal	yes	tools/user-browser or tools/browser ref did not resolve or is disconnected
LINKEDIN_BROWSER_FETCH_UNREACHABLE	internal	yes	Triform Connect extension not detected in this circle, or owning pod did not respond within timeout
LINKEDIN_BROWSER_FETCH_STATUS	internal	no	LinkedIn returned a non-success HTTP status — session may be expired
LINKEDIN_PROFILE_NOT_FOUND	validation	no	Requested LinkedIn profile does not exist or is not visible to this account
LINKEDIN_BODY_TOO_LONG	validation	no	Message or note exceeds LinkedIn’s char limit (connect-note 300, dm 8000, post 3000)