BLAZINGFAST — INTEGRATION WORKFLOWS
Reviewed: 7 October 2026.
Production release: SDK/CLI 0.1.17; contract 2026-10-07.1. Check GET /v1/version and GET /v1/capabilities before using optional workflow features. Strict response validation is enforced.
API: https://api.blazingfast.io (configure the origin without /v1).
Downloads: https://docs.blazingfast.io/sdk; verify SHA256SUMS.
Guide: https://docs.blazingfast.io/api/integration-guide
Reference: https://docs.blazingfast.io/api/reference

CLI AND MCP
Use bf for new integrations. bf-api is an actively supported alias of the same
CLI in the Python SDK; it is not a separate lower-level interface.
Read first: bf version; bf capabilities; bf regions; bf billing balance.
Hosted MCP: https://mcp.blazingfast.io/mcp, OAuth, selected scopes and policy.
Local MCP: bf-api-mcp stdio, same API environment, read-only by default.
BF_API_MCP_ENABLE_MUTATIONS=1 enables scoped direct writes locally.

DISCOVERY AND TWO PAYMENT WORKFLOWS
Discover exact variants, compatible images and owned SSH keys. Never invent IDs.
Use /v1/regions, /v1/products and the selected product's options/quote endpoints.

A: Quote -> create unpaid order -> inspect invoice -> explicitly pay -> provision.
Draft creation does not pay; a separate invoice payment may be partial.

B: POST /v1/deploy/{region}/{productCode}/{variantCode} creates the order, charges
the full final order amount to the account balance and queues provisioning in one request. Use for an
explicitly authorized single-product purchase. It never silently falls back to
an unpaid order or partial payment. Insufficient credit returns HTTP 402 with
error.code=insufficient_credit and no committed new order, invoice or debit.
Canonical snake_case inputs and max_total are documented in the billing brief.
max_total includes tax, setup and add-ons.
CLI: bf deploy REGION vps DISCOVERED_VARIANT --hostname test --os DISCOVERED_OS --max-total 25.00 --quote
Remove --quote only after authorizing full wallet payment. --wait polls readiness.

RETRIES AND UNCERTAIN OUTCOMES
Use a stable Idempotency-Key for each intended write. Most CLI lifecycle --request-key flags are optional: omitted keys are saved
and printed before dispatch. DNSSEC enable/disable requires an explicit key.
Same key and exact request is a retry; different payload with that key is rejected.
After a timeout inspect the original order/invoice/service or operation receipt.
Reuse the original key and payload; a new key can authorize a second purchase.
SDKs never automatically retry writes; read retries honor Retry-After and limits.
fullyPaid/paidNow and invoice state confirm payment. Only operation succeeded
and service readiness confirm provisioning. Accepted/pending/unknown is not ready.

SERVICES AND PAGINATION
Services default to active+suspended. Lifecycle and runtime power are separate.
Filters apply before pagination and counts. Follow each endpoint's documented
page/limit, cursor/next_cursor or offset/next_offset model. limit is canonical;
page_size/pageSize are deprecated HTTP aliases only where explicitly documented.
group_by=type groups the current page. /v1/services/grouped returns the complete
filtered inventory. Legacy default: active only. Pass status explicitly; prefer
/v1/services?statuses=active,suspended for new automation.

ERRORS
{"ok":false,"error":{"code":"scope_denied","message":"Required scope is missing","request_id":"...","field_errors":[]}}
Read error.code/message/request_id/field_errors. Flat fields are legacy
compatibility fields. Optional retryable/outcome/retry_after_seconds guide recovery.

WEBHOOKS
Use /v1/capabilities and the webhook contract to discover enabled events. Manage
/v1/webhooks with webhooks.read/webhooks.write. Create/rotate return the secret
once; list/history omit it. Delivery requires a public HTTPS IPv4 endpoint on 443.
POST /v1/webhooks/{id}/test queues a signed test visible in delivery history.
POST /v1/webhooks/{id}/rotate-secret replaces the signing secret.
Verify bf-signature HMAC-SHA256 over timestamp + '.' + exact raw JSON bytes.
Enforce timestamp tolerance and deduplicate bf-event-id durably. Validate api_version.
Delivery is at least once, can be unordered and retries up to 12 times. Delivered
history remains 30 days, failed 90 days. Paused events wait until resume/deletion.
Keep secrets private; discover emitted events.

DNSSEC AND FAMILY FILTERS
Registered-domain DNSSEC is public via GET/POST /v1/domains/{serviceId}/dnssec.
Read/refresh need domains.read; enable/disable need domains.write, acknowledgement
and a stable Idempotency-Key. HTTP202 is accepted; poll the same DNSSEC GET.
operationId is not a generic operation handle. Parent propagation is unverified.
See the domain brief for modes, public DNSKEYs, CLI and local MCP tools; hosted
MCP has no DNSSEC tool.
type is a normalized family; product_code selects a purchasable family:
tcp-proxy -> type=other; waf -> type=dns; license -> type=other.
MCP clients pass important filters explicitly and discover IDs before writes.

Workflow metadata: discover purchase.draft_order / purchase.atomic_deploy, then
follow requirements_url/options_url for canonical deployment inputs and sources.
Quotes are optional and not price-locked. Approve quote.recommended_max_total and
send max_total; deployment_price_limit_exceeded refuses a higher final total.
Follow returned links.operation/service/invoice/order when present. Canonical
write receipts are opt-in with x-bf-response-format: operation and capability
support; default v1 fields remain compatible. After losing a tracked write
response, GET /v1/operations?idempotency_key=ORIGINAL_KEY without repeating it.
Missing or expired receipts never authorize a replacement key. Poll status/done,
then read the successful result's resource IDs. MCP approval is separate from
execution. DNSSEC retains its own polling contract. See the integration guide.