API URL Proxy

What the AI client sees

The AI client sees a single named MCP tool with a JSON Schema built from your request mappings. When the model invokes the tool, Vectoralix composes the HTTP request, makes it (under SSRF protection), optionally reshapes the response via mappings or post-processing JS, and returns the result.

The four building blocks

1. URL template + method — for example, https://api.example.com/v1/quotes/{symbol} with HTTP method GET. Curly-brace tokens are filled in from request mappings.
2. Request mappings — each input field has a name, type, location (url, query, or body), optional regex validation, and an optional default value. Mappings become the tool's JSON Schema for the AI client.
3. Headers — static or placeholder-interpolated header rows attached to every outbound request.
4. Response mappings — JSONPath-lite expressions that pull fields out of the API response into a structured output object.

Body template (POST/PUT/PATCH only)

For mutating verbs the configure page exposes a Body Template field that uses the same {token} placeholders as the URL. The Test API modal's body-diagnostics panel warns about three independent issues: a body template attached to a non-mutating method (GET/DELETE/HEAD/OPTIONS), an empty body_template on a mutating method that has body mappings, and unsubstituted {token} patterns left over after substitution.

Response mappings (JSONPath-lite)

Each response mapping has a JSONPath-lite expression and a target output field name. The expression supports dot-paths, array indices, wildcards, recursive descent, and an aggregation pipe.

Expression	Result
$.rates.USD	Single scalar
$.tickers[0].price	First array element
$.tickers[*].price	Array of values across all elements
$.tickers[*].price|sum	Numeric sum across the array
$..price	Recursive — every "price" field at any depth

OAuth credentials

OAuth credentials are first-class entities (api_oauth_credentials), reusable across multiple API URL tools. You define a credential once — name, base URL, client ID, client secret, transfer method (header or query), header name — and attach it to as many tools as you like. The client_secret is encrypted at rest and hidden from serialization.

• Transfer method "headers" sends the credential as an Authorization (or configurable) header.
• Transfer method "query" appends the credential as a query-string parameter. In Test API previews and the live URL preview, query-string credentials are masked — first 10 characters kept, then asterisks.
• Credentials are attached by reference, not copied. Edit the credential once and every tool that uses it picks up the new value immediately.

Post-processing (optional)

After response mappings produce a structured object, you can optionally run JavaScript to transform it before returning to the AI client. The JS runs in the same QuickJS sandbox as Code Execute tools, with the same wall-clock and memory caps. Use it for unit conversion, rounding, locale formatting, or assembling a string from multiple mapped fields.

Next-prompt template (optional)

You can attach a free-text template that the AI can read after a successful call to know what to do next. This is purely advisory — the model sees it as part of the tool result and decides whether to act on it.

A worked example

A get_stock_price tool that calls a public ticker API and returns the price for a single symbol.

• URL template: https://api.example.com/v1/quotes/{symbol}
• Method: GET
• Request mapping: symbol (string, location=url)
• Header: X-Api-Key with a static value, or sourced from an OAuth credential.
• Response mapping: $.tickers[0].price -> price
• Optional post-processing: round price to two decimal places before returning.

Safety and limits

• Every outbound URL passes through the SSRF validator before the request fires. Private and reserved IP ranges are blocked (except in dev).
• DNS is pinned via cURL RESOLVE so the resolved IP cannot change between validation and request (no TOCTOU).
• Redirects are disabled — every redirect must be expressed in the URL template explicitly.
• Response size is capped at 1 MB; the dashboard adds a 128 KB display cap, which does not apply to the live MCP call.
• OAuth client_secret is encrypted at rest and hidden from serialization. Query-string credentials are masked in dashboard previews.
• Errors are surfaced per pipeline stage (ssrf, http, post_processing) so you can see exactly where a call broke.

Persistence semantics

• On first visit, an empty api_tools row is created automatically (url_template='', method=GET, timeout_ms=30000, memory_limit_mb=128) so the relation managers have a parent to attach to.
• Header, request mapping, and response mapping rows save immediately on Save in the relation manager modal — there is no batched save.
• The page-level Save button persists only the top-level scalars: URL template, method, body template, post-processing code, timeouts, memory limit, and OAuth credential.
• A tool with empty url_template is skipped at MCP registration time, and its Test API action is hidden until you give it a non-empty template.