HTTP Source

Use the HTTP adapter when the trusted system already exposes a restricted read API or when direct database access is inappropriate.

Source configuration

sources:
  billing-read-api:
    adapter: http
    base_url: https://billing.internal
    headers:
      Authorization: Bearer ${env:BILLING_API_TOKEN}
      Accept: application/json
    timeout: 5

Field	Default	Description
base_url	—	Required complete http:// or https:// URL in Console-managed configuration.
headers	{}	Static request headers with locally resolved secret references.
timeout	5	Request timeout in seconds.

The Console rejects a literal Authorization secret. Put the credential in the agent process environment.

Rule check

ground:
  checks:
    - source: billing-read-api
      method: GET
      path: /orders/{value}?workspace={workspace_id}
      select: data.order
      match:
        - column: customer_id
          ctx: customer_id
        - column: status
          value: delivered

Field	Default	Description
method	GET	GET or POST.
path	—	Path appended to base_url; supports {value}, tool-argument, and trusted-context placeholders.
select	empty	Dot path into a wrapped JSON object, such as data.order.
match	existence	Shared field and result-count conditions.

An unknown placeholder fails the check as a Source error rather than sending a partially formatted request.

The current adapter sends no request body. A POST verification call must express its input through the URL and must be implemented as a side-effect-free read endpoint. Prefer GET when possible.

Response semantics

• 404 becomes zero results and can satisfy an absence check.
• Other 4xx and 5xx responses are Source errors and use retry.on_error.
• A JSON object is one result unless it is empty.
• A JSON list contributes its full length and its first object as the candidate record.
• A selected null value is zero results.
• A non-JSON non-empty body is one result with no fields for field matching.

select follows dot-separated object keys. Shape the API response so the selected value is one object or a list of objects.

Security guidance

The HTTP adapter cannot prove that an endpoint is read-only. Protect the boundary with:

• a credential that can access only verification endpoints;
• server-side authorization scoped to the agent’s workspace or environment;
• network policy limiting reachable hosts;
• idempotent, side-effect-free endpoint implementations;
• bounded response sizes and timeouts.

Do not point an HTTP Source at a general-purpose application API using a broad writer token.