Agents

List Workflows

GET/api/v1/agents/workflows

List all workflows for the current brand.

Errors

Code	When	What to do
422	Validation Error	—

Request

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

import os
import requests

r = requests.request(
    "GET",
    "https://app.opvs.ai/api/v1/agents/workflows",
    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/agents/workflows", {
  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/agents/workflows", 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()

Create Workflow

POST/api/v1/agents/workflows

Create a new workflow.

Errors

Code	When	What to do
422	Validation Error	—

Request

curl -X POST "https://app.opvs.ai/api/v1/agents/workflows" \
  -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/agents/workflows",
    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/agents/workflows", {
  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/agents/workflows", 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()

Get Workflow

GET/api/v1/agents/workflows/{workflow_id}

Get a single workflow with full canvas state.

Errors

Code	When	What to do
422	Validation Error	—

Request

curl "https://app.opvs.ai/api/v1/agents/workflows/{workflow_id}" \
  -H "Authorization: Bearer $OPVS_TOKEN"

import os
import requests

r = requests.request(
    "GET",
    "https://app.opvs.ai/api/v1/agents/workflows/{workflow_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/agents/workflows/{workflow_id}", {
  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/agents/workflows/{workflow_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()

Update Workflow

PATCH/api/v1/agents/workflows/{workflow_id}

Update a workflow (name, description, canvas state, status, etc.).

Errors

Code	When	What to do
422	Validation Error	—

Request

curl -X PATCH "https://app.opvs.ai/api/v1/agents/workflows/{workflow_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/agents/workflows/{workflow_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/agents/workflows/{workflow_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/agents/workflows/{workflow_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()

Delete Workflow

DELETE/api/v1/agents/workflows/{workflow_id}

Delete a workflow.

Errors

Code	When	What to do
422	Validation Error	—

Request

curl -X DELETE "https://app.opvs.ai/api/v1/agents/workflows/{workflow_id}" \
  -H "Authorization: Bearer $OPVS_TOKEN"

import os
import requests

r = requests.request(
    "DELETE",
    "https://app.opvs.ai/api/v1/agents/workflows/{workflow_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/agents/workflows/{workflow_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/agents/workflows/{workflow_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()

Deploy Workflow

POST/api/v1/agents/workflows/{workflow_id}/deploy

Deploy a workflow — activates it and (in the future) syncs to the Management API to create/update the OpenClaw agent.

Errors

Code	When	What to do
422	Validation Error	—

Request

curl -X POST "https://app.opvs.ai/api/v1/agents/workflows/{workflow_id}/deploy" \
  -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/agents/workflows/{workflow_id}/deploy",
    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/agents/workflows/{workflow_id}/deploy", {
  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/agents/workflows/{workflow_id}/deploy", 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()

List Personas

GET/api/v1/agents/personas

List all personas for the current brand.

Errors

Code	When	What to do
422	Validation Error	—

Request

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

import os
import requests

r = requests.request(
    "GET",
    "https://app.opvs.ai/api/v1/agents/personas",
    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/agents/personas", {
  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/agents/personas", 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()

Create Persona

POST/api/v1/agents/personas

Create a new persona.

Errors

Code	When	What to do
422	Validation Error	—

Request

curl -X POST "https://app.opvs.ai/api/v1/agents/personas" \
  -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/agents/personas",
    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/agents/personas", {
  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/agents/personas", 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()

Get Persona

GET/api/v1/agents/personas/{persona_id}

Get a single persona with full details, visuals, and voice.

Errors

Code	When	What to do
422	Validation Error	—

Request

curl "https://app.opvs.ai/api/v1/agents/personas/{persona_id}" \
  -H "Authorization: Bearer $OPVS_TOKEN"

import os
import requests

r = requests.request(
    "GET",
    "https://app.opvs.ai/api/v1/agents/personas/{persona_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/agents/personas/{persona_id}", {
  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/agents/personas/{persona_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()

Update Persona

PATCH/api/v1/agents/personas/{persona_id}

Auto-save update for a persona. JSONB fields are merged (not replaced) — only provided keys are updated. If an own persona is deployed, syncs workspace files to the gateway as a background task. A live hire's vendor files are never regenerated by customer edits.

Errors

Code	When	What to do
422	Validation Error	—

Request

curl -X PATCH "https://app.opvs.ai/api/v1/agents/personas/{persona_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/agents/personas/{persona_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/agents/personas/{persona_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/agents/personas/{persona_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()

Delete Persona

DELETE/api/v1/agents/personas/{persona_id}

Delete a persona, unless a live hire still depends on it.

Errors

Code	When	What to do
422	Validation Error	—

Request

curl -X DELETE "https://app.opvs.ai/api/v1/agents/personas/{persona_id}" \
  -H "Authorization: Bearer $OPVS_TOKEN"

import os
import requests

r = requests.request(
    "DELETE",
    "https://app.opvs.ai/api/v1/agents/personas/{persona_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/agents/personas/{persona_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/agents/personas/{persona_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()

Get Persona Skills

GET/api/v1/agents/personas/{persona_id}/skills

Return the configured skills of one own persona in this brand.

Errors

Code	When	What to do
422	Validation Error	—

Request

curl "https://app.opvs.ai/api/v1/agents/personas/{persona_id}/skills" \
  -H "Authorization: Bearer $OPVS_TOKEN"

import os
import requests

r = requests.request(
    "GET",
    "https://app.opvs.ai/api/v1/agents/personas/{persona_id}/skills",
    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/agents/personas/{persona_id}/skills", {
  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/agents/personas/{persona_id}/skills", 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()

Retire Personas Bulk

POST/api/v1/agents/personas/retire

Clear agents out of all five stores at once — reversibly, or for good.

Errors

Code	When	What to do
422	Validation Error	—

Request

curl -X POST "https://app.opvs.ai/api/v1/agents/personas/retire" \
  -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/agents/personas/retire",
    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/agents/personas/retire", {
  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/agents/personas/retire", 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()

Deploy Persona

POST/api/v1/agents/personas/{persona_id}/deploy

Deploy a persona to the OpenClaw gateway.

Errors

Code	When	What to do
422	Validation Error	—

Request

curl -X POST "https://app.opvs.ai/api/v1/agents/personas/{persona_id}/deploy" \
  -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/agents/personas/{persona_id}/deploy",
    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/agents/personas/{persona_id}/deploy", {
  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/agents/personas/{persona_id}/deploy", 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()

Undeploy Persona

POST/api/v1/agents/personas/{persona_id}/undeploy

Remove a persona's agent from the OpenClaw gateway.

Errors

Code	When	What to do
422	Validation Error	—

Request

curl -X POST "https://app.opvs.ai/api/v1/agents/personas/{persona_id}/undeploy" \
  -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/agents/personas/{persona_id}/undeploy",
    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/agents/personas/{persona_id}/undeploy", {
  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/agents/personas/{persona_id}/undeploy", 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()

Get Agent Canvas

GET/api/v1/agents/canvas

Return saved organigram canvas state for the current brand.

Request

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

import os
import requests

r = requests.request(
    "GET",
    "https://app.opvs.ai/api/v1/agents/canvas",
    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/agents/canvas", {
  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/agents/canvas", 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()

Save Agent Canvas

PUT/api/v1/agents/canvas

Upsert organigram canvas state (node positions + edges + viewport).

Errors

Code	When	What to do
422	Validation Error	—

Request

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

import os
import requests

r = requests.request(
    "PUT",
    "https://app.opvs.ai/api/v1/agents/canvas",
    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/agents/canvas", {
  method: "PUT",
  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("PUT", "https://app.opvs.ai/api/v1/agents/canvas", 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