Supported API endpoints

Match your application’s requests to the endpoint and usage requirements below, then configure the provider rates and bounds. MarginCI measures supported calls; it does not change your application or SDK settings. Twilio outbound SMS is experimental and listed separately.

Endpoint overview

Every provider needs max_request_usd, a positive bound reserved before each billable request or batch. See the spend guard.

Each provider may set base_url and credential_env. The OpenAI-compatible, Firecrawl and Exa defaults are https://api.openai.com/v1, https://api.firecrawl.dev/v2 and https://api.exa.ai. Base URLs must not contain credentials, query strings or fragments. Set the same endpoint and model in your application, and provide credentials through its environment. Anthropic and Gemini defaults and required fields are in configuration; AWS Anthropic requires its native endpoint, and Pinecone requires a resolved index URL.

OpenAI-compatible completions

Configure the exact requested and returned model IDs and their rates. MarginCI does not look up model prices. Configured-rate costs are recorded as configured_marginal_rate.

For streams, request final usage data where the provider supports it and consume the entire response. Completion requires coherent final usage and a parsed terminal marker, or valid terminal usage followed by clean transport EOF for compatible providers that omit the marker. SDK iterator cleanup after a validated [DONE] is accepted; cleanup or usage alone is insufficient. MarginCI does not drain abandoned responses. Missing usage, contradictory counters, an unpriced response model, cache usage without a cache rate or an unfinished stream returns INCONCLUSIVE. Unpriced requested models are blocked before dispatch. Only absent, default or auto service tiers are supported. Paid tools and audio usage are unsupported.

SDKs must use supported global fetch or node:http/node:https transport. Custom Agent or node-fetch routing may require the SDK’s global-fetch option. Compatibility with the endpoint format does not establish support for every service, SDK or model.

Firecrawl batch scraping

Create the batch inside the attempt, then poll it until the final status and credit/page usage are available. Consume every observed response. Batch creation alone is incomplete measurement; status polls do not add duplicate cost.

Unknown batch IDs, decreasing or contradictory counts, a completed batch returning to an active state, unconsumed responses or unresolved jobs return INCONCLUSIVE. Webhooks and other endpoints are unsupported.

Exa search

Exa’s costDollars is a provider estimate, not an invoice charge. Enable it explicitly with allow_estimate: true, or set per_request_usd to use a configured rate. The configured rate takes precedence while the returned estimate remains in the evidence.

With a configured rate, costDollars may be absent. If returned, it must be valid and internally consistent; negative, null or contradictory values invalidate measurement even with a configured rate. Estimate mode requires costDollars. Additional endpoints and search modes are not covered automatically.

Anthropic Messages

Native text Messages: direct https://api.anthropic.com/v1/messages, or configured AWS native /anthropic/v1/messages on Bedrock runtime/Mantle. JSON and fully consumed SSE are admitted. No Converse/InvokeModel, batches, tools, media, beta features, paid search or nonstandard tiers. Output and optional thinking must be explicitly bounded; thinking tokens are already included in output usage.

Configuration requires platform: anthropic or amazon_bedrock, api_version: '2023-06-01', currency: USD, rate_source, max_request_usd and model entries. Each model needs input_per_million, output_per_million, max_input_tokens and explicit response_models aliases. Nonzero cache use requires cached_input_per_million, cache_write_5m_per_million and/or cache_write_1h_per_million as applicable. Freeze the platform/region/inference rate and admit only its flat input tier. AWS configuration includes inference_geo when required by the chosen route.

Configured USD = (input × input rate + output × output rate + cache read × read rate + 5m cache write × 5m rate + 1h cache write × 1h rate) / 1,000,000. Input, cache read and cache creation are disjoint; write-duration counters partition cache creation. Stream usage updates replace cumulative totals. Complete final usage, ordered content blocks, message_stop and clean HTTP EOF are required. Missing, contradictory or unsupported counters prevent a complete measurement.

Native Messages JSON/SSE and retries are fixture-tested. Live checks used Amazon Bedrock Runtime’s native Anthropic Messages API, in us-east-2, using us.anthropic.claude-haiku-4-5-20251001-v1:0. JSON and SSE usage matched independent arithmetic. Direct api.anthropic.com remains fixture-tested only; the attempted Mantle path returned 403. Nonzero cache and thinking evidence is synthetic, not live validation. Messages, AWS native Messages.

Gemini Developer API

Native https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent and :streamGenerateContent?alt=sse, text only and one candidate. No Vertex, Interactions, files, explicit cache creation/storage, tools, media or live sockets. Require bounded maxOutputTokens and either an explicit nonnegative thinking budget within it or supported MINIMAL thinking level; no dynamic/unbounded thinking. Prefer header x-goog-api-key.

The admitted request body is a narrow subset of Gemini’s API:

For example, a bounded nonstream text request may use generationConfig: { temperature: 0, maxOutputTokens: 32, thinkingConfig: { thinkingLevel: 'MINIMAL' } }. The same body shape applies to the completed SSE route with ?alt=sse. responseMimeType is not admitted in this private alpha. Other Gemini API fields are not automatically MarginCI-compatible because Google accepts them. MarginCI identifies unsupported request field paths and refuses certification before dispatch; it does not silently discard them. See configuration for model IDs, rates and request bounds.

Configuration requires api_version: v1beta, currency: USD, rate_source, max_request_usd and model entries with input/output rates per million, max_input_tokens, response_models and a cache rate for nonzero cached input. Only the configured flat text tier and standard service tier are admitted.

Configured USD = ((prompt − cached) × input rate + cached × cache rate + (candidates + thoughts) × output rate) / 1,000,000. Cached input overlaps prompt; thoughts are separate from visible candidate tokens. totalTokenCount must reconcile; it is not another charge. Cumulative stream snapshots replace earlier counts. Require a final candidate status or explicit blocked-output status, final usage and a fully completed SSE response. Safety-blocked output with explicit valid usage retains input cost; absent candidate usage is not zero.

Developer API JSON/SSE and retries are fixture-tested. Native Developer API JSON/SSE live requests on gemini-3.5-flash-lite, minimal thinking, each returned 4 prompt + 2 candidate = 6 total tokens; repeated streaming totals were counted once. Nonzero implicit cache/thinking is fixture evidence. Free allowances are not subtracted from the configured gross model. Generation API, pricing.

Pinecone serverless query

API 2026-07, POST /query at an explicitly configured resolved index host. Supplied dense vector, namespace, topK, metadata filter and include-values/metadata flags only. No discovery/control-plane calls inside measurement, writes, integrated embeddings, reranking, document search or dedicated read nodes. Prepare the index and resolve its host outside the measured operation.

Required config: base_url, api_version: '2026-07', index_type: serverless_on_demand, currency: USD, rate_source, read_units_per_million_usd, egress_per_gb_usd, egress_basis: identity_response_body_bytes, max_request_usd. USD = returned usage.readUnits × RU rate / 1,000,000 + captured identity JSON body bytes × egress rate / 1,000,000,000. RU can be fractional; result count and topK do not determine it. Missing/null usage, unknown charges, nonempty legacy results or compressed/incomplete/invalid UTF-8 bodies prevent a complete measurement.

The configured cost includes read units and the size of the uncompressed JSON response body, measured in bytes. It is not provider invoice reconstruction: a live response returned egressBytes: 44 while its JSON body was 143 bytes. The undocumented counter is retained separately and is not treated as equivalent to body bytes. Persistent storage, setup writes, subscriptions and account minimums are excluded; free allowances do not silently zero either modeled component.

Query fixtures cover a resolved host, identity encoding and SDK retry behavior. The live Starter test used one tiny owned index/vector and returned 1 RU with 143 body bytes. Its configured value matched independent arithmetic. Query reference, cost dimensions.

Provider testing

Controlled fixtures cover the six supported provider scopes, including incomplete and contradictory responses. Twilio is fixture-tested separately and remains experimental. Live checks cover only the paths described below and in each provider section. Use the acceptance record matching your delivered archive; historical requests do not validate a different package or runtime.

Earlier live checks covered one AWS OpenAI-compatible model (google.gemma-3-4b-it) using JSON and completed SSE with final usage, one Firecrawl v2 single-page batch through completion, and one Exa single-result search with a consistent estimate. These are historical observations, not a fresh test of your delivered package.

The historical compatible-provider checks described here did not separately validate direct api.openai.com. The AWS-hosted compatible checks do not certify every compatible model, nonzero cache/reasoning usage, nondefault tiers, larger Firecrawl outcomes or all Exa modes. The supported request and usage rules above still apply. No test establishes agreement with settled provider charges.

Experimental: Twilio outbound SMS

Implemented and tested with controlled fixtures and twilio@6.1.1; live evidence incomplete. Explicit experimental: true is required. This is excluded from the validated provider list. The tested contract is default-region Programmable Messaging API2010-04-01: form POST /Accounts/{account}/Messages.json with only E.164 From, To, and bounded Body, followed by GET of the exact Message SID created by the operation. Normal SDK default retries are off; keep autoRetry: false. Your application must read the message status within 12 reads and 120 seconds, and finish before its process exits. No callbacks, media, templates, scheduled sends, other channels, foreign IDs or arbitrary regions.

Required config: api_version: '2010-04-01', currency: USD, account_sid_env naming the configured account variable, credential_env naming the API secret, price_source: terminal_message_price, account_addons: none, experimental: true, and max_request_usd. Optional bounds: max_status_reads (1..12), observation_timeout_ms (100..120000). account_addons: none is an explicit account-scope assertion: verify it is true. Enabled or unknown separately billed add-ons, including Compliance Toolkit, are outside this contract; the adapter cannot inspect account settings.

Ownership, direction, SMS channel, segment count and ordered timestamps are validated before redaction. Require delivered or undelivered, non-null USD/usd price, final nonzero segments and a sent timestamp. Economic USD = −price, using the API’s negative charge-string convention; positive prices and other currencies are refused. The exact raw price is retained as provider_reported_charge. Repeated matching reads count once; changes to a settled observation invalidate the comparison. Queued/sending/sent or missing price remain pending. Provider failed is refused because separate failure-fee completeness is unverified. Application failure after a priced delivery still retains spending.

The Message price includes messaging and applicable carrier fees according to Twilio’s fee explanation; no duplicate carrier fee is added. It may arrive too late for the bounded operation. Persistent number rental, taxes, subscriptions and account commitments are excluded. This does not reconstruct later invoice adjustments.

Live SMS creation was not dispatched. The available 100-message trial uses preset template codes and trial-selected senders, outside the declared custom-Body/explicit-From path. A compatible account and bounded delivered/price evidence are required before calling this scope live-validated.

Provider status in reports

Saved JSON exposes providers[].support_status; Twilio is experimental. Default human output includes Twilio: EXPERIMENTAL (opted in; live verification incomplete). The same designation appears with PASS, FAIL and INCONCLUSIVE. Explicit opt-in remains mandatory. Experimental status is reported separately from cost measurement; it does not by itself make a result INCONCLUSIVE. Twilio remains outside the six validated provider scopes. The AWS-only Anthropic and other live-testing qualifications above remain in force.