Sales Associate API

Last updated: May 5, 2026

A REST endpoint that lets external clients call Omi’s recommendation engine programmatically and render the results in their own UI. One call, one turn of the conversation — the caller owns layout, theming, and product display.

Base URLs

api.youromi.com is a Regional API Gateway custom domain pinned to us-east-1 with TLS 1.2. Prefer the custom domain in client code so a future infrastructure migration doesn’t require a release on your side.

Staging mirrors production but is re-deployed continuously and shares the same rate-limit table. Use staging for contract validation and integration smoke tests; do not load-test against it.

Endpoint path appended to any of the above: /concierge/chat

Authentication

Every request must include an x-api-key header. Omi issues one key per client. The key is bound to a Shopify storefront domain (used to scope catalog lookups), one or more allowed origins (used for browser CORS), and a usage tier (sets rate-limit caps).

Key format

ak_concierge_<48 hex characters>

Sending the key

x-api-key: ak_concierge_7db7c4bc1bc1849cec4884543df6879dcdb56304609d7aef

Rotating keys

Email accounts@youromi.com and we will issue a new key alongside the old one (both valid for the rollover window you specify, default 7 days), then disable the old key when you confirm the cut-over.

Authentication errors

Storing the key

Treat it as a secret: never check it into a public repository, never expose it in client-side JavaScript on a public page (use a server-side proxy for browser-side integrations), and rotate immediately if leaked.

Rate Limits

Rate limits are scoped per API key across three rolling windows. The caps depend on the tier attached to your key:

Counters increment on every accepted request, including ones that fail upstream. The limiter is keyed on the API key, not the session.

Inspecting your usage

Every successful response carries these headers:

When you hit the cap

HTTP/1.1 429 Too Many Requests
Retry-After: 18
Content-Type: application/json

{
  "error": "rate_limited",
  "message": "Rate limit exceeded for window 'minute' (cap 30). Retry after 18s.",
  "request_id": "1f4e2d6c-...",
  "limit_window": "minute",
  "limit": 30,
  "tier": "trial"
}

The Retry-After value is the number of seconds until the breached bucket rolls over. Clients should wait at least that long before retrying, apply jitter when retrying from multiple workers, and treat repeated 429s as a configuration issue rather than retrying indefinitely.

Endpoint

Take a free-text prompt plus optional structured context, and return a recommendation message plus 0–N products.

Request

Headers

Body

{
  "prompt": "Birthday gift for my mom, fashion-leaning, budget around $250",
  "session_id": "9b1f4e2d-6cb2-4f10-9ec0-1234567890ab",
  "context": {
    "occasion": "birthday",
    "recipient": "mother",
    "budget_max": 250,
    "page_url": "https://www.example.com/pages/gifting-concierge"
  }
}

Additional ad-hoc keys inside context are forwarded to the engine as hints; unknown keys are ignored, never rejected.

Limits

Exceeding either returns 400 (body_too_large or prompt_too_long).

Response

Headers

Content-Type: application/json
Access-Control-Allow-Origin: <echoed if origin is allow-listed for your key>
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 487
X-RateLimit-Window: hour
X-RateLimit-Tier: trial

Body (200 OK)

{
  "session_id": "9b1f4e2d-6cb2-4f10-9ec0-1234567890ab",
  "message": "Three picks based on what you described.\n\nLean fashion-forward with a coffee-table format.",
  "products": [
    {
      "id": "gid://shopify/Product/8529335779428",
      "handle": "abu-dhabi",
      "title": "Abu Dhabi Bright",
      "vendor": "Assouline",
      "description": "Glossy travel monograph.",
      "price": 105.0,
      "currency": "USD",
      "image": "https://cdn.shopify.com/.../AbuDhabi01.jpg",
      "url": "https://www.example.com/products/abu-dhabi",
      "available": true
    }
  ],
  "intent": "GIFTING",
  "follow_up": "Want more interiors-leaning options?",
  "refinement_options": [
    { "text": "Under $200", "type": "price_pivot" }
  ],
  "request_id": "1f4e2d6c-aaaa-bbbb-cccc-001122334455"
}

Response fields

Recommended rendering order

When showing the response in a chat-style UI, render in this order:

1. Each paragraph of message (separate bubble per \n\n)
2. The products cards
3. The follow_up bubble
4. The refinement_options chips (if any)

Error Responses

All errors share the same envelope:

{
  "error": "<machine_code>",
  "message": "<human-readable explanation>",
  "request_id": "<uuid>"
}

Any 5xx response should be retried at most 2–3 times with exponential backoff. If the issue persists, capture the request_id and contact support.

CORS

The API serves standard CORS headers. For a given API key, the Access-Control-Allow-Origin header is echoed only if the request’s Origin matches the public_origin or one of the additional_origins configured for your key.

Unknown origins still get a 200 response (so server-to-server callers work), but the browser will block the response from reaching the page.

If you need an additional origin allow-listed (e.g. a staging domain), email accounts@youromi.com.

Browser-side integrations

For production browser-side use, do not embed the API key in client-side JavaScript. Instead:

1. Stand up a thin server-side proxy (Cloudflare Worker, Lambda, Vercel function, etc.) that holds the API key and forwards requests
2. Optionally add per-end-user rate limiting at that layer

Examples

curl

curl -X POST "https://api.youromi.com/v1/concierge/chat" \
  -H "x-api-key: ak_concierge_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Birthday gift for my mom, budget $250",
    "context": {
      "occasion": "birthday",
      "recipient": "mother",
      "budget_max": 250
    }
  }'

JavaScript (fetch)

const res = await fetch(
  "https://api.youromi.com/v1/concierge/chat",
  {
    method: "POST",
    headers: {
      "x-api-key": process.env.OMI_CONCIERGE_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      prompt: "Birthday gift for my mom, budget $250",
      session_id: sessionStorage.getItem("omi_session")
        ?? crypto.randomUUID(),
      context: {
        occasion: "birthday",
        recipient: "mother",
        budget_max: 250,
      },
    }),
  }
);

if (res.status === 429) {
  const wait = Number(res.headers.get("Retry-After") ?? 60);
  console.warn(`Rate limited, retrying in ${wait}s`);
  // implement retry logic here
}

if (!res.ok) {
  const err = await res.json();
  throw new Error(
    `Omi error ${err.error} (${err.request_id}): ${err.message}`
  );
}

const {
  session_id, message, products,
  follow_up, refinement_options
} = await res.json();

sessionStorage.setItem("omi_session", session_id);

Python (requests)

import os, uuid, requests

BASE = "https://api.youromi.com"

def ask_omi(prompt: str, session_id: str | None = None, **context):
    body = {
        "prompt": prompt,
        "session_id": session_id or str(uuid.uuid4()),
    }
    if context:
        body["context"] = context

    resp = requests.post(
        f"{BASE}/v1/concierge/chat",
        headers={
            "x-api-key": os.environ["OMI_CONCIERGE_KEY"],
            "Content-Type": "application/json",
        },
        json=body,
        timeout=30,
    )

    if resp.status_code == 429:
        retry_after = int(resp.headers.get("Retry-After", "60"))
        raise RuntimeError(f"rate_limited; retry in {retry_after}s")

    resp.raise_for_status()
    return resp.json()


reply = ask_omi(
    "Birthday gift for my mom, budget $250",
    occasion="birthday",
    recipient="mother",
    budget_max=250,
)

print(reply["message"])
for p in reply["products"]:
    print(f"  - {p['title']} ({p['price']} {p['currency']}) {p['url']}")

Latency

Cold Lambda starts are not expected (warmed every 5 min). Latency scales with catalog size and the number of brand/collection filters in the prompt.

The recommendation engine streams its first token within ~600 ms but this API returns a single JSON document. Streaming responses are on the roadmap.

Changelog

2026-05-02 — v1.2

Custom domain api.youromi.com is live (Regional API Gateway, TLS 1.2) for both production and staging. Raw execute-api URLs still work but new integrations should use the custom domain.

2026-05-02 — v1.1

• Per-API-key rate limits with tier-based caps (trial / production / internal)
• Retry-After, X-RateLimit-* headers
• request_id returned on every response
• New 4xx codes: body_too_large, prompt_too_long, body_must_be_object
• Per-key CORS via additional_origins
• Structured error envelope

2026-04-30 — v1.0

Initial release. POST /v1/concierge/chat over x-api-key auth.

Support

Include in every report: the request_id from the response, approximate timestamp (UTC), and the prompt that triggered the issue.