HTTP (http)

Category: io | Form: | Symbol: Ht

Connect flows to HTTP endpoints for receiving and sending requests

Unified HTTP connector — handles both exposed (server) and driven (client) roles depending on wiring topology. When wired as a flow source it listens on spec.path for spec.methods and emits request events. When wired as a flow sink it sends HTTP requests to spec.url with spec.method. HMAC is unified under spec.hmac: use spec.hmac.verify.* for inbound signature checking and spec.hmac.sign.* for outbound request signing. Supports bearer, api_key, basic, and none auth modes in both directions. Retry (spec.retry.) and CORS (spec.cors.) apply to their respective roles. The respond op sends a custom HTTP response back to an awaiting caller. The call op makes an ad-hoc outbound request at runtime.

Guide

Connect flows to HTTP endpoints for receiving and sending requests

What It Does

HTTP is a unified IO connector that can act as both a server (exposed) and a client (driven). In exposed mode, it registers a path on the platform and routes incoming HTTP requests to your flow. In driven mode, it sends HTTP requests to external endpoints. Which role is active depends on how the element is wired.

Element Definition

Property	Value
Type	http
Category	io
Form	atom

Key Properties

Field	Type	Default	Description
timeout_ms	integer	30000	Request/response timeout in milliseconds
headers	object	—	Static headers for all requests
path	string	—	URL path for exposed endpoints
methods	array	[POST]	Allowed HTTP methods (exposed mode)
url	string	—	Target URL (driven mode)
method	string	POST	HTTP method (driven mode)
auth_mode	string	none	Authentication: none, bearer, basic, api_key, hmac

Usage

Exposed (receive requests): Configure a path and wire to an action to handle incoming webhooks from external services.

Driven (send requests): Configure a url and method, then wire from an action or automation to call external APIs.

Request Body Encoding (body_encoding)

The call, invoke, request, and call_streaming ops accept a body_encoding field that controls how the request body is serialised on the wire:

Value	Body type	Wire format	Notes
json (default)	object	application/json	Standard JSON serialisation; Content-Type set automatically
form	flat object	application/x-www-form-urlencoded	Requires a flat object of scalar values — the shape most OAuth token endpoints expect
raw	string	verbatim bytes	Caller must set Content-Type explicitly via headers; use for pre-serialised JSON, XML, SOAP, signed JWT payloads, etc.

Example — raw XML / SOAP body:

{
  "url": "https://api.example.com/soap",
  "method": "POST",
  "body": "<soapenv:Envelope>...</soapenv:Envelope>",
  "body_encoding": "raw",
  "headers": { "Content-Type": "text/xml; charset=utf-8" }
}

Example — pre-serialised JWT bearer assertion (OAuth token endpoint):

{
  "url": "https://auth.example.com/token",
  "method": "POST",
  "body": "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=eyJ...",
  "body_encoding": "raw",
  "headers": { "Content-Type": "application/x-www-form-urlencoded" }
}

Note: body_encoding=form hard-errors on nested objects (use raw with a pre-serialised string instead). body_encoding=raw with a non-string body JSON-serialises it as a fallback — prefer passing an explicit string to avoid ambiguity.

Relationships

• Attaches to: rate-limit, auth-policy, validation, api-token, evaluator
• Uses: variable

Capabilities

• rest: RESTful endpoint handling (exposed)
• methods: All standard HTTP methods supported
• path-params: URL path parameter extraction (exposed)
• openapi: OpenAPI spec generation (exposed)
• async-http: Async HTTP client with configurable retry (driven)
• hmac-verify: HMAC signature verification on inbound requests (exposed)
• hmac-sign: HMAC request signing for outbound calls (driven)
• cors: CORS preflight handling (exposed)
• deduplication: Idempotency key deduplication on inbound (exposed)
• retry: Exponential backoff retry for outbound calls (driven)

Properties

Property	Type	Default	Description
timeout_ms	integer	30000	Request/response timeout in milliseconds
headers	object	—	Static headers applied to all requests (driven) or expected on all requests (exposed)
path	string	"/"	URL path pattern for the exposed endpoint (e.g., /api/users/:id)
methods	array	["GET","POST"]	Allowed HTTP methods (exposed role)
mode	string	"invoke"	invoke: Standard dispatch — emit event and return result. conversation: Conversational — manage guest sessions, route messages through conversation system, support WebSocket streaming.
cors	object	—	CORS configuration (exposed role)
request	object	—	Inbound request handling (exposed role)
deduplication	object	—	Deduplication of retried inbound deliveries (exposed role)
url	string	—	Full target URL for outbound requests (can include template variables). Used by call and send operations. If base_url is also set, url takes precedence. At call time, the url input parameter overrides this value.
base_url	string	—	Base URL prefix for outbound requests (e.g., ‘https://api.example.com/v1’). Combined with path at call time. Use url for full static URLs, or base_url when you want to vary the path per call.
target_ref	string	—	Reference to another element whose URL is used as the target. Takes precedence over url/base_url when set. Useful for wiring HTTP elements to dynamic targets.
method	string	"POST"	HTTP method for outbound requests (driven role)
body	object	—	Request body configuration (driven role)
retry	object	—	Retry configuration for outbound requests (driven role)
auth	object	—	Authentication configuration (exposed: enforced on inbound; driven: sent on outbound)
hmac	object	—	HMAC signature configuration — verify for inbound, sign for outbound

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

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.

call

Post /ops/call | Auth: Execute

Make an outbound HTTP request (driven role)

Makes an HTTP request with spec.method. URL resolution precedence: (1) input url override, (2) spec.target_ref resolved URL, (3) spec.url, (4) spec.base_url + path. Applies spec.auth credentials and spec.hmac.sign signing if configured. Retries on transient failures per spec.retry. Returns the response body and status code. Also available as “invoke” — both names route to the same handler. Use body_encoding to control how the request body is serialised: “json” (default) sends as application/json, “form” sends as application/x-www-form-urlencoded (required by most OAuth token endpoints), “raw” forwards the body verbatim and the caller is responsible for the Content-Type header.

call_streaming

Post /ops/call-streaming | Auth: Execute

Make a streaming outbound HTTP call and pump chunks to a pubsub channel (driven role)

Like call but does not buffer the response body. Issues an HTTP request with Accept: text/event-stream (overridable via input.headers), reads the response stream chunk-by-chunk, and publishes each chunk to the pubsub channel named in input.target_channel. Returns immediately with {stream: <target_channel>, status, headers} once the upstream sends response headers. Background pump emits one envelope per SSE event {event: "chunk", data: "<raw-bytes>"} and a terminal {event: "done", _terminal: true} when the upstream closes. Use this when wiring an Anthropic / OpenAI / SSE-style upstream through a flow whose response is consumed by io/http’s receive_stream op.

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.

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.

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.

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.

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.

invoke

Post /ops/call | Auth: Execute

Make an outbound HTTP request (alias for call)

Alias for the “call” operation. Makes an HTTP request with spec.method. This operation exists for consistency with other element types that use “invoke” as their primary execution operation. See “call” for full documentation.

oauth_authorize

Post /ops/oauth_authorize | Auth: Write

Generate an OAuth2 consent URL for this HTTP connector

Uses spec.auth.oauth or a referenced oauth-client profile to build an authorization-code consent URL. The redirect_uri defaults to the stable platform connector callback /api/oauth/connect/callback when no override is configured. The returned state is signed and routes the callback back to this element.

oauth_callback

Get /ops/oauth_callback | Auth: None

Exchange an OAuth2 authorization code and store the connector grant encrypted

Normally called by the platform stable callback route after verifying the signed state. Direct calls are useful for tests and local providers. Stores the resulting access/refresh token pair on this element under provider_key.

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.

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 an incoming HTTP request (exposed role)

Entry point for external HTTP traffic. Platform auth is bypassed (auth: none) — element-level auth from spec.auth is enforced instead. When spec.hmac.verify.enabled is true, the request body is verified against the HMAC signature in spec.hmac.verify.header before forwarding. Emits the request event into the connected flow. Returns the flow’s response or a 202 when no response is awaited.

receive_stream

Post /ops/receive-stream | Auth: None

POST a streaming HTTP request, get an SSE response (exposed role)

Streaming SSE entry-point. Client POSTs a request body; the handler reads the inbound element’s spec.target_ref flow, dispatches it with a per-request _stream_channel UUID injected into the flow’s input, and returns an SSE stream that reads chunks the flow’s outbound call_streaming op publishes to that channel. Designed for transparent SSE pass-through (Anthropic-style streaming LLM proxies). Platform auth is bypassed (auth: none) — element-level auth from spec.auth is enforced inside the handler. The stream terminates when a chunk carries _terminal: true or event: "done", when the publisher closes, or when the idle timeout (5 min) fires.

regenerate_secret

Post /ops/regenerate-secret | Auth: Admin

Rotate the HMAC verification secret (exposed role)

Generates a new HMAC verification secret and returns it (shown once — store immediately). The old secret is invalidated immediately. Update the external service’s webhook config with the new secret. Requires admin auth.

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.

request

Post /ops/call | Auth: Execute

Make an outbound HTTP request (canonical alias: call)

Alias for call and invoke — all three names POST to the same handler and accept the same payload. request is the REST-conventional name and matches what most HTTP clients call this verb.

respond

Post /ops/respond | Auth: Execute

Send a custom HTTP response back to an awaiting caller (exposed role)

Sends a custom HTTP response to the caller that triggered a receive. Set status (HTTP status code) and body (JSON object). Use when the connected flow element needs to control the response rather than returning its result directly.

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.

retry_delivery

Post /ops/retry-delivery | Auth: Execute

Retry a failed outbound delivery (driven role)

Re-attempts delivery to spec.url. Provide delivery_id to identify which prior attempt to retry, or omit to trigger a fresh delivery with an optional payload override.

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 webhook POST to a target URL (driven role)

POSTs payload as JSON to spec.url with HMAC signing if spec.hmac.sign.enabled is true. Returns delivered boolean, HTTP status code, and delivery metadata. Retries per spec.retry. Common mistake: omitting spec.url — send fails with URL not configured.

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 HTTP element configuration

Validates the element’s HTTP configuration locally. Checks that a URL is configured (url, base_url, or target_url), auth credentials are present if required, and HMAC signing config is valid. Returns connected boolean and details. Does NOT make an actual outbound request — use call for that.

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.

webhook_url

Get /ops/webhook-url | Auth: Read

Get the receive URL and HMAC secret hint for this element (exposed role)

Returns the full URL for receiving inbound HTTP requests and, when hmac.verify.enabled is true, the last 4 characters of the verification secret as secret_hint. Use when configuring an external service to point at this element.

Error Codes

Code	Class	Retryable	Description
HTTP_VALIDATION_FAILED	validation	no	Request validation failed
HTTP_RATE_LIMITED	limit	yes	Rate limit exceeded
HTTP_UNAUTHORIZED	auth	no	Authentication failed
HTTP_SIGNATURE_INVALID	auth	no	HMAC signature verification failed
HTTP_TIMEOUT	timeout	yes	HTTP request timed out (driven)
HTTP_CONNECTION_FAILED	internal	yes	Connection to target URL failed (driven)
HTTP_RETRY_EXHAUSTED	internal	no	All retry attempts exhausted (driven)
HTTP_INVALID_URL	validation	no	Target URL is invalid (driven)