Agent Embed

Embed Context Read

GET/api/v1/embed/context

Service-to-service read for the 1.2 gateway plugin. Auth is ``X-Admin-Key`` (the plugin, like skills-meta). ``flow_id`` + ``url`` are supplied server-side by the plugin from ``ctx`` — never the LLM for ``flow_id``.

Errors

Code	When	What to do
422	Validation Error	—

Request

curl "https://app.opvs.ai/api/v1/embed/context" \
  -H "Authorization: Bearer $OPVS_TOKEN"

import os
import requests

r = requests.request(
    "GET",
    "https://app.opvs.ai/api/v1/embed/context",
    headers={"Authorization": f"Bearer {os.environ['OPVS_TOKEN']}"},
)
r.raise_for_status()
print(r.json())

const r = await fetch("https://app.opvs.ai/api/v1/embed/context", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.OPVS_TOKEN}` },
});
if (!r.ok) throw new Error(String(r.status));
console.log(await r.json());

req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/embed/context", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("OPVS_TOKEN"))
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()

Embed Context Upload

POST/api/v1/embed/context

Store the visitor's current page content for scoped-pull by the agent.

Errors

Code	When	What to do
422	Validation Error	—

Request

curl -X POST "https://app.opvs.ai/api/v1/embed/context" \
  -H "Authorization: Bearer $OPVS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

import os
import requests

r = requests.request(
    "POST",
    "https://app.opvs.ai/api/v1/embed/context",
    headers={"Authorization": f"Bearer {os.environ['OPVS_TOKEN']}", "Content-Type": "application/json"},
    data='{}',
)
r.raise_for_status()
print(r.json())

const r = await fetch("https://app.opvs.ai/api/v1/embed/context", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.OPVS_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
if (!r.ok) throw new Error(String(r.status));
console.log(await r.json());

req, _ := http.NewRequest("POST", "https://app.opvs.ai/api/v1/embed/context", strings.NewReader(`{}`))
req.Header.Set("Authorization", "Bearer "+os.Getenv("OPVS_TOKEN"))
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()

Embed Preflight

OPTIONS/api/v1/embed/context

Scoped-CORS preflight responder. (The global CORSMiddleware intercepts preflights for origins outside CORS_ORIGINS before this runs — same as embed_mock; an external origin's browser POST still needs CORS_ORIGINS at deploy, while the SSE GET is a simple request served by reflection alone.)

Request

curl -X OPTIONS "https://app.opvs.ai/api/v1/embed/context" \
  -H "Authorization: Bearer $OPVS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

import os
import requests

r = requests.request(
    "OPTIONS",
    "https://app.opvs.ai/api/v1/embed/context",
    headers={"Authorization": f"Bearer {os.environ['OPVS_TOKEN']}", "Content-Type": "application/json"},
    data='{}',
)
r.raise_for_status()
print(r.json())

const r = await fetch("https://app.opvs.ai/api/v1/embed/context", {
  method: "OPTIONS",
  headers: { Authorization: `Bearer ${process.env.OPVS_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
if (!r.ok) throw new Error(String(r.status));
console.log(await r.json());

req, _ := http.NewRequest("OPTIONS", "https://app.opvs.ai/api/v1/embed/context", strings.NewReader(`{}`))
req.Header.Set("Authorization", "Bearer "+os.Getenv("OPVS_TOKEN"))
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()

Embed Sse

GET/api/v1/embed/sse

Open the AI SDK response stream for a validated session token. When a ``message`` is supplied the agent's reply to it streams; otherwise just an open frame so the EventSource handshake completes. ``page_url`` (optional) grounds the turn to the visitor's current page (M2.1).

Errors

Code	When	What to do
422	Validation Error	—

Request

curl "https://app.opvs.ai/api/v1/embed/sse" \
  -H "Authorization: Bearer $OPVS_TOKEN"

import os
import requests

r = requests.request(
    "GET",
    "https://app.opvs.ai/api/v1/embed/sse",
    headers={"Authorization": f"Bearer {os.environ['OPVS_TOKEN']}"},
)
r.raise_for_status()
print(r.json())

const r = await fetch("https://app.opvs.ai/api/v1/embed/sse", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.OPVS_TOKEN}` },
});
if (!r.ok) throw new Error(String(r.status));
console.log(await r.json());

req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/embed/sse", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("OPVS_TOKEN"))
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()

Embed Preflight

OPTIONS/api/v1/embed/sse

Request

curl -X OPTIONS "https://app.opvs.ai/api/v1/embed/sse" \
  -H "Authorization: Bearer $OPVS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

import os
import requests

r = requests.request(
    "OPTIONS",
    "https://app.opvs.ai/api/v1/embed/sse",
    headers={"Authorization": f"Bearer {os.environ['OPVS_TOKEN']}", "Content-Type": "application/json"},
    data='{}',
)
r.raise_for_status()
print(r.json())

const r = await fetch("https://app.opvs.ai/api/v1/embed/sse", {
  method: "OPTIONS",
  headers: { Authorization: `Bearer ${process.env.OPVS_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
if (!r.ok) throw new Error(String(r.status));
console.log(await r.json());

req, _ := http.NewRequest("OPTIONS", "https://app.opvs.ai/api/v1/embed/sse", strings.NewReader(`{}`))
req.Header.Set("Authorization", "Bearer "+os.Getenv("OPVS_TOKEN"))
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()

Embed Turn

POST/api/v1/embed/turn

Run a user/widget turn and stream the agent's reply as AI SDK frames.

Errors

Code	When	What to do
422	Validation Error	—

Request

curl -X POST "https://app.opvs.ai/api/v1/embed/turn" \
  -H "Authorization: Bearer $OPVS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

import os
import requests

r = requests.request(
    "POST",
    "https://app.opvs.ai/api/v1/embed/turn",
    headers={"Authorization": f"Bearer {os.environ['OPVS_TOKEN']}", "Content-Type": "application/json"},
    data='{}',
)
r.raise_for_status()
print(r.json())

const r = await fetch("https://app.opvs.ai/api/v1/embed/turn", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.OPVS_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
if (!r.ok) throw new Error(String(r.status));
console.log(await r.json());

req, _ := http.NewRequest("POST", "https://app.opvs.ai/api/v1/embed/turn", strings.NewReader(`{}`))
req.Header.Set("Authorization", "Bearer "+os.Getenv("OPVS_TOKEN"))
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()

Embed Preflight

OPTIONS/api/v1/embed/turn

Request

curl -X OPTIONS "https://app.opvs.ai/api/v1/embed/turn" \
  -H "Authorization: Bearer $OPVS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

import os
import requests

r = requests.request(
    "OPTIONS",
    "https://app.opvs.ai/api/v1/embed/turn",
    headers={"Authorization": f"Bearer {os.environ['OPVS_TOKEN']}", "Content-Type": "application/json"},
    data='{}',
)
r.raise_for_status()
print(r.json())

const r = await fetch("https://app.opvs.ai/api/v1/embed/turn", {
  method: "OPTIONS",
  headers: { Authorization: `Bearer ${process.env.OPVS_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
if (!r.ok) throw new Error(String(r.status));
console.log(await r.json());

req, _ := http.NewRequest("OPTIONS", "https://app.opvs.ai/api/v1/embed/turn", strings.NewReader(`{}`))
req.Header.Set("Authorization", "Bearer "+os.Getenv("OPVS_TOKEN"))
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()

Embed Session

POST/api/v1/embed/session

Mint a public embed session token for a registered flow + origin.

Errors

Code	When	What to do
422	Validation Error	—

Request

curl -X POST "https://app.opvs.ai/api/v1/embed/session" \
  -H "Authorization: Bearer $OPVS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

import os
import requests

r = requests.request(
    "POST",
    "https://app.opvs.ai/api/v1/embed/session",
    headers={"Authorization": f"Bearer {os.environ['OPVS_TOKEN']}", "Content-Type": "application/json"},
    data='{}',
)
r.raise_for_status()
print(r.json())

const r = await fetch("https://app.opvs.ai/api/v1/embed/session", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.OPVS_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
if (!r.ok) throw new Error(String(r.status));
console.log(await r.json());

req, _ := http.NewRequest("POST", "https://app.opvs.ai/api/v1/embed/session", strings.NewReader(`{}`))
req.Header.Set("Authorization", "Bearer "+os.Getenv("OPVS_TOKEN"))
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()

Embed Preflight

OPTIONS/api/v1/embed/session

Request

curl -X OPTIONS "https://app.opvs.ai/api/v1/embed/session" \
  -H "Authorization: Bearer $OPVS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

import os
import requests

r = requests.request(
    "OPTIONS",
    "https://app.opvs.ai/api/v1/embed/session",
    headers={"Authorization": f"Bearer {os.environ['OPVS_TOKEN']}", "Content-Type": "application/json"},
    data='{}',
)
r.raise_for_status()
print(r.json())

const r = await fetch("https://app.opvs.ai/api/v1/embed/session", {
  method: "OPTIONS",
  headers: { Authorization: `Bearer ${process.env.OPVS_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
if (!r.ok) throw new Error(String(r.status));
console.log(await r.json());

req, _ := http.NewRequest("OPTIONS", "https://app.opvs.ai/api/v1/embed/session", strings.NewReader(`{}`))
req.Header.Set("Authorization", "Bearer "+os.Getenv("OPVS_TOKEN"))
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()

Embed Bind

POST/api/v1/embed/bind

Client-facing hire→bind: turn a catalog pick into a live bound flow.

Errors

Code	When	What to do
422	Validation Error	—

Request

curl -X POST "https://app.opvs.ai/api/v1/embed/bind" \
  -H "Authorization: Bearer $OPVS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

import os
import requests

r = requests.request(
    "POST",
    "https://app.opvs.ai/api/v1/embed/bind",
    headers={"Authorization": f"Bearer {os.environ['OPVS_TOKEN']}", "Content-Type": "application/json"},
    data='{}',
)
r.raise_for_status()
print(r.json())

const r = await fetch("https://app.opvs.ai/api/v1/embed/bind", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.OPVS_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
if (!r.ok) throw new Error(String(r.status));
console.log(await r.json());

req, _ := http.NewRequest("POST", "https://app.opvs.ai/api/v1/embed/bind", strings.NewReader(`{}`))
req.Header.Set("Authorization", "Bearer "+os.Getenv("OPVS_TOKEN"))
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()

Embed Bind Update Origins

PATCH/api/v1/embed/bind/{flow_id}

Update a binding's origin allowlist (PAT-auth, brand-scoped).

Errors

Code	When	What to do
422	Validation Error	—

Request

curl -X PATCH "https://app.opvs.ai/api/v1/embed/bind/{flow_id}" \
  -H "Authorization: Bearer $OPVS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

import os
import requests

r = requests.request(
    "PATCH",
    "https://app.opvs.ai/api/v1/embed/bind/{flow_id}",
    headers={"Authorization": f"Bearer {os.environ['OPVS_TOKEN']}", "Content-Type": "application/json"},
    data='{}',
)
r.raise_for_status()
print(r.json())

const r = await fetch("https://app.opvs.ai/api/v1/embed/bind/{flow_id}", {
  method: "PATCH",
  headers: { Authorization: `Bearer ${process.env.OPVS_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
if (!r.ok) throw new Error(String(r.status));
console.log(await r.json());

req, _ := http.NewRequest("PATCH", "https://app.opvs.ai/api/v1/embed/bind/{flow_id}", strings.NewReader(`{}`))
req.Header.Set("Authorization", "Bearer "+os.Getenv("OPVS_TOKEN"))
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()

Embed Unbind

DELETE/api/v1/embed/bind/{flow_id}

Unbind a flow — soft-disable the binding (PAT-auth, brand-scoped).

Errors

Code	When	What to do
422	Validation Error	—

Request

curl -X DELETE "https://app.opvs.ai/api/v1/embed/bind/{flow_id}" \
  -H "Authorization: Bearer $OPVS_TOKEN"

import os
import requests

r = requests.request(
    "DELETE",
    "https://app.opvs.ai/api/v1/embed/bind/{flow_id}",
    headers={"Authorization": f"Bearer {os.environ['OPVS_TOKEN']}"},
)
r.raise_for_status()
print(r.json())

const r = await fetch("https://app.opvs.ai/api/v1/embed/bind/{flow_id}", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${process.env.OPVS_TOKEN}` },
});
if (!r.ok) throw new Error(String(r.status));
console.log(await r.json());

req, _ := http.NewRequest("DELETE", "https://app.opvs.ai/api/v1/embed/bind/{flow_id}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("OPVS_TOKEN"))
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()

Embed Catalog Bind

POST/api/v1/embed/catalog/bind

Provision (or reuse) the platform-owned demo hire for a catalog product.

Errors

Code	When	What to do
422	Validation Error	—

Request

curl -X POST "https://app.opvs.ai/api/v1/embed/catalog/bind" \
  -H "Authorization: Bearer $OPVS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

import os
import requests

r = requests.request(
    "POST",
    "https://app.opvs.ai/api/v1/embed/catalog/bind",
    headers={"Authorization": f"Bearer {os.environ['OPVS_TOKEN']}", "Content-Type": "application/json"},
    data='{}',
)
r.raise_for_status()
print(r.json())

const r = await fetch("https://app.opvs.ai/api/v1/embed/catalog/bind", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.OPVS_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
if (!r.ok) throw new Error(String(r.status));
console.log(await r.json());

req, _ := http.NewRequest("POST", "https://app.opvs.ai/api/v1/embed/catalog/bind", strings.NewReader(`{}`))
req.Header.Set("Authorization", "Bearer "+os.Getenv("OPVS_TOKEN"))
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()

Embed Catalog Session

POST/api/v1/embed/catalog/session

PUBLIC. Mint a demo session token for a profile that already has a binding.

Errors

Code	When	What to do
422	Validation Error	—

Request

curl -X POST "https://app.opvs.ai/api/v1/embed/catalog/session" \
  -H "Authorization: Bearer $OPVS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

import os
import requests

r = requests.request(
    "POST",
    "https://app.opvs.ai/api/v1/embed/catalog/session",
    headers={"Authorization": f"Bearer {os.environ['OPVS_TOKEN']}", "Content-Type": "application/json"},
    data='{}',
)
r.raise_for_status()
print(r.json())

const r = await fetch("https://app.opvs.ai/api/v1/embed/catalog/session", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.OPVS_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
if (!r.ok) throw new Error(String(r.status));
console.log(await r.json());

req, _ := http.NewRequest("POST", "https://app.opvs.ai/api/v1/embed/catalog/session", strings.NewReader(`{}`))
req.Header.Set("Authorization", "Bearer "+os.Getenv("OPVS_TOKEN"))
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()

Did this answer your question?

Need help? support@opvs.aiChangelog LLM? Read llms.txt