the api, in plain english

Quick start #

Three commands and you have a working integration. Get a key, ping, list projects — that's it.

1 · Get an API key #

Visit /dashboard/api-keys → Create key. The secret is shown once — copy it into your secret store immediately.

2 · Smoke test #

curl https://myaise.com/v1/ping \\
  -H "Authorization: Bearer myaise_live_…"

3 · List your projects #

curl https://myaise.com/v1/projects \\
  -H "Authorization: Bearer myaise_live_…"

Authentication #

Every request carries a workspace-scoped Bearer token. Keys are workspace-scoped — a team key can never see a personal workspace. MCP clients such as Claude can sign in with OAuth instead of using a key; see Connect Claude.

Authorization: Bearer myaise_live_<prefix>_<random>

Scopes #

Dashboard presets #

The API keys page mints keys from presets. A preset name is never stored; the key carries the scopes it expands to.

Studio (free) #

Concepts #

Six resources, in nesting order. Everything else is a child or a side-effect.

ID prefixes #

Every ID is prefixed so you can spot the resource by eye — no need to remember which is which.

• ws_team workspace
• ws_user_personal workspace
• proj_project
• demo_demo
• step_step
• ov_overlay
• act_action
• sess_viewer session
• wh_webhook
• del_delivery

Embed MyAISE in a signup flow #

A new prospect signs up on your site. Your backend POSTs to MyAISE to mint a session URL, then redirects the prospect there instead of an empty account.

Use a sessions_only key for this integration.

// mint a session, redirect prospect
const res = await fetch(
  "https://myaise.com/v1/demos/demo_abc.../sessions",
  {
    method:  "POST",
    headers: {
      "Authorization":   `Bearer ${process.env.MYAISE_API_KEY}`,
      "Content-Type":    "application/json",
      "Idempotency-Key": prospect.id   // safe to retry
    },
    body: JSON.stringify({
      prospect: {
        name:    prospect.name,
        email:   prospect.email,
        company: prospect.company
      },
      encrypted_payload:  encryptCookies(cookies, myaisePubkey),
      expires_in_seconds: 3600
    })
  }
);

const { data } = await res.json();
res.redirect(data.viewer_url);

A live demo before signup (website integration) #

A prospect on your marketing site fills in name, email and company. Your backend provisions a throwaway demo account inside your own app, encrypts a one-time login URL for it, creates a MyAISE session with a time limit, an AI-credit budget and a host allowlist, binds an MCP grant so the AI SE can act as that demo user, redirects the prospect to the viewer, and cleans up when the session.ended webhook arrives.

Before you start

• An AI SE workspace with MyAISE (the assistant) enabled.
• An API key with sessions:write + sessions:credentials:submit — a sessions_only key is exactly that set.
• A webhook subscribed to session.ended (and optionally session.budget_exhausted).
• The id of the demo to launch (demo_…).
• Optionally, the workspace Website integration policy in the dashboard — default / maximum TTL, default / maximum credit budget, allowed-hosts mode. Values you send are clamped to it.

# your form handler
POST https://you.example/demo-requests

# provision the demo account, then:
GET  https://myaise.com/v1/viewer/public_key
POST https://myaise.com/v1/demos/demo_b3d2.../sessions
POST https://myaise.com/v1/customer_app/mcp_handoffs

# hand the prospect over
303  Location: <viewer_url>

# later, from MyAISE to you
POST https://you.example/webhooks/myaise   # session.ended

Fetch the public key #

Every workspace has an RSA public key (PEM) held by its viewer key provider. You wrap the per-session AES key with it; the matching private key never leaves the key provider, and the cloud only ever holds the sealed envelope.

curl https://myaise.com/v1/viewer/public_key \
  -H "Authorization: Bearer $CAP_KEY"

Fetch it per session and never persist it — the key is regenerated in development and rotated in production, and a stale key produces a session whose credentials can never be unsealed. The response spells out the whole envelope contract (padding, hashes, IV and tag sizes, the plaintext schema) so you never have to guess; the full shape is in the endpoint reference. If the key provider is unreachable you get 503 key_unavailable — retry. There is no plaintext fallback: plaintext credentials are rejected.

Encrypt the login #

The envelope is fixed:

• A random 32-byte AES key and a random 12-byte IV, both fresh for every session.
• AES-256-GCM over the UTF-8 JSON plaintext with empty additional data (AAD = ""), producing a 16-byte tag.
• The AES key wrapped with RSA-OAEP — SHA-256 hash, MGF1-SHA-256, no label.
• Every field base64 (standard alphabet, padded), sent as encrypted_key, iv, ciphertext, tag.

The plaintext is one small JSON object:

{
  "base_url": "https://app.example.com/demo/enter/<one-time-token>",
  "cookies": [],
  "headers": {}
}

Prefer a one-time login URL over real cookies — it is the smallest thing you can hand over and it dies on first use. When you do need cookies, each entry is { name, value, domain, path, secure, httpOnly }; headers are sent on every request to the base_url host. The viewer machine consumes the credentials exactly once, and the cloud stores only the sealed envelope — never the plaintext, never the AES key.

Both examples are stdlib only — Ruby 3.x on OpenSSL 3, and Node 18+ on node:crypto. (On Ruby 3.4+ base64 is a bundled gem: add it to your Gemfile, or swap those four calls for [bytes].pack("m0").)

require "openssl"
require "json"
require "base64"

def seal_for_myaise(plaintext_hash, public_key_pem)
  cipher = OpenSSL::Cipher.new("aes-256-gcm").encrypt
  key = cipher.random_key          # 32 bytes
  iv  = cipher.random_iv           # 12 bytes
  cipher.auth_data = ""
  ciphertext = cipher.update(JSON.generate(plaintext_hash)) + cipher.final
  tag = cipher.auth_tag            # 16 bytes

  rsa = OpenSSL::PKey.read(public_key_pem)
  wrapped = rsa.encrypt(key,
    rsa_padding_mode: "oaep",
    rsa_oaep_md: "sha256",
    rsa_mgf1_md: "sha256")         # never public_encrypt: that is SHA-1 OAEP

  {
    encrypted_key: Base64.strict_encode64(wrapped),
    iv:            Base64.strict_encode64(iv),
    ciphertext:    Base64.strict_encode64(ciphertext),
    tag:           Base64.strict_encode64(tag)
  }
end

import { randomBytes, createCipheriv, publicEncrypt, constants } from "node:crypto";

export function sealForMyaise(plaintext, publicKeyPem) {
  const key = randomBytes(32);
  const iv = randomBytes(12);
  const cipher = createCipheriv("aes-256-gcm", key, iv);
  cipher.setAAD(Buffer.alloc(0));
  const ciphertext = Buffer.concat([cipher.update(JSON.stringify(plaintext), "utf8"), cipher.final()]);
  const tag = cipher.getAuthTag();
  const wrapped = publicEncrypt(
    { key: publicKeyPem, padding: constants.RSA_PKCS1_OAEP_PADDING, oaepHash: "sha256" },
    key
  );
  return {
    encrypted_key: wrapped.toString("base64"),
    iv: iv.toString("base64"),
    ciphertext: ciphertext.toString("base64"),
    tag: tag.toString("base64"),
  };
}

Create the session #

POST /demos/:demo_id/sessions, with an Idempotency-Key header so a retried POST replays the original response instead of spinning a second viewer machine.

{
  "prospect": {
    "name": "Sarah Chen",
    "email": "sarah@acme.com",
    "company": "Acme",
    "metadata": { "lead_id": "ld_91" }
  },
  "encrypted_payload": { "encrypted_key": "…", "iv": "…", "ciphertext": "…", "tag": "…" },
  "expires_in_seconds": 1200,
  "credit_budget": 100,
  "allowed_hosts": ["app.example.com", "*.app.example.com"]
}

A 201 comes back with the one-time viewer URL and the limits as they were actually applied:

{
  "data": {
    "id": "sess_7a2e...",
    "token": "v1_AbCd...",
    "status": "pending",
    "viewer_url": "https://joinlivedemo.com/view/v1_AbCd...",
    "expires_at": "2026-09-06T14:30:00Z",
    "expires_in_seconds": 1200,
    "credit_budget": 100,
    "credits_spent": 0,
    "allowed_hosts": ["app.example.com", "*.app.example.com"],
    "demo_id": "demo_b3d2...",
    "project_id": "proj_e72b...",
    "workspace": { "type": "team", "id": "ws_3f1c..." }
  }
}

The three limits:

• Time limit. expires_in_seconds is clamped to the workspace maximum, so read expires_at and expires_in_seconds back from the response instead of assuming. When the clock runs out the session ends with end_reason: "ttl_expired".
• Credit budget. The AI SE's answers, walkthrough generation and agent turns each cost credits (see AI credits). Without credit_budget the session takes the workspace default, or 5000 credits when the workspace sets none (lowered to the workspace maximum if that is smaller); read credit_budget back from the response. The turn that reaches the budget is the last one, and the session ends with end_reason: "credit_budget_exhausted". Live-viewer session hours are metered separately and are not part of this budget.
• Host allowlist. The streamed browser refuses top-level navigations to any other host and bounces back to the demo's base URL — links to your marketing site, your docs or an external site cannot carry the prospect away. Page subresources from other hosts still load.

Errors worth handling: 400 invalid_expires_in and 400 invalid_credit_budget for values that are not positive integers; 422 credit_budget_exceeds_policy when the budget is above the workspace maximum; 422 invalid_allowed_hosts when the list is not an array, holds more than 20 entries, or contains an entry that is not a hostname (the offending entry is named in the error message); 422 navigation_base_required when the workspace limits sessions to the project's hosts but the project has no base URL (or *) and none of its demos names a site (an absolute step URL or an exit URL), so there is no host to allow and nowhere to bounce back to. Set the project's base URL or give a demo step an absolute URL.

Bind the MCP grant #

If your app exposes an MCP server, the AI SE can answer "how many campaigns do I have?" by calling it as the demo user. Mint a short-lived grant scoped to the demo account you just provisioned — expiring no later than the session, with a tool-call cap — and push it server-side with viewer_session_id from the previous response:

{
  "endpoint_url": "https://mcp.example.com/rpc",
  "access_token": "demo_user_grant_...",
  "expires_at": "2026-09-06T14:30:00Z",
  "app_ref": "example-app",
  "account_id": "demo_acct_91",
  "scopes": ["read_only"],
  "viewer_session_id": "sess_7a2e...",
  "tool_catalog": { "tools": [ /* your MCP tools/list result for this grant */ ] }
}

tool_catalog is what the AI SE can call: pass the tools/list result your server returns for this grant (MCP shape — name, description, inputSchema, annotations). MyAISE never calls tools/list itself, so a handoff without a catalog gives the AI SE zero tools.

The grant is bound to that prospect's viewer session, so it dies with the session. Re-pushing with the same viewer_session_id rotates the grant. Because the binding is authorised by the same scope that created the session, sessions:write is enough here — a sessions_only key can push a session-bound handoff, while an unbound one still needs content:write. Building the MCP server itself is covered in the MCP integration guide.

Handle session.ended #

Every terminal session fires the specific event plus the meta session.ended:

{
  "id": "evt_9b1f...",
  "type": "session.ended",
  "created_at": "2026-09-06T14:21:03Z",
  "workspace_id": "ws_3f1c...",
  "api_version": "2026-06-01",
  "data": {
    "session_id": "sess_7a2e...",
    "status": "expired",
    "completion_type": "budget_exhausted",
    "end_reason": "credit_budget_exhausted",
    "ended_at": "2026-09-06T14:21:02Z",
    "seconds": 742,
    "credits_spent": 100,
    "credit_budget": 100,
    "allowed_hosts": ["app.example.com", "*.app.example.com"],
    "expires_at": "2026-09-06T14:30:00Z",
    "prospect": {
      "name": "Sarah Chen",
      "email": "sarah@acme.com",
      "company": "Acme",
      "metadata": { "lead_id": "ld_91" }
    },
    "demo_id": "demo_b3d2...",
    "project_id": "proj_e72b..."
  }
}

end_reason is one of:

On receipt:

1. Verify the signature (see Signature verification) before trusting anything in the body.
2. Be idempotent on the event id — retries and replays are expected.
3. Revoke the MCP grant.
4. Disable or soft-delete the demo account immediately; hard-purge it after a grace period.

Run a sweeper too, for sessions whose webhook you never received: the session show endpoint reports status, end_reason and ended_at, so a periodic reconcile over your own open demo accounts closes the gap.

What the prospect sees #

A branded viewer page — your logo, colours and splash from the white-label theme — with a countdown pill showing the time left that turns amber under five minutes, and the AI SE chat alongside the live app. When the session ends they get an end screen keyed on end_reason: "Your demo time is up" for the time limit, an "AI budget has been used up" message for the credit budget, "Thanks for watching" when the demo completed, and your demo's exit URL if it defines one. Nothing about credits, hosts or policy is exposed beyond the countdown and that end screen.

Teams with a custom end page in their white-label theme keep it. Add <ca-slot name="end_headline">, <ca-slot name="end_subtitle"> or <ca-slot name="end_reason"> to that page and the viewer fills in why the session ended; slots the page does not use cost nothing.

Security checklist #

• Login URLs are one-time and short-lived (five minutes or less), stored on your side as digests, never in plaintext.
• Demo accounts are least-privilege: no billing, no team management, no API keys, no purchasing.
• Ship only the cookies the demo needs, and only for the demo account.
• viewer_url is a bearer secret — redirect once, never log or email it.
• Allow only the hosts the demo needs; every extra host is somewhere a prospect can wander.
• Rate-limit and CAPTCHA the form, and cap concurrent sessions per IP, per email and per workspace.
• Keep prospect.metadata to what you would put in a CRM — no PII beyond that.
• Verify webhook signatures, tolerate replays, and expect the same event id more than once.
• Purge demo data on a schedule, not only on the webhook.
• Never log the API key, the encrypted payload, or the login token.

AI-design a demo via MCP #

Connect Claude (or any MCP client) to https://myaise.com/mcp. You sign in to MyAISE, pick a workspace and what the client may do, and there is no key to copy. The model then authors demos the same way your backend would.

1 · Connect the client #

• Claude.ai and Claude Desktop: open Settings → Connectors, choose Add custom connector and enter https://myaise.com/mcp.
• Claude Code: add the server, then run /mcp in Claude Code and choose it to sign in.

claude mcp add --transport http myaise https://myaise.com/mcp

The client opens a MyAISE page in your browser. Sign in with GitHub or Google, pick the workspace (only workspaces on Solo or AI SE can connect), check the scopes it may use, and approve. The client receives a one-hour access token and a refresh token; it renews them itself for up to 90 days. The connection is listed under API keys → Connected apps, where you, or the owner of its team, can revoke it at any time. Leaving the team ends it too.

Use an API key instead

Scripts and clients without OAuth support can send an API key from API keys as a Bearer header:

{
  "mcpServers": {
    "myaise": {
      "transport": "http",
      "url":       "https://myaise.com/mcp",
      "headers": {
        "Authorization": "Bearer myaise_live_..."
      }
    }
  }
}

claude mcp add --transport http myaise https://myaise.com/mcp --header "Authorization: Bearer myaise_live_..."

2 · Ask the model

3 · What it does, step-by-step

1. tools/list — sees the full tool surface.
2. The design_demo prompt — gets a structured prompt template covering URL flow + overlay copy guidelines.
3. projects.create, then demos.create with nested steps + overlays.
4. For anchored overlays, attaches target_context (+ an optional baseline screenshot) so the demo can self-heal — see “Drift protection” below.
5. sessions.create to actually launch the demo.

4 · Configure the workspace from chat #

With a team key minted from the full preset, the model can also configure the whole workspace — Assist, your app's MCP connection, the visual asset Library, whitelabel branding, billing, and usage — the same way the dashboard does. The same rules as the dashboard apply: the key's creator must still be a member of the team, on the plan the dashboard action itself requires. Every tool below routes through the same context function its dashboard action calls, with the same validation.

Projects

Demos

Sessions

Customer App

Webhooks

Solutions

Assist

Keys

Workspace

Integrations

Knowledge

Embed

Library

Branding

Domains

Billing

Usage

Environments

5 · Drift protection (self-healing) #

Customer sites change. When an overlay's target element moves or its selector breaks, MyAISE re-locates it using the overlay's target_context — a snapshot of the element's anchors. To make an agent-authored demo durable:

1. Set auto_healing_enabled: true on the demo (demos.create / demos.update).
2. Give every anchored overlay (one with a target_selector) a target_context on overlays.create — capture it from the live page you authored against:

"target_context": {
  "selectorCandidates": [
    { "kind": "id", "selector": "#new-report", "rank": 0 },
    { "kind": "role-name", "selector": "button[name=\"New report\"]", "rank": 2 }
  ],
  "role": "button",
  "accessibleName": "New report",
  "textContent": "New report",
  "nearbyText": ["Reports", "Create"],
  "rect": { "x": 120, "y": 340, "width": 96, "height": 32 }
}

Optionally pass a base64 screenshot alongside it; MyAISE stores it as a baseline demo asset and references it from target_context.screenshotRef for visual diffing. Re-baseline after a site change with overlays.update (a screenshot-only update keeps the existing anchors). Floating overlays (modal/banner with no target_selector) don't need this.

Embed library #

Drop a <script> tag in your own product and run MyAISE-authored demos on your customer's REAL accounts. Overlays + transitions render on your DOM — no proxy hop, no PII upload, no screen recording. Team-tier only.

Install #

One bundle — myaise.min.js — does everything: overlay rendering, CSS step transitions, and the full Three.js transition set. Each demo's custom themes / animations / transitions are fetched at launch as a per-demo asset pack (one request, SRI-verified), so the bundle stays the same size no matter how customized your demos are. Strict-CSP-safe — no unsafe-eval, no new Function. Load from our CDN (versioned) or self-host with SRI:

Asset code (custom and marketplace transitions, scripted overlay animations) never runs in your page: each run gets a sandboxed frame (sandbox="allow-scripts") with no access to your page, cookies or storage. The frame runs inline script only and its policy blocks requests. A Content-Security-Policy cannot switch WebRTC off, so the frame's first script, before any asset code, removes WebRTC and media capture from the frame, makes shadow DOM unavailable in it and discards any frame nested inside it. The frame still receives the before/after snapshots of your page that it animates, and a browser cannot stop a frame from navigating itself, so treat a transition's snapshots as readable by the asset's author. Marketplace code is published only after an admin reviews it and our automated review passes it; the automated review rejects any code that uses WebRTC or media capture. An asset's stylesheet is not script and does not run in the frame: a transition's code_css is added to your page's <head> (asset verification rejects a stylesheet that loads anything but an inline image). Under a strict CSP, keep your API host in connect-src (the frame's Three.js build loads from it) and, with a nonce-based script-src, pass cspNonce.

The SDK is served from MyAISE and exposes window.MyAISE; it is not published to npm, so install it only from these script tags. These examples give it the local name MyAISE and connect it to the MyAISE API.

<script src="https://myaise.com/embed/v1/myaise.min.js"></script>
<button id="show-me-tour">Show me a tour</button>
<script>
  const MyAISE = window.MyAISE;
  MyAISE.init({
    apiKey: "myaise_pub_xxx",
    apiBase: "https://myaise.com",
  });

  document.querySelector("#show-me-tour").addEventListener("click", () => {
    MyAISE.launch("your-demo-uuid");
  });
</script>

Or self-host (recommended for strict CSP): replace the CDN script tag with this one and keep the initialization and launch code below it.

<script
  src="/static/myaise.min.js"
  integrity="sha384-wlZ/BbgH0VR5ZSzjMDRPivBRHSoylx0XjedoLTDm+RkfaO5o1ZZ5cRFPtXMrgsj1"
  crossorigin="anonymous"
></script>

Embed keys #

Embed mode uses embed keys (myaise_pub_*), different from the secret myaise_live_* keys you use server-side. Create one on the API keys page, where each key, its embed key id (the JWT kid) and your team id stay visible:

• Domain allowlist: customer.com, *.customer.com. A leaked key can't be used from any other origin.
• Demo allowlist: pin a key to one or more demo UUIDs.
• Team-scoped: embed keys belong to teams (AI SE plan required).

Embed keys are designed to live in your HTML — they're usage scoping, not protection. Treat the demo spec as public content (your customer's visitors can see it anyway).

For tighter setups, mint short-lived launch JWTs from your backend:

MyAISE.init({
  apiBase: "https://myaise.com",
  jwt: await fetch("/api/myaise-token").then(r => r.text()),
  jwtRefresh: async () => fetch("/api/myaise-token").then(r => r.text()),
});

JWTs are HS256-signed with a per-key secret OR Ed25519-signed against a public key you register with us. Required claims: iss, aud=myaise.embed, typ=embed_access, sub, kid (header), origin, team_id, jti, exp at most 5 minutes out. When the key has a demo allowlist, sub must be one of those demo ids. Optional: end_user_ref, context, and the credit claims.

Identify the end user with end_user_ref, never sub. The embedded assistant scopes chats and credit allowances to the explicit end_user_ref claim — your stable id for the signed-in user, e.g. user.id. sub is never used as the end-user identity; without end_user_ref the context exchange refuses with 403 end_user_required, and an end_user_ref that names one of your demos is refused with 400 invalid_end_user.

Session tokens. The session_api_key an assistant conversation or demo launch returns stops working when the session ends, when its key is revoked (revoking a key ends every open session it minted), 24 hours after it was issued, or after 2 hours unused. Every assistant turn also re-checks the key, the plan, the assistant switch and the domain allowlist, so turning any of them off stops turns on tokens already issued.

Per-user credits #

When the assistant is embedded in your product, every answer draws on your workspace balance. Per-user allowances let you decide how much of it each of your users may spend — sell credits monthly, grant a fixed pool, or block a user — without giving anyone unbridled access.

Allowances need JWT mode: the user is identified by the end_user_ref claim (required — sub is not an identity). Once any allowance is configured (a workspace default or maximum, or any user with an allowance), conversations without a signed end_user_ref are refused with 403 end_user_required, so a capped or blocked user can't fall back to an anonymous chat. Three optional claims set the allowance for that user:

An allowance set through the API or the dashboard is a pin that wins over the claim, which wins over the workspace default; a JWT never overwrites a pin, with or without claims, until you clear it. Every claim and pin is clamped to the maximum allowance in the dashboard (Assist → Website integration → Embedded assistant), and invalid claims refuse the exchange with 400 invalid_credit_claims rather than silently granting unlimited credits.

// Your backend, when rendering the page for a signed-in user:
const claims = {
  iss: "app.example.com", aud: "myaise.embed", kid: PUBLISHABLE_KEY_ID,
  origin: "https://app.example.com", team_id: TEAM_ID,
  sub: user.id,
  end_user_ref: user.id,             // required: the end-user identity
  jti: crypto.randomUUID(), exp: now + 300,
  context: { key: account.id, label: account.name },
  credit_allowance: user.plan.aiCredits,   // e.g. 300 per month
  credit_period: "monthly",                // or "total"
  // credit_period_key: user.billingCycleStart  // your own cycle instead of calendar months
};

What a turn costs. An embedded answer costs 30 credits (a live-MCP agent turn), a confirmed customer-app action's verification the same, and a generated walkthrough 8. The turn that reaches the allowance is the last one — spend can exceed the allowance by less than one turn, and remaining is reported as 0. A user whose allowance cannot cover a walkthrough still gets the answer. Your workspace balance is charged as usual after the user's reservation; if the workspace itself is out of credits the reservation is returned.

What the widget shows. The exchange, the chat list and every turn response carry a credits object (null when the user has no cap): allowance, extra_credits (top-ups not yet spent; they carry over), spent, remaining (what is left of the allowance, plus the pot), period, period_key, resets_at and your out_of_credits message + link. The widget renders a "N credits left" pill in the header (amber under 10 %) and, once the user is out, locks the composer and shows your message with a "Get more credits" button pointing at your top-up page — both set in the dashboard. A turn refused for this reason returns 402 with code: "user_allowance_exhausted" and the same credits object; the workspace-level out_of_credits 402 is unchanged and unrelated.

{
  "error": {
    "type": "user_allowance_exhausted",
    "code": "user_allowance_exhausted",
    "message": "You've used this month's AI credits.",
    "url": "https://app.example.com/billing/credits",
    "credits": {
      "allowance": 300, "extra_credits": 0, "spent": 300, "remaining": 0,
      "period": "monthly", "period_key": "2026-09",
      "resets_at": "2026-10-01T00:00:00Z",
      "out_of_credits": { "message": "You've used this month's AI credits.", "url": "https://app.example.com/billing/credits" }
    }
  }
}

Managing allowances from your backend. GET /v1/embed/end_users/:end_user_ref/credits reads a user's standing; PUT sets credit_allowance, credit_period / credit_period_key, and reset_spent: true zeroes the counter (a refund or a new plan), and add_credits: N adds to a top-up pool that is spent after the period allowance and carries over until used. That last one is the self-serve flow: point your out-of-credits link at your billing page and, once the purchase clears, PUT add_credits from your backend with an Idempotency-Key (your payment id, so a retried request never grants the credits twice) — the widget re-reads the standing when the user comes back to its tab (or taps "I've added credits") and unlocks without a reload; unused top-ups survive the period reset, and the exhausted webhook re-arms. An allowance you set is pinned — it beats the JWT's claims on every later visit until clear_override: true, while the period follows the JWT — and the same controls are on the dashboard under Assist → End users, so your support team can bump one user without code. Both use your secret key. When a user runs out you receive the embed.end_user_credits_exhausted webhook once per period with end_user_ref, the standing and resets_at — the hook for an upsell email or an in-app nudge. See the endpoint reference.

Step transitions #

Per-step transitions are stored as an object on the demo's step:

{
  "id": "step-2",
  "url_pattern": "/dashboard/billing*",
  "transition": {
    "wipe": "cube",
    "bg_color": "#0c0a20"
  },
  "overlays": [ ... ]
}

The catalog has three kinds, all rendered by the one bundle:

• Simple — pure CSS. Five ids: none, blur, zoom_css, slide, circle_css.
• 2D — Three.js fragment shaders on a flat quad. dissolve, glitch, liquid, and dozens more.
• 3D — true depth + multi-mesh scenes. cube, flip, fold, cosmic and others.

The runtime bundles a handful of scenes (dissolve, cube, flip, glitch); every other Three.js/html-doc transition arrives in the demo's asset pack and is registered at launch — still no eval. Model-backed transitions such as koi ship their html_doc plus a CORS model_url in the pack.

Overlay animations #

Each overlay can pick from 13 enter animations (matching the desktop studio's OVERLAY_ANIMATIONS list). The renderer applies a per-overlay-type default; set animation on the overlay to override:

{
  "id": "hero-modal",
  "type": "modal",
  "title": "Welcome to Acme",
  "animation": "elastic",
  "body": "Three minutes to your first dashboard."
}

The full list of wire ids:

• fade — quick opacity fade. Default for spotlights, outlines, hotspots, number badges, banners.
• scale — opacity + scale-in from 0.5 with a tiny overshoot.
• slide-up / slide-down / slide-left / slide-right — translate from off-axis.
• rise — translateY + perspective + a blur dropoff. Default for tooltips, callouts, slideouts.
• fly-in-3d — Z-axis fly-in with rotation + blur. Default for driven_action overlays.
• portal — perspective scale + rotate-X. Default for modals.
• elastic — scale-in with a rubber-band overshoot.
• glitch — clip-path stutter + RGB color shift.
• zoom-spin — scale from 0 + 180° rotation.
• parallax — minimal translateY for content-heavy slideouts.

Unknown ids fall back to the per-type default (no error). Class names are .ca-enter-<id> exactly — easy to inspect in devtools.

Demo-level config #

Every demo carries a target_runtime field that the studio's picker filter consults and that gates which assets are embed-eligible (all embed targets load the same myaise.min.js):

• viewer (default) — the desktop / cloud viewer pool. All transitions available.
• embed_lite — customer-site embed; simple CSS transitions + overlays.
• embed_pro — customer-site embed; adds Three.js scenes (bundled + pack-delivered) on top.

Set it on create or patch:

POST /v1/projects/proj_<uuid>/demos
Content-Type: application/json

{
  "name": "Acme onboarding",
  "target_runtime": "embed_pro",
  "theme_id": "ocean",
  "steps": [ ... ]
}

MCP authoring tools (demos.create, demos.update) accept the same field. The cloud schema enum-validates the value, so a typo bubbles up as a changeset error instead of silently coercing to viewer.

Drift checks #

Demos break when your UI changes. To keep them healed without ever touching real user data, configure a test account per project in Studio. We run a headless Playwright check against that account every N minutes (max 30) and AI-heal selector drift when confidence ≥ your threshold. Two credential modes:

• Encrypted at rest — cookies / headers arrive over TLS and are immediately protected with a KMS-backed AES-256-GCM data-key envelope. Cleartext is recovered only for the claimed drift check.
• Customer-backend JWT callback — we POST your webhook at check time; you return a 5-minute signed token. We never persist credentials.

A callback response JWT must carry aud: "myaise.embed.callback_response". Saving the callback binds it to one active HS256 embed key and returns callback_api_key_id; pass a replacement id explicitly when you rotate that callback key. Ed25519-only keys cannot authenticate MyAISE's request and are therefore not eligible for credential callbacks.

The drift envelope ships inline with every demo fetch — the library exposes it via onDriftDetected:

MyAISE.launch("demo-uuid", {
  onDriftDetected: (info) => {
    // info.status: ok | unverified | stale | broken | healed
    // info.findings_count, info.checked_at, info.next_check_at
  },
});

Timeline capture & PII #

The library captures overlay clicks only — clicks on the Next/Back/dismiss buttons we render, never anything on your customer's page. There is no document-level listener and we don't read text content, attribute values, or input values from any element. URL paths aren't captured either.

Capture is opt-in:

MyAISE.init({
  apiKey: "myaise_pub_xxx",
  apiBase: "https://myaise.com",
  captureTimeline: true,             // default false
  navigationMode: "auto",          // "spa" | "mpa" | "auto"
  variables: { firstName: "Alice" },
  cspNonce: "<your-csp-nonce>",  // for strict CSP
});

Event shape (overlay-scoped):

{
  "event_type": "overlay_click",
  "ts": 1717108800123,
  "step_index": 2,
  "overlay_id": "ov_abc...",
  "button_id": "1",
  "action": "next_step"
}

Webhooks #

Subscribe to lifecycle events at /dashboard/webhooks or via POST /v1/workspaces/:ws/webhooks. Signing secret is shown once.

Signature verification #

Each delivery carries a header you must verify before trusting the payload:

X-MyAISE-Signature: t=<unix-seconds>,v1=<hmac-sha256>

Where hmac = HMAC-SHA256(signing_secret, "<t>.<raw_body>"). Every delivery also carries X-MyAISE-Event-Id (the payload's id, use it to de-duplicate retries) and X-MyAISE-Event-Type. Header names are case-insensitive. Verification (Node):

import crypto from "node:crypto";

function verifyMyAISESignature(rawBody, header, secret) {
  const parts = Object.fromEntries(
    header.split(",").map(p => p.split("=", 2))
  );

  const t  = parseInt(parts.t, 10);
  const v1 = parts.v1;

  // ±5min clock-skew guard
  if (Math.abs(Date.now() / 1000 - t) > 300) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(v1,       "hex")
  );
}

Retry & auto-disable #

Failed deliveries back off exponentially. After 8 consecutive non-2xx responses, the webhook auto-disables and we email the workspace owner.

Redrive a specific failed delivery via POST /v1/webhook_deliveries/:id/redrive. Full event taxonomy at GET /v1/event_types.

Ingest API #

The ingest API lets you push support conversations into MyAISE from anywhere — helpdesk exports, chat platforms, internal tools, whatever you run. Zendesk has a hosted sync; for other sources, use a collector that maps your conversations to this API. Everything you push lands in the team's quarantined mining pipeline — raw conversations never reach your end users; only genericized, human-approved solutions do.

Keys & auth #

Requests authenticate with source-bound myaise_ing_* keys minted on /dashboard/api-keys. Send the secret as Authorization: Bearer. Each key is bound to one team and one source slug you choose at mint time. The slug must be 2-32 chars, use lowercase letters, digits, dash, or underscore, and start with a letter or digit; common ones are telegram | slack | whatsapp | zendesk | other, or anything that names your source. The channel kind always derives from the key's ingest_source, never from the request — a key minted for internal-crm can only feed internal-crm channels. The secret is shown once at mint; revoke it and anything still using it stops immediately.

Pushing items #

Base URL: https://myaise.com/v1/ingest. Register each external chat/channel once, maintain its roster, then replay message batches whenever needed.

curl -X POST https://myaise.com/v1/ingest/channels/ch_123/items \
  -H "Authorization: Bearer myaise_ing_..." \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "external_id": "msg-1001",
        "sender": "Ava",
        "sender_key": "user:42",
        "body": "The billing page is blank",
        "sent_at": "2026-06-12T09:18:00Z"
      },
      {
        "external_id": "msg-1002",
        "sender": "Support",
        "sender_key": "agent:7",
        "out": true,
        "body": "Can you send a screenshot?",
        "attachments": [
          {
            "mime": "image/png",
            "data_b64": "iVBORw0KGgoAAAANSUhEUg...",
            "width": 1280,
            "height": 720
          }
        ]
      }
    ],
    "cursor": { "chat_id": "42", "offset": 1002 }
  }'

The successful batch also emits an ingest_batch activity event into the Assist live feed.

Build your own collector #

Zendesk is the one hosted sync we ship. Chat platforms like Telegram don't allow a hosted service to read your conversations, so a collector for them runs on your side — a small always-on program that reads the chats you have access to and replays them into this API. An AI coding agent can build one in a sitting; the prompt below describes the collector we run ourselves (a Telegram tray app), and adapts to Slack, WhatsApp exports, or an internal tool by swapping the source.

Build me an always-on desktop collector (a menu-bar/tray app) that harvests
our Telegram support chats into MyAISE's ingest API.

Requirements:
- I sign into Telegram Web once inside a persistent session partition; the
  session survives restarts and never leaves my machine. MyAISE's servers
  must never contact Telegram directly.
- A small manager window lets me pick which chats to harvest.
- Every 30 minutes, and on a "Harvest now" click, extract new messages from
  the Telegram Web DOM and send them as idempotent batches to
  POST https://myaise.com/v1/ingest/channels/:id/items, after
  registering each chat once via POST /v1/ingest/channels with a stable
  external_key. Each message carries a stable external_id so replays upsert
  instead of duplicating.
- Authenticate with my source-bound ingest key (myaise_ing_..., minted at
  /dashboard/api-keys) sent as Authorization: Bearer. Store the key encrypted
  with the OS keychain; keep other config in a local config file.
- Track every sender seen; let me mark each one Staff or Customer in the
  manager, and sync the roster via PUT /v1/ingest/channels/:id/participants
  as a map of sender_key to "staff" or "customer". Send sender_key on each
  item and out: true for our own outbound messages.
- Persist a per-chat cursor in the batch payload so harvests resume where
  they left off.
- Read the API contract at https://myaise.com/docs/api#ingest-api first.
  Treat 409 ingest_paused as a stop signal (not a retry); replay the same
  batch on 502.

AI credits #

Every hosted AI feature — MyAISE answers, walkthrough generation, rule generation, the design kit, self-healing, knowledge mining from your support channels — draws from one per-workspace credit balance. Monthly grants reset each billing period; purchased top-ups never expire. Check the balance before batch work:

GET /v1/credits/balance

{
  "data": {
    "balance": { "granted": 640, "purchased": 500, "total": 1140 },
    "grant": { "amount": 1000, "period": "2026-08", "last_grant_period": "2026-08", "next_grant_at": "2026-09-01" },
    "low_balance": false,
    "topup_url": "https://myaise.com/dashboard/billing"
  }
}

Live-session hours #

Live viewer sessions draw on a separate monthly allowance of runtime hours: 10 hours on Solo, 20 hours per seat, pooled, on AI SE. A session is metered from the moment its runtime goes live until it ends. Time past the allowance is charged to the same credit balance at 50 credits per hour, prorated per started minute, when the session ends. Every session object carries the workspace's current-month usage as workspace.session_hours (used, included, period); once the allowance is spent and the balance cannot cover an hour, session creation returns 402 out_of_credits.

Usage audit #

Every charge is attributed to the workspace it was for and the entity that caused it — a viewer session, an assistant conversation, a learner job, a mining cluster, an API key. GET /v1/credits/usage?period=YYYY-MM returns the period's totals, the breakdown by action, a per-day series, and the session-hour meter; GET /v1/credits/transactions returns the ledger itself, newest first, with period, kind, action, source_type, source_id, end_user_ref, status (shadow, pending, settled, refunded), page and per_page (max 100) filters. A workspace key reads its workspace; a personal key reads the user's own account. The same view is on the dashboard at Usage, with CSV export.

GET /v1/credits/usage?period=2026-09

{
  "data": {
    "period": "2026-09",
    "scope": { "type": "team", "id": "…" },
    "credits_used": 1240, "refunded": 16, "net": 1224, "recorded": 0,
    "by_action": [ { "action": "agent_turn", "count": 120, "credits": 960, "refunded": 16, "net": 944 } ],
    "by_day": [ { "date": "2026-09-01", "credits": 0, "refunded": 0 }, … ],
    "session_hours": { "used_seconds": 5400, "included_seconds": 5400, "overage_seconds": 0, "overage_credits": 0, "allowance_seconds": 216000, "remaining_seconds": 210600 }
  }
}

GET /v1/credits/transactions?period=2026-09&source_type=viewer_session&source_id=…

{
  "data": [
    { "id": "…", "inserted_at": "2026-09-07T10:12:03Z", "kind": "deduction", "action": "agent_turn",
      "amount": -8, "balance_after": 2492, "team_id": "…",
      "source": { "type": "viewer_session", "id": "…" },
      "status": "settled", "end_user_ref": null, "acting_user": "se@example.com",
      "trace": { "model": "claude-sonnet-4-6", "prompt_tokens": 40612, "completion_tokens": 88 } }
  ],
  "page": { "page": 1, "per_page": 50, "total": 1, "total_pages": 1 }
}

Out of credits #

When the balance is exhausted, AI endpoints return 402 Payment Required with code: "out_of_credits", the current balance, the next grant date, and a top-up URL. Demos keep playing — serving a demo never spends credits — and non-AI endpoints are unaffected. Handle it by pausing AI calls until the next grant or topping up from the billing dashboard.

{
  "code":  "out_of_credits",
  "error": "Out of AI credits",
  "balance": { "granted": 0, "purchased": 0, "total": 0 },
  "grant": { "amount": 1000, "period": "2026-08", "next_grant_at": "2026-09-01" },
  "topup_url": "https://myaise.com/dashboard/billing"
}

The embedded assistant has a second, per-user 402 — user_allowance_exhausted — when one of your users has spent the allowance you gave them while your workspace still has credits. See per-user credits.

Endpoint reference #

Grouped by resource. Click any row to expand auth, request body, an example request, and a sample response. All requests carry Authorization: Bearer <api_key>. Use the narrow content:*, sessions:*, workspace:read, and owner-only webhooks:* scopes shown above; catch-all and plaintext-credential scopes do not exist.

curl https://myaise.com/v1/workspaces \
  -H "Authorization: Bearer $CAP_KEY"

{
  "data": [
    {
      "id": "ws_3f1c8e2a-...",
      "type": "team",
      "name": "Acme Inc",
      "slug": "acme",
      "created_at": "2026-05-01T12:00:00Z",
      "updated_at": "2026-05-20T09:30:00Z"
    }
  ]
}

curl https://myaise.com/v1/workspaces/ws_3f1c8e2a-... \
  -H "Authorization: Bearer $CAP_KEY"

{
  "data": {
    "id": "ws_3f1c8e2a-...",
    "type": "team",
    "name": "Acme Inc",
    "slug": "acme",
    "created_at": "2026-05-01T12:00:00Z",
    "updated_at": "2026-05-20T09:30:00Z"
  }
}

curl https://myaise.com/v1/workspaces/ws_3f1c.../api_keys \
  -H "Authorization: Bearer $CAP_KEY"

{
  "data": [
    {
      "id": "key_a1b2c3d4-...",
      "name": "CI key",
      "prefix": "cap_live_",
      "last4": "9f3a",
      "scopes": ["workspace:read", "content:read"],
      "rate_limit_per_minute": 120,
      "last_used_at": "2026-05-26T11:00:00Z",
      "revoked_at": null,
      "created_at": "2026-04-10T08:00:00Z"
    }
  ]
}

curl https://myaise.com/v1/projects \
  -H "Authorization: Bearer $CAP_KEY"

{
  "data": [
    {
      "id": "proj_e72b1a4c-...",
      "name": "Acme Demo",
      "description": "",
      "base_url": "https://app.acme.com",
      "version": 7,
      "rule_count": 4,
      "demo_count": 2,
      "created_at": "2026-05-01T12:00:00Z",
      "updated_at": "2026-05-20T09:30:00Z"
    }
  ]
}

curl https://myaise.com/v1/projects/proj_e72b... \
  -H "Authorization: Bearer $CAP_KEY"

{
  "data": {
    "id": "proj_e72b...", "name": "Acme Demo", "base_url": "https://app.acme.com",
    "version": 7, "rule_count": 4, "demo_count": 2,
    "rules": [{ "id": "8c1f...", "match": "/api/users", "type": "json", "index": 0 }],
    "demos": [{ "id": "demo_b3d2...", "name": "Onboarding", "steps": [] }]
  }
}

curl -X POST https://myaise.com/v1/projects \
  -H "Authorization: Bearer $CAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Demo","base_url":"https://app.acme.com"}'

{
  "data": {
    "id": "proj_e72b...", "name": "Acme Demo", "base_url": "https://app.acme.com",
    "version": 1, "rule_count": 0, "demo_count": 0, "rules": [], "demos": []
  }
}

curl -X PATCH https://myaise.com/v1/projects/proj_e72b... \
  -H "Authorization: Bearer $CAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"version":7,"name":"Acme Demo 2026"}'

{ "data": { "id": "proj_e72b...", "name": "Acme Demo 2026", "version": 8 } }

curl -X DELETE https://myaise.com/v1/projects/proj_e72b... \
  -H "Authorization: Bearer $CAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"version":8}'

204 No Content

curl https://myaise.com/v1/projects/proj_e72b.../rules \
  -H "Authorization: Bearer $CAP_KEY"

{
  "data": [
    { "id": "8c1f2a...", "match": "/api/users", "type": "json",
      "rewrite": "$.data[*].plan", "enabled": true, "index": 0 }
  ]
}

curl -X POST https://myaise.com/v1/projects/proj_e72b.../rules \
  -H "Authorization: Bearer $CAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"match":"/api/users","type":"json","rewrite":"$.plan","body":"enterprise"}'

{
  "data": {
    "rule": { "id": "8c1f2a...", "match": "/api/users", "type": "json" },
    "rules": [{ "id": "8c1f2a...", "index": 0 }]
  }
}

curl -X PATCH https://myaise.com/v1/projects/proj_e72b.../rules/8c1f2a... \
  -H "Authorization: Bearer $CAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'

{ "data": { "rule": { "id": "8c1f2a...", "enabled": false }, "rules": [ ... ] } }

curl -X DELETE https://myaise.com/v1/projects/proj_e72b.../rules/8c1f2a... \
  -H "Authorization: Bearer $CAP_KEY"

204 No Content

curl https://myaise.com/v1/projects/proj_e72b.../demos \
  -H "Authorization: Bearer $CAP_KEY"

{ "data": [ { "id": "demo_b3d2...", "name": "Onboarding", "theme_id": "glass", "steps": [] } ] }

curl -X POST https://myaise.com/v1/projects/proj_e72b.../demos \
  -H "Authorization: Bearer $CAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Onboarding","theme_id":"glass"}'

{
  "data": {
    "id": "demo_b3d2...", "name": "Onboarding", "theme_id": "glass",
    "exit_url": null, "auto_healing_enabled": false, "steps": [], "pre_demo_actions": []
  }
}

curl https://myaise.com/v1/demos/demo_b3d2... \
  -H "Authorization: Bearer $CAP_KEY"

{
  "data": {
    "id": "demo_b3d2...", "name": "Onboarding", "theme_id": "glass",
    "color_scheme": { "primary": "#7c3aed", "accent": "#a855f7" },
    "steps": [{ "id": "step_91fe...", "name": "Dashboard", "url_pattern": "/dashboard*",
                "overlays": [{ "id": "ov_4c8a...", "type": "tooltip" }] }],
    "pre_demo_actions": []
  }
}

curl -X PATCH https://myaise.com/v1/demos/demo_b3d2... \
  -H "Authorization: Bearer $CAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"exit_url":"https://acme.com/thanks"}'

{ "data": { "id": "demo_b3d2...", "exit_url": "https://acme.com/thanks" } }

curl -X DELETE https://myaise.com/v1/demos/demo_b3d2... \
  -H "Authorization: Bearer $CAP_KEY"

204 No Content

curl -X POST https://myaise.com/v1/demos/demo_b3d2.../clone \
  -H "Authorization: Bearer $CAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Onboarding — EU"}'

{ "data": { "id": "demo_9a77...", "name": "Onboarding — EU", "steps": [ ... ] } }

curl https://myaise.com/v1/demos/demo_b3d2.../steps \
  -H "Authorization: Bearer $CAP_KEY"

{ "data": [ { "id": "step_91fe...", "name": "Dashboard", "url_pattern": "/dashboard*", "overlays": [] } ] }

curl -X POST https://myaise.com/v1/demos/demo_b3d2.../steps \
  -H "Authorization: Bearer $CAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Dashboard","url_pattern":"/dashboard*"}'

{ "data": { "id": "step_91fe...", "name": "Dashboard", "url_pattern": "/dashboard*", "overlays": [], "entry_actions": [] } }

curl -X PATCH https://myaise.com/v1/demos/demo_b3d2.../steps/step_91fe... \
  -H "Authorization: Bearer $CAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url_pattern":"/reports*"}'

{ "data": { "id": "step_91fe...", "url_pattern": "/reports*" } }

curl -X DELETE https://myaise.com/v1/demos/demo_b3d2.../steps/step_91fe... \
  -H "Authorization: Bearer $CAP_KEY"

204 No Content

curl https://myaise.com/v1/steps/step_91fe.../overlays \
  -H "Authorization: Bearer $CAP_KEY"

{ "data": [ { "id": "ov_4c8a...", "type": "tooltip", "title": "Click here", "target_selector": "#new-report" } ] }

curl -X POST https://myaise.com/v1/steps/step_91fe.../overlays \
  -H "Authorization: Bearer $CAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"tooltip","title":"Click here","target_selector":"#new-report"}'

{ "data": { "id": "ov_4c8a...", "type": "tooltip", "title": "Click here", "target_selector": "#new-report" } }

curl -X PATCH https://myaise.com/v1/steps/step_91fe.../overlays/ov_4c8a... \
  -H "Authorization: Bearer $CAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"animation":"slide-up"}'

{ "data": { "id": "ov_4c8a...", "animation": "slide-up" } }

curl -X DELETE https://myaise.com/v1/steps/step_91fe.../overlays/ov_4c8a... \
  -H "Authorization: Bearer $CAP_KEY"

204 No Content

curl https://myaise.com/v1/demos/demo_b3d2.../pre_demo_actions \
  -H "Authorization: Bearer $CAP_KEY"

{ "data": [ { "id": "act_2f9b...", "type": "fill", "target": "#email", "value": "jane@acme.com" } ] }

curl -X POST https://myaise.com/v1/demos/demo_b3d2.../pre_demo_actions \
  -H "Authorization: Bearer $CAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"fill","target":"#email","value":"jane@acme.com"}'

{ "data": { "id": "act_2f9b...", "type": "fill", "target": "#email", "value": "jane@acme.com" } }

curl -X PATCH https://myaise.com/v1/demos/demo_b3d2.../pre_demo_actions/act_2f9b... \
  -H "Authorization: Bearer $CAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"delay_ms":500}'

{ "data": { "id": "act_2f9b...", "delay_ms": 500 } }

curl -X DELETE https://myaise.com/v1/demos/demo_b3d2.../pre_demo_actions/act_2f9b... \
  -H "Authorization: Bearer $CAP_KEY"

204 No Content

curl https://myaise.com/v1/steps/step_91fe.../entry_actions \
  -H "Authorization: Bearer $CAP_KEY"

{ "data": [ { "id": "act_7c1a...", "type": "click", "target": ".accept-cookies" } ] }

curl -X POST https://myaise.com/v1/steps/step_91fe.../entry_actions \
  -H "Authorization: Bearer $CAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"click","target":".accept-cookies"}'

{ "data": { "id": "act_7c1a...", "type": "click", "target": ".accept-cookies" } }

curl -X PATCH https://myaise.com/v1/steps/step_91fe.../entry_actions/act_7c1a... \
  -H "Authorization: Bearer $CAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"delay_ms":300}'

{ "data": { "id": "act_7c1a...", "delay_ms": 300 } }

curl -X DELETE https://myaise.com/v1/steps/step_91fe.../entry_actions/act_7c1a... \
  -H "Authorization: Bearer $CAP_KEY"

204 No Content

curl https://myaise.com/v1/demos/demo_b3d2.../assets \
  -H "Authorization: Bearer $CAP_KEY"

{
  "data": [
    {
      "id": "asset_5d1c...", "demo_id": "demo_b3d2...", "project_id": "proj_e72b...",
      "content_hash": "sha256:abc123...", "kind": "baseline_screenshot",
      "storage_url": "https://cdn.myaise.com/assets/abc123.png",
      "width": 1280, "height": 800, "byte_size": 48213, "mime_type": "image/png",
      "created_at": "2026-05-20T09:30:00Z"
    }
  ]
}

curl https://myaise.com/v1/demos/demo_b3d2.../assets/abc123... \
  -H "Authorization: Bearer $CAP_KEY"

{ "data": { "id": "asset_5d1c...", "content_hash": "sha256:abc123...", "storage_url": "https://cdn.myaise.com/assets/abc123.png" } }

curl https://myaise.com/v1/viewer/public_key \
  -H "Authorization: Bearer $CAP_KEY"

{
  "data": {
    "public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0B...\n-----END PUBLIC KEY-----\n",
    "key_type": "RSA",
    "algorithm": {
      "key_wrap": "RSA-OAEP", "hash": "SHA-256",
      "mgf1_hash": "SHA-256", "content": "AES-256-GCM"
    },
    "envelope_fields": ["encrypted_key", "iv", "ciphertext", "tag"],
    "iv_bytes": 12,
    "tag_bytes": 16,
    "encoding": "base64",
    "plaintext_schema": { "base_url": "https://…", "cookies": [], "headers": {} }
  }
}

curl -X POST https://myaise.com/v1/demos/demo_b3d2.../sessions \
  -H "Authorization: Bearer $CAP_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "prospect": { "name": "Jane", "email": "jane@acme.com" },
    "encrypted_payload": { "encrypted_key": "...", "iv": "...", "ciphertext": "...", "tag": "..." },
    "expires_in_seconds": 1200,
    "credit_budget": 100,
    "allowed_hosts": ["app.example.com", "*.app.example.com"]
  }'

{
  "data": {
    "id": "sess_7a2e...",
    "token": "v1_AbCd...",
    "status": "pending",
    "viewer_url": "https://joinlivedemo.com/view/v1_AbCd...",
    "expires_at": "2026-05-28T14:00:00Z",
    "expires_in_seconds": 1200,
    "credit_budget": 100,
    "credits_spent": 0,
    "allowed_hosts": ["app.example.com", "*.app.example.com"],
    "demo_id": "demo_b3d2...",
    "project_id": "proj_e72b...",
    "workspace": { "type": "team", "id": "ws_3f1c..." }
  }
}

curl -X POST https://myaise.com/v1/projects/proj_e72b.../assistant_sessions \
  -H "Authorization: Bearer $CAP_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"prospect":{"name":"Jane"},"encrypted_payload":{"encrypted_key":"...","iv":"...","ciphertext":"...","tag":"..."}}'

{
  "data": {
    "id": "sess_7a2e...", "token": "v1_AbCd...", "status": "pending",
    "viewer_url": "https://joinlivedemo.com/view/v1_AbCd...",
    "expires_at": "2026-05-28T14:00:00Z", "project_id": "proj_e72b...",
    "workspace": { "type": "team", "id": "ws_3f1c..." }
  }
}

curl "https://myaise.com/v1/workspaces/ws_3f1c.../sessions?status=active" \
  -H "Authorization: Bearer $CAP_KEY"

{
  "data": [
    {
      "id": "sess_7a2e...", "status": "active", "demo_id": "demo_b3d2...",
      "token_prefix": "v1_AbCd", "share_link_available": false,
      "workspace": { "type": "team", "id": "ws_3f1c..." },
      "prospect": { "name": "Jane", "email": "jane@acme.com" },
      "demo_status": "in_progress", "demo_step_index": 2,
      "machine_id": "d8...", "warming_state": "ready",
      "expires_at": "2026-05-28T14:00:00Z", "created_at": "2026-05-28T13:00:00Z"
    }
  ]
}

curl https://myaise.com/v1/demo_sessions/sess_7a2e... \
  -H "Authorization: Bearer $CAP_KEY"

{
  "data": {
    "id": "sess_7a2e...", "status": "active",
    "token_prefix": "v1_AbCd", "share_link_available": false,
    "workspace": { "type": "team", "id": "ws_3f1c..." },
    "project_id": "proj_e72b...", "demo_id": "demo_b3d2...",
    "prospect": { "name": "Jane", "email": "jane@acme.com", "company": "Acme", "metadata": {} },
    "current_url": "https://app.acme.com/dashboard",
    "demo_status": "in_progress", "demo_step_index": 2,
    "demo_started_at": "2026-05-28T13:01:00Z", "demo_completed_at": null,
    "credit_budget": 100, "credits_spent": 34,
    "allowed_hosts": ["app.example.com", "*.app.example.com"],
    "end_reason": null, "ended_at": null,
    "machine_id": "d8...", "warming_state": "ready",
    "warming_completed": 4, "warming_total": 4,
    "expires_at": "2026-05-28T14:00:00Z"
  }
}

curl -X DELETE https://myaise.com/v1/demo_sessions/sess_7a2e... \
  -H "Authorization: Bearer $CAP_KEY"

{ "ok": true }

curl -X POST https://myaise.com/v1/assist/messages \
  -H "Authorization: Bearer $CAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Which object backs the account settings form?",
    "origin": "customer-app-mcp-planner"
  }'

{
  "data": {
    "conversation_id": "9f4d2c1b-...",
    "conversation_created": true,
    "message": {
      "id": "3e533c0a-...",
      "role": "assistant",
      "content": "Open Campaigns and verify the routing target is active."
    },
    "answer_gap": false,
    "suggested_walkthroughs": [],
    "wants_walkthrough_generation": false,
    "retrieval_refs": {
      "solution_ids": ["8c1a..."],
      "chunk_ids": [],
      "groundtruth_ids": []
    }
  }
}

curl -X POST https://myaise.com/v1/assist/conversations \
  -H "Authorization: Bearer $CAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origin":"customer-app-mcp-planner"}'

{
  "data": {
    "conversation_id": "9f4d2c1b-...",
    "status": "active",
    "origin": "customer-app-mcp-planner"
  }
}

curl -X POST https://myaise.com/v1/assist/conversations/9f4d2c1b-.../messages \
  -H "Authorization: Bearer $CAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"What should I check first?"}'

{
  "data": {
    "conversation_id": "9f4d2c1b-...",
    "conversation_created": false,
    "message": {
      "id": "3e533c0a-...",
      "role": "assistant",
      "content": "Open Campaigns and verify the routing target is active."
    },
    "answer_gap": false,
    "suggested_walkthroughs": [],
    "wants_walkthrough_generation": false,
    "retrieval_refs": {
      "solution_ids": ["8c1a..."],
      "chunk_ids": [],
      "groundtruth_ids": []
    }
  }
}

curl https://myaise.com/v1/embed/end_users/user_8842/credits \
  -H "Authorization: Bearer $CAP_KEY"

{
  "data": {
    "end_user_ref": "user_8842",
    "credit_allowance": 300,
    "allowance_source": "claim",
    "credit_period": "monthly",
    "period_key": "2026-09",
    "credits_spent": 90,
    "credits_remaining": 210,
    "resets_at": "2026-10-01T00:00:00Z",
    "out_of_credits": false,
    "last_seen_at": "2026-09-04T18:20:11Z",
    "out_of_credits_message": "You've used this month's AI credits.",
    "out_of_credits_url": "https://app.example.com/billing/credits"
  }
}

curl -X PUT https://myaise.com/v1/embed/end_users/user_8842/credits \
  -H "Authorization: Bearer $CAP_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"credit_allowance": 500, "credit_period": "monthly", "reset_spent": true}'

# a purchase: send the payment id as the Idempotency-Key so a retry never grants twice
curl -X PUT https://myaise.com/v1/embed/end_users/user_8842/credits \
  -H "Authorization: Bearer $CAP_KEY" \
  -H 'Idempotency-Key: pay_01J9X…' -H 'Content-Type: application/json' \
  -d '{"add_credits": 50}'

{
  "data": {
    "end_user_ref": "user_8842",
    "credit_allowance": 500,
    "allowance_source": "api",
    "credit_period": "monthly",
    "period_key": "2026-09",
    "credits_spent": 0,
    "extra_credits": 0,
    "credits_remaining": 500,
    "resets_at": "2026-10-01T00:00:00Z",
    "out_of_credits": false,
    "last_seen_at": "2026-09-04T18:20:11Z",
    "out_of_credits_message": "You've used this month's AI credits.",
    "out_of_credits_url": "https://app.example.com/billing/credits"
  }
}

curl -X POST https://myaise.com/v1/embed/end_users/user_8842/revoke \
  -H "Authorization: Bearer $CAP_KEY"

{
  "data": {
    "end_user_ref": "user_8842",
    "revoked_at": "2026-10-16T14:02:11.418220Z",
    "sessions_ended": 2,
    "connections_removed": 1
  }
}

curl -X POST https://myaise.com/v1/customer_app/mcp_handoffs \
  -H "Authorization: Bearer $CAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint_url": "https://mcp.customer-app.example/rpc",
    "access_token": "customer_app_mcp_token_...",
    "expires_at": "2026-06-26T16:00:00Z",
    "app_ref": "supportdesk",
    "account_id": "acct_123",
    "scopes": ["read_only"],
    "tool_catalog": [{"name":"records.get","readOnlyHint":true}],
    "myaise_conversation_id": "9f4d2c1b-...",
    "viewer_session_id": "sess_7a2e..."
  }'

{
  "data": {
    "handoff_ref": "customer_app_handoff_abc123",
    "expires_at": "2026-06-26T16:00:00Z",
    "viewer_session_id": "sess_7a2e...",
    "connected": true,
    "credential_handling": "server-side only",
    "customer_app": {
      "app_ref": "supportdesk",
      "account_id": "acct_123",
      "tool_count": 1,
      "read_only": true
    }
  }
}

curl -X POST https://myaise.com/v1/whitelabel/theme_verifications \
  -H "Authorization: Bearer $CAP_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "css": ":root { --brand: #4f46e5; }",
    "preview_html": "<!doctype html><html><body>Preview</body></html>",
    "external_ref": "theme_123"
  }'

{
  "data": {
    "id": "6d8d4f2a-...",
    "external_ref": "theme_123",
    "status": "queued",
    "findings": [],
    "cleared_css": null
  }
}

curl https://myaise.com/v1/whitelabel/theme_verifications/6d8d4f2a-... \
  -H "Authorization: Bearer $CAP_KEY"

{
  "data": {
    "id": "6d8d4f2a-...",
    "external_ref": "theme_123",
    "status": "approved",
    "findings": [],
    "cleared_css": ":root { --brand: #4f46e5; }"
  }
}

curl -X POST https://myaise.com/v1/whitelabel/theme_verifications \
  -H "Authorization: Bearer $CAP_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "css": ":root { --brand: #4f46e5; }",
    "preview_html": "<!doctype html><html><body>Preview</body></html>",
    "external_ref": "theme_123"
  }'

{
  "data": {
    "id": "6d8d4f2a-...",
    "external_ref": "theme_123",
    "status": "queued",
    "findings": [],
    "cleared_css": null
  }
}

curl https://myaise.com/v1/whitelabel/theme_verifications/6d8d4f2a-... \
  -H "Authorization: Bearer $CAP_KEY"

{
  "data": {
    "id": "6d8d4f2a-...",
    "external_ref": "theme_123",
    "status": "approved",
    "findings": [],
    "cleared_css": ":root { --brand: #4f46e5; }"
  }
}

curl https://myaise.com/v1/workspaces/ws_3f1c.../blocked_paths \
  -H "Authorization: Bearer $CAP_KEY"

{ "data": [ { "id": "bp_77aa...", "pattern": "/admin/*", "status_code": 403, "enabled": true, "locked": false } ] }

curl -X POST https://myaise.com/v1/workspaces/ws_3f1c.../blocked_paths \
  -H "Authorization: Bearer $CAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pattern":"/admin/*","status_code":403}'

{ "data": { "id": "bp_77aa...", "pattern": "/admin/*", "status_code": 403, "enabled": true, "locked": false } }

curl -X PATCH https://myaise.com/v1/workspaces/ws_3f1c.../blocked_paths/bp_77aa... \
  -H "Authorization: Bearer $CAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'

{ "data": { "id": "bp_77aa...", "enabled": false } }

curl -X DELETE https://myaise.com/v1/workspaces/ws_3f1c.../blocked_paths/bp_77aa... \
  -H "Authorization: Bearer $CAP_KEY"

204 No Content

curl https://myaise.com/v1/workspaces/ws_3f1c.../webhooks \
  -H "Authorization: Bearer $CAP_KEY"

{
  "data": [
    {
      "id": "wh_9c3d...", "url": "https://acme.com/hooks", "active": true,
      "events": ["session.created", "session.demo_completed"],
      "project_ids": ["proj_e72b..."], "demo_ids": [],
      "signing_secret_prefix": "whsec_ab12cd", "consecutive_failures": 0,
      "last_success_at": "2026-05-27T10:00:00Z", "last_failure_at": null
    }
  ]
}

curl -X POST https://myaise.com/v1/workspaces/ws_3f1c.../webhooks \
  -H "Authorization: Bearer $CAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://acme.com/hooks","events":["session.created"]}'

{
  "data": {
    "id": "wh_9c3d...", "url": "https://acme.com/hooks", "active": true,
    "events": ["session.created"],
    "signing_secret": "whsec_ab12cd...FULL_SECRET_SHOWN_ONCE",
    "signing_secret_prefix": "whsec_ab12cd"
  }
}

curl -X PATCH https://myaise.com/v1/workspaces/ws_3f1c.../webhooks/wh_9c3d... \
  -H "Authorization: Bearer $CAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active":false}'

{ "data": { "id": "wh_9c3d...", "active": false } }

curl -X DELETE https://myaise.com/v1/workspaces/ws_3f1c.../webhooks/wh_9c3d... \
  -H "Authorization: Bearer $CAP_KEY"

204 No Content

curl -X POST https://myaise.com/v1/workspaces/ws_3f1c.../webhooks/wh_9c3d.../test \
  -H "Authorization: Bearer $CAP_KEY"

{
  "data": {
    "id": "del_b81a...", "webhook_id": "wh_9c3d...", "event_type": "session.created",
    "status": "delivered", "attempt": 1, "response_status": 200, "created_at": "..."
  }
}

curl https://myaise.com/v1/workspaces/ws_3f1c.../webhook_deliveries \
  -H "Authorization: Bearer $CAP_KEY"

{
  "data": [
    {
      "id": "del_b81a...", "webhook_id": "wh_9c3d...", "event_type": "session.demo_completed",
      "status": "delivered", "attempt": 1, "response_status": 200,
      "delivered_at": "2026-05-27T10:00:01Z", "next_attempt_at": null
    }
  ]
}

curl https://myaise.com/v1/webhook_deliveries/del_b81a... \
  -H "Authorization: Bearer $CAP_KEY"

{
  "data": {
    "id": "del_b81a...", "webhook_id": "wh_9c3d...", "event_type": "session.demo_completed",
    "status": "delivered", "attempt": 1, "response_status": 200,
    "payload": { "type": "session.demo_completed", "data": { "session_id": "sess_7a2e..." } },
    "response_body": null, "error_message": null,
    "signature": "sha256=9f86d0818..."
  }
}

curl -X POST https://myaise.com/v1/webhook_deliveries/del_b81a.../redrive \
  -H "Authorization: Bearer $CAP_KEY"

{ "data": { "id": "del_b81a...", "status": "pending", "attempt": 2, "next_attempt_at": "2026-05-28T13:05:00Z" } }

curl https://myaise.com/v1/event_types \
  -H "Authorization: Bearer $CAP_KEY"

{
  "data": [
    { "type": "session.created", "category": "session",
      "description": "A new viewer session was created via the API." },
    { "type": "session.demo_completed", "category": "session",
      "description": "The prospect reached the end of the demo." },
    { "type": "demo.drift_detected", "category": "demo_authoring",
      "description": "The validator found drift in this demo." }
  ]
}

Errors #

Error responses use a Stripe-shape envelope so existing client libraries can be reused.

{
  "error": {
    "type":       "validation_error",
    "message":    "One or more fields are invalid.",
    "details": [
      { "path": "demos.0.steps", "message": "must be a list" }
    ],
    "request_id": "F7xa..."
  }
}

Status codes #

Found a typo? Drop us a note at docs@myaise.com · API status: status.myaise.com