HTTP

Read HTTP APIs or send results to an endpoint with explicit requests. HTTP supports source and sink roles, with response/request media types determining whether data is JSON, CSV, a raw file, or a form.

Use the shared connection workflow to create this data source in your workspace. You can read this guide without an account or provider resources. Running examples requires your own non-production system and synthetic data.

Connection settings

Field	Required	Type	Default	Notes
base_url	yes	string (URI)	—	Base URL of the HTTP service; must be http or https
health_path	no	string	/	Relative path used for the connection test (GET request)
timeout_seconds	no	integer	5	Request timeout in seconds (1–300)
openapi_url	no	string (URI)	—	OpenAPI document URL used for schema import and operation browsing
openapi_fetch_timeout_seconds	no	integer	10	OpenAPI document fetch timeout in seconds (1–60)
allow_private_hosts	no	boolean	false	Requires private host access to be enabled for the deployment; hosted/default deployments reject true

Authentication and permissions

Field	Required	Notes
bearer_token	no	Added as Authorization: Bearer <token> header
username	no	HTTP Basic Auth username
password	no	HTTP Basic Auth password; required when username is set

Credentials belong in the connection, never in an operation statement. They are encrypted at rest and are not returned in API responses. Hosted/default deployments block loopback and private network endpoints; your laptop’s localhost is not the hosted worker’s network.

Use either bearer authentication or Basic authentication; leave credentials empty for a public endpoint. Do not put authentication tokens in operation examples or saved query parameters.

Test and discover

Connection testing sends GET to health_path relative to base_url. Choose a path that permits GET. Schema refresh imports the optional OpenAPI document; without openapi_url, an empty schema is expected. Imported operations can be browsed but do not automatically create saved queries.

Read example

Assume your endpoint exposes GET /customers?email=... and returns [{"email":"alex@example.com","name":"Alex"}]. Define a text email parameter with alex@example.com. The configured base URL supplies the host; this is an example endpoint contract, not a Braidplane-hosted demo API.

{
  "type": "http",
  "method": "GET",
  "path": "/customers",
  "query_params": {
    "email": "{{email}}"
  },
  "headers": {
    "Accept": "application/json"
  }
}

Write example

Save this operation for a pipeline sink whose destination accepts a JSON array. Upstream rows become the request body. Success and write semantics are defined by your endpoint; a POST is not automatically safe to replay.

{
  "type": "http",
  "method": "POST",
  "path": "/imports/customers",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": "{{input}}"
}

Operation reference

Field	Meaning
type	http
method	GET, POST, PUT, DELETE, PATCH, or HEAD
path	Endpoint path relative to the configured base URL
query_params	Query string values
headers	Non-secret request headers
body	JSON value or supported native input binding

Parameters can appear in the path, query parameters, headers, and body. For URL-encoded scalar forms use Content-Type: application/x-www-form-urlencoded; for multipart forms use multipart/form-data. Braidplane supplies the multipart boundary. Explicit null bodies are JSON-only.

Pipeline behavior

Use operation_type: http. JSON and CSV source responses retain their payload representations; other media types such as PDF or images can produce raw file payloads. HTTP also supports multipart form payloads. This does not mean every response can feed an SQL transform directly.

A sink with body: "{{input}}" can forward rows, JSON, CSV, files, or forms in the corresponding supported representation. Raw file output uses the file media type; explicit compatible headers can override the default.

Cursor checkpoints require an API that accepts a previous cursor and returns a next cursor. Bind {{runtime.incremental.lower_bound.cursor}} into the request and configure the response cursor path. One request does not automatically follow every page.

Limits and troubleshooting

• Requests, responses, time, redirects, and row counts are bounded.
• Retries default to one attempt. Where enabled, only idempotent methods retry transient network failures, HTTP 429, or 5xx responses; mutating methods do not retry automatically.
• A health test returning 405 usually needs a different GET-compatible path.
• Empty metadata without an OpenAPI URL is expected; failed imports require checking URL reachability and document validity.
• A 401/403 response calls for checking provider credentials and permissions.
• No automatic general pagination or spreadsheet parsing/export. Use a file connector when worksheet and range selection are required.

See operation and pipeline basics for where to use these statements, parameters, environment bindings, and replay safety. Return to the connector directory.