REST API

A small JSON API over HTTPS.

https://api.openintents.io/v1

Authentication#

Send your API key as a Bearer token. oi_test_ keys create test intents; oi_live_ keys make real purchases.

curl https://api.openintents.io/v1/intents \
  -H "Authorization: Bearer $OPENINTENTS_API_KEY"

Conventions#

• Amounts are integers in the smallest currency unit (cents for USD).
• Timestamps are ISO 8601 in UTC.
• Creates, cancels and answers accept an Idempotency-Key header (up to 255 printable ASCII characters). Retrying with the same key returns the first response instead of doing the work twice. Use it for anything that spends money. The same key with a different body is 409 idempotency_key_reused; the same key while the first request is still running is 409 idempotency_key_in_use.
• Lists are cursor-paginated: pass limit (max 100) and the next_cursor from the previous page.
• Every request is counted against the key's rate limit.

Customers#

A customer is one of your own users, kept as a payer of its own: each has the wallet their purchases are paid from, browser profiles and secrets, apart from your other customers and from your account. Pass customer (the cus_… ID) to act for one: when you create an intent or list intents. Without it the call acts for your account. A customer ID that is not one of your account's is 400 with param: "customer".

curl https://api.openintents.io/v1/customers \
  -H "Authorization: Bearer $OPENINTENTS_API_KEY" \
  -H "Idempotency-Key: 0a4c1d1e-signup-u42" \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "u_42", "name": "Ada Lovelace", "email": "[email protected]" }'

{
  "id": "cus_8f2a",
  "object": "customer",
  "external_id": "u_42",
  "name": "Ada Lovelace",
  "email": "[email protected]",
  "metadata": {},
  "limits": { "per_intent": null, "monthly": null },
  "created_at": "2026-10-01T08:12:00Z"
}

Returns the customer with HTTP 201.

Returns the customer.

Takes the same fields as create. A field left out is kept, an empty string clears external_id, name or email, metadata replaces the whole map, and inside limits only the fields you name change (null removes one).

A page of your customers, newest first. external_id finds the one you know by your own ID.

There is no delete. Forgetting a customer's profile and deleting its secrets erases their browser data and stored details; the customer record itself (name, email, metadata, limits), its ledger entries and its intent history stay.

A customer's wallet#

A link where the customer sets up their wallet ahead of their first purchase: amount, return_url and ttl_seconds are optional. Returns a wallet_link with HTTP 201; send its url to the customer alone. It takes no Idempotency-Key.

Where the customer's wallet stands (status) and the one step left (next_step), checked against a purchase of ?amount= cents if you give one. Never their balance or limits. 503 wallet_unavailable when wallets cannot be read right now. Both are described in wallet links.

Create an intent#

curl https://api.openintents.io/v1/intents \
  -H "Authorization: Bearer $OPENINTENTS_API_KEY" \
  -H "Idempotency-Key: 5b1f6c1e-coffee-0845" \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "flat white, oat milk, pickup 8:45 at the Blue Bottle on 5th",
    "max_amount": 1000,
    "metadata": { "user": "u_42" }
  }'

const res = await fetch("https://api.openintents.io/v1/intents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OPENINTENTS_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({ intent: "book an Uber to SFO at 7am", max_amount: 6000 }),
});
const intent = await res.json(); // { id: "int_…", status: "queued", … }

import os, uuid, requests

intent = requests.post(
    "https://api.openintents.io/v1/intents",
    headers={
        "Authorization": f"Bearer {os.environ['OPENINTENTS_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"intent": "reorder my usual coffee beans on Amazon", "max_amount": 3000},
).json()

Returns the intent object with "status": "queued" and HTTP 201.

Retrieve an intent#

Returns the intent. Poll every 2 to 5 seconds, or use webhooks.

To hold the request open instead, send Prefer: wait=N (whole seconds, at most 50; a larger number is applied as 50). The call returns as soon as the intent is neither queued nor running, or when the time is up, with a Preference-Applied: wait=N header. The same header works on POST /v1/intents, which then returns the intent as it stands when the wait ends. A caller who stops waiting loses nothing: the intent runs on.

List intents#

Newest first. Filter with status and customer.

{
  "object": "list",
  "data": [{ "id": "int_7f3a2c", "status": "completed" }],
  "next_cursor": "int_7f29aa"
}

Answer what the agent asked#

For an intent in requires_input: input (the input_request.id) and exactly one of value (the phone number, email, code, or the answer to a detail, one of its options when it has any), decline: true or done: true (for an approval). Returns the intent, running again. A value that doesn't fit the kind is 400. A question already answered, expired, or one the intent moved past is 409 with code input_not_waiting. See signing in by message.

Cancel an intent#

Cancels an intent that has not paid yet (queued, running, requires_input, requires_payment or requires_login). Cancelled intents are free.

Sign-in links#

A link you make up front for a customer to sign in to a shop, with no intent waiting on it ("connect your account"). The payer opens it, signs in on a picture of the shop's page, and the shop's cookies are saved with their profile, so later intents find them signed in. (An intent that needs a sign-in makes its own link; see sign-in links.)

Returns HTTP 201 and a sign_in object: id (sgn_…), status (open, active, done, declined, expired or cancelled), shop, customer, country, return_url, url (send it to the payer alone), expires_at and ended_at. 403 shop_not_allowed for a shop we do not sign payers in to; 503 sign_ins_unavailable when sign-in links are not on for your key.

Returns the link. When it ends, an endpoint that names sign_in.completed or sign_in.expired is sent a webhook.

Portal sessions#

Gives one of your customers a page of their own, the payer portal, where they see which shops they are signed in to, connect more, and forget what is kept. It acts for that customer only. The portal is on for your key only when we have turned it on (503 portal_unavailable otherwise).

Returns HTTP 201 with { "id", "object": "portal_session", "customer", "url", "expires_at" }. url works once and only for 30 minutes: send it to your customer, who is then signed in to the portal by a cookie for ttl_seconds. It takes no Idempotency-Key: each call makes a new link.

Live views#

Returns HTTP 201 with { "object": "live_link", "session", "url", "expires_at" }: a page that shows a session's browser live and lets whoever opens it tap and type, for 10 minutes. Each call makes a new link and takes no Idempotency-Key. 409 session_not_open for a session that is not open, 404 for another account's session, and 503 live_unavailable when live views are not on for the session.

Webhook endpoints#

/v1/webhook_endpoints lists, creates, updates and deletes your account's endpoints, with rotate_secret, test and a delivery log with redeliver under each. They are covered in Webhooks.

Profiles, sessions and timelines#

• Browser profiles: /v1/profiles, the logins and carts each payer keeps.
• Browser sessions: /v1/sessions, a payer's browser driven step by step.
• Secrets: /v1/secrets, /v1/customers/{id}/secret_requests and /v1/secret_requests/{id}, the details a payer stores once.
• Events & live streams: /v1/intents/{id}/events and /v1/sessions/{id}/events.

Errors#

Errors use standard HTTP status codes and a consistent body:

{
  "error": {
    "type": "invalid_request",
    "code": "max_amount_too_low",
    "message": "max_amount must be at least 50 (cents).",
    "param": "max_amount"
  }
}

Rate limits#

Each API key may make 600 requests a minute in live mode and 300 in test mode, to /v1 and /mcp together. The limit is also the burst: a key that has been idle can send that many at once, then about one a tenth of a second (live) or a fifth of a second (test). Every response from a key carries:

Past the limit the answer is 429 (rate_limit_exceeded) with a Retry-After header: the whole seconds to wait before the next request will pass. Every other 429 carries Retry-After too. Back off for that long, and read RateLimit-Remaining to pace a batch instead of waiting for a refusal.

Failures during an intent (sold out, over budget) are not HTTP errors: the intent ends in failed with an error.code such as over_max_amount, limit_exceeded (the purchase is over a customer's limits), payment_declined (the payer's wallet refused the payment; message is its own reason, and nothing was charged), currency_unsupported (the shop charges in a currency wallets don't pay in yet), out_of_stock, merchant_unavailable or login_required (the shop wants your customer signed in, and they didn't, or you turned sign-in links off). needs_review means the payment step began but its outcome is unknown, so the order may have gone through: the money stays reserved while we check, and the intent is never run again. Don't place the same order again until we have checked it.