ONCE

Know whether an uncertain action is safe to retry.

What it does

Record supported provider actions under a stable operation key. Repeated requests reuse the operation; an uncertain outcome remains uncertain until evidence resolves it.

Public developer beta: documentation, signup and free usage are available. Use your product API key for requests; public examples do not require Vercel preview access. Paid subscriptions are available; free usage remains available.

First request

Create a project in the account page and save the API key shown once. Use it as a bearer token. Keep keys in server-side configuration.

curl https://once.aiagenthuddle.com/v1/operations \
  -H "Authorization: Bearer $ONCE_API_KEY" \
  -H "Once-Stripe-Test-Key: $STRIPE_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-123-intent" \
  -d '{"provider":"stripe","action":"create_payment_intent","parameters":{"amount":100,"currency":"gbp"}}'

Supply your own Stripe sandbox credential in the dedicated header. ONCE does not store it. This creates an unconfirmed test PaymentIntent, not a real payment.

Your GitHub connection

Use a fine-grained token limited to your repository with Issues read/write. Supply Once-GitHub-Token and Once-GitHub-Repository: owner/repository in request headers. The repository stays pinned to the operation. Retrying or reconciling requires your credential; a new token may replace an expired one but cannot redirect the operation. Tokens are never stored in the ledger. Creating an issue is a real repository write.

The SDK accepts these credentials as its third constructor argument: {githubToken, githubRepository}. MCP transports send the same HTTP headers; credentials are never tool arguments. Read-only lookup needs only your ONCE key.

REST endpoints

Endpoint	Behaviour
`POST /v1/operations`	Create or retrieve a logical operation using Idempotency-Key.
`GET /v1/operations/{id}`	Read the durable state and retry safety.
`POST /v1/operations/{id}/reconcile`	Read provider evidence and update the operation.
`POST /v1/operations/{id}/retry`	Retry only when the recorded evidence permits it.

Failure behaviour and limits

Reusing a key with different parameters returns a conflict without another provider action.
UNKNOWN and AMBIGUOUS states never permit blind redispatch. A missing provider object alone does not prove non-commit.
Supported adapters create unconfirmed Stripe test PaymentIntents in your sandbox and GitHub issues in a pinned repository using your request-scoped credential. They do not capture live payments or offer arbitrary HTTP access.
Provider-native idempotency can be sufficient for a single integration. ONCE adds a durable operation record and explicit outcome/recovery states for the supported actions. It does not promise universal exactly-once effects.

Request bodies are limited to 16 KiB. Missing, revoked or cross-product keys are rejected. Rate limits return HTTP 429; service unavailability remains an error rather than a successful operation.

Engineering notes

A timeout does not tell you whether an action happened: a concrete failure scenario and the limits of the recovery mechanism.

MCP and SDK access

JavaScript · Node.js

Save the module as sdk.js in a project with "type": "module". The client uses the built-in fetch API.

import { OnceClient } from './sdk.js';

const once = new OnceClient(
  'https://once.aiagenthuddle.com',
  process.env.ONCE_API_KEY,
  { stripeTestKey: process.env.STRIPE_TEST_KEY }
);

const operation = await once.create(
  'order-123-intent', 'stripe', 'create_payment_intent',
  { amount: 100, currency: 'gbp' }
);
// Preserve the operation ID. Inspect before any retry.
console.log(operation);

Authenticated stateless MCP is available at /mcp. Tools: once_create, once_get, once_retry, once_reconcile. Official current and legacy clients have passed protected hosted checks. No resumable SSE sessions or unsupported MCP features are advertised.

The standalone JavaScript client is available directly. Download sdk.js into your server-side project. No npm package is published. Keep credentials outside browser bundles.

Usage, privacy and support

Free preview access includes 1,000 ordinary request units per UTC month. Existing-operation inspection and MCP discovery have a separate minute rate allowance. Reconciliation additionally uses a reserved 100 requests per project per UTC calendar month, independent of ordinary units and shared by free/paid access. Exhaustion returns HTTP 429 MONTHLY_RECONCILIATION_ALLOWANCE_EXCEEDED before provider lookup/history writes; ledger reads remain available. Read the service terms, usage limits, privacy notice and support information before integrating. Download the standalone JavaScript module; no npm package is published.