Jump toWidgets

Widgets

Chat widgets for your website: drafts, versions, keys and identity secrets.

get/v1/widget-embed

Widget embed

Needs widget.view

Response200

objectstring
widget_embed
gateway_urlstring
loader_urlstring
page_url_templatestring

Status codes

200Successful Response
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl "https://api.mydeepagents.com/v1/widget-embed" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "object": "widget_embed",
  "gateway_url": "https://example.com",
  "loader_url": "https://example.com",
  "page_url_template": "page url template"
}

get/v1/widgets

List widgets

Needs widget.view

Recently changed first. Sorts by updated_at, created_at, name, latest_version, active_keys and sessions_7d; q searches names and the answering agent's name, or finds a pasted widget ID. Filters, each repeatable: status (enabled, disabled), publication (live, staging, unpublished), valid (true, false), agent (agt_…, or none for no agent chosen), created_by and updated_by (usr_… or sa_…), plus the created and updated time ranges; facets count each of them, and agents names the agents counted.

Query parameters

workspace_idstring
Only rows in this workspace (ws_…).
statusstring[]
publicationstring[]
validstring[]
agentstring[]
created_bystring[]
updated_bystring[]
limitinteger
Rows per page, 1 to 200.
Default50at least 1at most 200
cursorstring
qstring
Search: rows whose name (or the list's other searchable text) contains this, any case.
at most 200 characters
orderstring
Sort field; a leading - sorts down. Each list names the fields it sorts by.
at most 64 charactersmatches ^-?[a-z_]+$
includestring[]
total_count (counted up to 10,000) and facets (a count per filter value).
One oftotal_countfacets
created_afterstring
Only rows created at or after this time (RFC 3339).
date-time
created_beforestring
Only rows created at or before this time (RFC 3339).
date-time
updated_afterstring
Only rows last changed at or after this time (RFC 3339).
date-time
updated_beforestring
Only rows last changed at or before this time (RFC 3339).
date-time

Response200

objectstring
list
dataWidget[]
21 fields
- idstring
- objectstring
  widget
- active_keysinteger
- agent_idstring or null
- aliasesmap<string, integer>
- created_atstring
- draft_revisioninteger
- draft_validboolean
- identity_secret_setboolean
- latest_versioninteger or null
- namestring
- row_versioninteger
- sessions_7dinteger
- statusstring
  One ofenableddisabled
- updated_atstring
- workspace_idstring
- agent_namestring or null
- created_byActorRef or null
  Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
  5 fields
  idstring or null
  kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
  namestring or null
  avatar_versionstring or null
  emailstring or null
- lookWidgetLook or null
  Enough of the draft to draw a widget's thumbnail in a list.
  6 fields
  greetingstring or null
  iconstring or null
  sitesinteger
  themeobject or null
  Any JSON object.
  titlestring or null
  glyphobject or null
  Any JSON object.
- publicationstring or null
  One oflivestagingunpublished
- updated_byActorRef or null
  Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
  5 fields
  idstring or null
  kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
  namestring or null
  avatar_versionstring or null
  emailstring or null
has_moreboolean
next_cursorstring or null
agentsmap<string, string> or null
facetsmap<string, map<string, integer>> or null
peoplemap<string, ActorRef> or null
5 fields
- idstring or null
- kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
- namestring or null
- avatar_versionstring or null
- emailstring or null
total_countinteger or null
total_count_exactboolean or null

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl "https://api.mydeepagents.com/v1/widgets?limit=20" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "object": "list",
  "agents": {
    "key": "key"
  },
  "data": [
    {
      "id": "wgt_01jcb9b91yw6e401867mcdfc37",
      "object": "widget",
      "active_keys": 2,
      "agent_id": "agt_01jctdbahw9btk5p831xs974yq",
      "agent_name": "agent name",
      "aliases": {
        "live": 2
      },
      "created_at": "2026-11-10T09:30:00.000Z",
      "created_by": {
        "kind": "user",
        "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
        "name": "Ada Lovelace",
        "email": "ada@example.com"
      },
      "draft_revision": 2,
      "draft_valid": true,
      "identity_secret_set": true,
      "latest_version": 3,
      "look": {
        "glyph": {},
        "greeting": "greeting",
        "icon": "icon",
        "sites": 2,
        "theme": {},
        "title": "Support triage"
      },
      "name": "Support triage",
      "publication": "live",
      "row_version": 4,
      "sessions_7d": 2,
      "status": "enabled",
      "updated_at": "2026-11-10T09:30:00.000Z",
      "updated_by": {
        "kind": "user",
        "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
        "name": "Ada Lovelace",
        "email": "ada@example.com"
      },
      "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": 1
}

post/v1/widgets

Create widget

Needs widget.edit

Request bodyWidgetCreate

definitionobjectRequired
The whole definition document, as JSON. The request example shows a complete, minimal one; the draft endpoints return the same shape.
workspace_idstringRequired
agent_idstring or null

Response201

idstring
objectstring
widget
active_keysinteger
agent_idstring or null
aliasesmap<string, integer>
created_atstring
draftWidgetDraft
6 fields
- objectstring
  widget_draft
- definitionobject
  The whole definition document, as JSON. The request example shows a complete, minimal one; the draft endpoints return the same shape.
- draft_revisioninteger
- issuesValidationIssue[]
  5 fields
  codestring
  messagestring
  pathstring
  severitystring
  One oferrorwarning
  hintstring or null
- validboolean
- widget_idstring
draft_revisioninteger
draft_validboolean
identity_secret_setboolean
latest_versioninteger or null
namestring
row_versioninteger
sessions_7dinteger
statusstring
One ofenableddisabled
updated_atstring
workspace_idstring
agent_namestring or null
created_byActorRef or null
Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
5 fields
- idstring or null
- kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
- namestring or null
- avatar_versionstring or null
- emailstring or null
lookWidgetLook or null
Enough of the draft to draw a widget's thumbnail in a list.
6 fields
- greetingstring or null
- iconstring or null
- sitesinteger
- themeobject or null
  Any JSON object.
- titlestring or null
- glyphobject or null
  Any JSON object.
publicationstring or null
One oflivestagingunpublished
updated_byActorRef or null
Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
5 fields
- idstring or null
- kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
- namestring or null
- avatar_versionstring or null
- emailstring or null

Status codes

201Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X POST "https://api.mydeepagents.com/v1/widgets" \
  -H "Authorization: Bearer $MDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_01jctdbahw9btk5p831xs974yq",
    "definition": {},
    "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h"
  }'

Response · 201

JSON

{
  "id": "wgt_01jcb9b91yw6e401867mcdfc37",
  "object": "widget",
  "active_keys": 2,
  "agent_id": "agt_01jctdbahw9btk5p831xs974yq",
  "agent_name": "agent name",
  "aliases": {
    "live": 2
  },
  "created_at": "2026-11-10T09:30:00.000Z",
  "created_by": {
    "kind": "user",
    "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  },
  "draft": {
    "object": "widget_draft",
    "definition": {},
    "draft_revision": 2,
    "issues": [
      {
        "code": "code",
        "hint": "hint",
        "message": "Summarise today's open tickets.",
        "path": "path",
        "severity": "error"
      }
    ],
    "valid": true,
    "widget_id": "wgt_01jcb9b91yw6e401867mcdfc37"
  },
  "draft_revision": 2,
  "draft_valid": true,
  "identity_secret_set": true,
  "latest_version": 3,
  "look": {
    "glyph": {},
    "greeting": "greeting",
    "icon": "icon",
    "sites": 2,
    "theme": {},
    "title": "Support triage"
  },
  "name": "Support triage",
  "publication": "live",
  "row_version": 4,
  "sessions_7d": 2,
  "status": "enabled",
  "updated_at": "2026-11-10T09:30:00.000Z",
  "updated_by": {
    "kind": "user",
    "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  },
  "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h"
}

get/v1/widgets/{widget_id}

Get widget

Needs widget.view

Path parameters

widget_idstringRequired

Response200

idstring
objectstring
widget
active_keysinteger
agent_idstring or null
aliasesmap<string, integer>
created_atstring
draft_revisioninteger
draft_validboolean
identity_secret_setboolean
latest_versioninteger or null
namestring
row_versioninteger
sessions_7dinteger
statusstring
One ofenableddisabled
updated_atstring
workspace_idstring
agent_namestring or null
created_byActorRef or null
Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
5 fields
- idstring or null
- kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
- namestring or null
- avatar_versionstring or null
- emailstring or null
lookWidgetLook or null
Enough of the draft to draw a widget's thumbnail in a list.
6 fields
- greetingstring or null
- iconstring or null
- sitesinteger
- themeobject or null
  Any JSON object.
- titlestring or null
- glyphobject or null
  Any JSON object.
publicationstring or null
One oflivestagingunpublished
updated_byActorRef or null
Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
5 fields
- idstring or null
- kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
- namestring or null
- avatar_versionstring or null
- emailstring or null

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl "https://api.mydeepagents.com/v1/widgets/wgt_01jcb9b91yw6e401867mcdfc37" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "id": "wgt_01jcb9b91yw6e401867mcdfc37",
  "object": "widget",
  "active_keys": 2,
  "agent_id": "agt_01jctdbahw9btk5p831xs974yq",
  "agent_name": "agent name",
  "aliases": {
    "live": 2
  },
  "created_at": "2026-11-10T09:30:00.000Z",
  "created_by": {
    "kind": "user",
    "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  },
  "draft_revision": 2,
  "draft_valid": true,
  "identity_secret_set": true,
  "latest_version": 3,
  "look": {
    "glyph": {},
    "greeting": "greeting",
    "icon": "icon",
    "sites": 2,
    "theme": {},
    "title": "Support triage"
  },
  "name": "Support triage",
  "publication": "live",
  "row_version": 4,
  "sessions_7d": 2,
  "status": "enabled",
  "updated_at": "2026-11-10T09:30:00.000Z",
  "updated_by": {
    "kind": "user",
    "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  },
  "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h"
}

delete/v1/widgets/{widget_id}

Delete widget

Needs widget.edit

Path parameters

widget_idstringRequired

Response204

Answers 204 with no body.

Status codes

204Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X DELETE "https://api.mydeepagents.com/v1/widgets/wgt_01jcb9b91yw6e401867mcdfc37" \
  -H "Authorization: Bearer $MDA_API_KEY"

get/v1/widgets/{widget_id}/bindings

List widget bindings

Needs widget.view

Path parameters

widget_idstringRequired

Response200

objectstring
list
dataBinding[]
8 fields
- objectstring
  binding
- aliasstring
  One ofdraftstaginglive
- revisioninteger
- slotstring
- target_idstring
- target_typestring
  One ofconnectionmcp_serverknowledge_baseagentworkflowcode_toola2a_agent
- updated_atstring
- target_aliasstring or null
has_moreboolean
next_cursorstring or null
facetsmap<string, map<string, integer>> or null
peoplemap<string, ActorRef> or null
5 fields
- idstring or null
- kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
- namestring or null
- avatar_versionstring or null
- emailstring or null
total_countinteger or null
total_count_exactboolean or null

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl "https://api.mydeepagents.com/v1/widgets/wgt_01jcb9b91yw6e401867mcdfc37/bindings" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "object": "list",
  "data": [
    {
      "object": "binding",
      "alias": "live",
      "revision": 2,
      "slot": "crm",
      "target_alias": "target alias",
      "target_id": "target id",
      "target_type": "connection",
      "updated_at": "2026-11-10T09:30:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": 1
}

get/v1/widgets/{widget_id}/draft

Get widget draft

Needs widget.view

Path parameters

widget_idstringRequired

Response200

objectstring
widget_draft
definitionobject
The whole definition document, as JSON. The request example shows a complete, minimal one; the draft endpoints return the same shape.
draft_revisioninteger
issuesValidationIssue[]
5 fields
- codestring
- messagestring
- pathstring
- severitystring
  One oferrorwarning
- hintstring or null
validboolean
widget_idstring

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl "https://api.mydeepagents.com/v1/widgets/wgt_01jcb9b91yw6e401867mcdfc37/draft" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "object": "widget_draft",
  "definition": {},
  "draft_revision": 2,
  "issues": [
    {
      "code": "code",
      "hint": "hint",
      "message": "Summarise today's open tickets.",
      "path": "path",
      "severity": "error"
    }
  ],
  "valid": true,
  "widget_id": "wgt_01jcb9b91yw6e401867mcdfc37"
}

put/v1/widgets/{widget_id}/draft

Put widget draft

Needs widget.edit

Path parameters

widget_idstringRequired

Headers

If-Matchstring
The ETag you read. If the resource changed since, the write fails with 412.

Request bodyWidgetDraftPut

definitionobjectRequired
The whole definition document, as JSON. The request example shows a complete, minimal one; the draft endpoints return the same shape.

Response200

objectstring
widget_draft
definitionobject
The whole definition document, as JSON. The request example shows a complete, minimal one; the draft endpoints return the same shape.
draft_revisioninteger
issuesValidationIssue[]
5 fields
- codestring
- messagestring
- pathstring
- severitystring
  One oferrorwarning
- hintstring or null
validboolean
widget_idstring

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X PUT "https://api.mydeepagents.com/v1/widgets/wgt_01jcb9b91yw6e401867mcdfc37/draft" \
  -H "Authorization: Bearer $MDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "definition": {}
  }'

Response · 200

JSON

{
  "object": "widget_draft",
  "definition": {},
  "draft_revision": 2,
  "issues": [
    {
      "code": "code",
      "hint": "hint",
      "message": "Summarise today's open tickets.",
      "path": "path",
      "severity": "error"
    }
  ],
  "valid": true,
  "widget_id": "wgt_01jcb9b91yw6e401867mcdfc37"
}

post/v1/widgets/{widget_id}/identity-secret

Rotate identity secret

Needs widget.publish

Path parameters

widget_idstringRequired

Response201

objectstring
widget_identity_secret
secretstring
widget_idstring

Status codes

201Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X POST "https://api.mydeepagents.com/v1/widgets/wgt_01jcb9b91yw6e401867mcdfc37/identity-secret" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 201

JSON

{
  "object": "widget_identity_secret",
  "secret": "secret",
  "widget_id": "wgt_01jcb9b91yw6e401867mcdfc37"
}

delete/v1/widgets/{widget_id}/identity-secret

Remove identity secret

Needs widget.publish

Path parameters

widget_idstringRequired

Response204

Answers 204 with no body.

Status codes

204Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X DELETE "https://api.mydeepagents.com/v1/widgets/wgt_01jcb9b91yw6e401867mcdfc37/identity-secret" \
  -H "Authorization: Bearer $MDA_API_KEY"

get/v1/widgets/{widget_id}/keys

List widget keys

Needs widget.view

A widget's keys, revoked last: a few at most (KEYS_PER_WIDGET), so never paged.

Path parameters

widget_idstringRequired

Response200

objectstring
list
dataWidgetKey[]
17 fields
- idstring
- objectstring
  widget_key
- aliasstring
  One ofstaginglive
- allow_localhostboolean
- created_atstring or null
- domainsstring[] or null
- keystring
- labelstring
- last_used_atstring or null
- revoked_atstring or null
- statusstring
  One ofactivesuspendedrevoked
- status_reasonstring or null
- surfacestring
  One ofembedpageheadless
- widget_idstring
- created_byActorRef or null
  Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
  5 fields
  idstring or null
  kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
  namestring or null
  avatar_versionstring or null
  emailstring or null
- updated_atstring or null
- updated_byActorRef or null
  Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
  5 fields
  idstring or null
  kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
  namestring or null
  avatar_versionstring or null
  emailstring or null
has_moreboolean
next_cursorstring or null
facetsmap<string, map<string, integer>> or null
peoplemap<string, ActorRef> or null
5 fields
- idstring or null
- kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
- namestring or null
- avatar_versionstring or null
- emailstring or null
total_countinteger or null
total_count_exactboolean or null

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl "https://api.mydeepagents.com/v1/widgets/wgt_01jcb9b91yw6e401867mcdfc37/keys" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "object": "list",
  "data": [
    {
      "id": "wgk_01jcjhd18yptvces0car3mxb8d",
      "object": "widget_key",
      "alias": "live",
      "allow_localhost": true,
      "created_at": "2026-11-10T09:30:00.000Z",
      "created_by": {
        "kind": "user",
        "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
        "name": "Ada Lovelace",
        "email": "ada@example.com"
      },
      "domains": [
        "domain"
      ],
      "key": "key",
      "label": "label",
      "last_used_at": "2026-11-10T09:30:00.000Z",
      "revoked_at": null,
      "status": "active",
      "status_reason": null,
      "surface": "embed",
      "updated_at": "2026-11-10T09:30:00.000Z",
      "updated_by": {
        "kind": "user",
        "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
        "name": "Ada Lovelace",
        "email": "ada@example.com"
      },
      "widget_id": "wgt_01jcb9b91yw6e401867mcdfc37"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": 1
}

post/v1/widgets/{widget_id}/keys

Create widget key

Needs widget.publish

Path parameters

widget_idstringRequired

Request bodyWidgetKeyCreate

labelstringRequired
at least 1 charactersat most 100 characters
aliasstring
One ofstagingliveDefault"live"
allow_localhostboolean
Defaultfalse
domainsstring[] or null
at most 50 items
surfacestring
One ofembedpageheadlessDefault"embed"

Response201

idstring
objectstring
widget_key
aliasstring
One ofstaginglive
allow_localhostboolean
created_atstring or null
domainsstring[] or null
keystring
labelstring
last_used_atstring or null
revoked_atstring or null
statusstring
One ofactivesuspendedrevoked
status_reasonstring or null
surfacestring
One ofembedpageheadless
widget_idstring
created_byActorRef or null
Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
5 fields
- idstring or null
- kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
- namestring or null
- avatar_versionstring or null
- emailstring or null
updated_atstring or null
updated_byActorRef or null
Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
5 fields
- idstring or null
- kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
- namestring or null
- avatar_versionstring or null
- emailstring or null

Status codes

201Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X POST "https://api.mydeepagents.com/v1/widgets/wgt_01jcb9b91yw6e401867mcdfc37/keys" \
  -H "Authorization: Bearer $MDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "live",
    "allow_localhost": false,
    "domains": [
      "domain"
    ],
    "label": "label",
    "surface": "embed"
  }'

Response · 201

JSON

{
  "id": "wgk_01jcjhd18yptvces0car3mxb8d",
  "object": "widget_key",
  "alias": "live",
  "allow_localhost": true,
  "created_at": "2026-11-10T09:30:00.000Z",
  "created_by": {
    "kind": "user",
    "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  },
  "domains": [
    "domain"
  ],
  "key": "key",
  "label": "label",
  "last_used_at": "2026-11-10T09:30:00.000Z",
  "revoked_at": null,
  "status": "active",
  "status_reason": null,
  "surface": "embed",
  "updated_at": "2026-11-10T09:30:00.000Z",
  "updated_by": {
    "kind": "user",
    "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  },
  "widget_id": "wgt_01jcb9b91yw6e401867mcdfc37"
}

post/v1/widgets/{widget_id}/preview/speech/synthesize

Preview say

Needs agent.run

Path parameters

widget_idstringRequired

Request bodyPreviewSay

textstringRequired
at least 1 charactersat most 400 characters

Response200

objectstring
widget_speech
audiostring
mimestring

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X POST "https://api.mydeepagents.com/v1/widgets/wgt_01jcb9b91yw6e401867mcdfc37/preview/speech/synthesize" \
  -H "Authorization: Bearer $MDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "text"
  }'

Response · 200

JSON

{
  "object": "widget_speech",
  "audio": "audio",
  "mime": "mime"
}

post/v1/widgets/{widget_id}/preview/speech/transcribe

Preview hear

Needs agent.run

Path parameters

widget_idstringRequired

Request bodyPreviewHear

audiostringRequired
at least 1 charactersat most 1333341 characters
mimestringRequired
at least 1 charactersat most 100 characters
languagestring or null
matches ^[a-z]{2}(-[A-Za-z]{2})?$

Response200

objectstring
widget_transcript
textstring

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X POST "https://api.mydeepagents.com/v1/widgets/wgt_01jcb9b91yw6e401867mcdfc37/preview/speech/transcribe" \
  -H "Authorization: Bearer $MDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio": "audio",
    "language": "language",
    "mime": "mime"
  }'

Response · 200

JSON

{
  "object": "widget_transcript",
  "text": "text"
}

post/v1/widgets/{widget_id}/preview/uploads

Preview upload

Needs agent.run

Path parameters

widget_idstringRequired

Request bodyPreviewUpload

content_typestringRequired
at least 1 charactersat most 100 characters
filenamestringRequired
at least 1 charactersat most 255 characters
sizeintegerRequired
at least 1at most 26214400

Response201

idstring
objectstring
widget_upload
content_typestring
kindstring
namestring
sizeinteger
statusstring
One ofpendingready
uploadWidgetUploadTarget or null
Where the browser PUTs the file: the staging bucket, size and type signed.
4 fields
- expires_atstring
- headersmap<string, string>
- methodstring
  PUT
- urlstring

Status codes

201Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X POST "https://api.mydeepagents.com/v1/widgets/wgt_01jcb9b91yw6e401867mcdfc37/preview/uploads" \
  -H "Authorization: Bearer $MDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content_type": "content type",
    "filename": "filename",
    "size": 1
  }'

Response · 201

JSON

{
  "id": "id",
  "object": "widget_upload",
  "content_type": "content type",
  "kind": "kind",
  "name": "Support triage",
  "size": 2,
  "status": "pending",
  "upload": {
    "expires_at": "2026-11-10T09:30:00.000Z",
    "headers": {
      "X-Request-Source": "X-Request-Source"
    },
    "method": "PUT",
    "url": "https://mcp.example.com/mcp"
  }
}

post/v1/widgets/{widget_id}/publish

Publish widget

Needs widget.publish

Path parameters

widget_idstringRequired

Request bodyWidgetPublishBody

aliasstring or null
One oflivestaging

Response201

idstring
objectstring
widget_version
aliasesstring[]
content_hashstring
created_atstring
numberinteger
published_bystring
schema_versionstring
statusstring
One ofpublishedarchived
widget_idstring

Status codes

201Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X POST "https://api.mydeepagents.com/v1/widgets/wgt_01jcb9b91yw6e401867mcdfc37/publish" \
  -H "Authorization: Bearer $MDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "live"
  }'

Response · 201

JSON

{
  "id": "id",
  "object": "widget_version",
  "aliases": [
    "aliase"
  ],
  "content_hash": "content hash",
  "created_at": "2026-11-10T09:30:00.000Z",
  "number": 3,
  "published_by": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
  "schema_version": "schema version",
  "status": "published",
  "widget_id": "wgt_01jcb9b91yw6e401867mcdfc37"
}

put/v1/widgets/{widget_id}/status

Put widget status

Needs widget.edit

Path parameters

widget_idstringRequired

Request bodyWidgetStatusPut

statusstringRequired
One ofenableddisabled

Response200

idstring
objectstring
widget
active_keysinteger
agent_idstring or null
aliasesmap<string, integer>
created_atstring
draft_revisioninteger
draft_validboolean
identity_secret_setboolean
latest_versioninteger or null
namestring
row_versioninteger
sessions_7dinteger
statusstring
One ofenableddisabled
updated_atstring
workspace_idstring
agent_namestring or null
created_byActorRef or null
Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
5 fields
- idstring or null
- kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
- namestring or null
- avatar_versionstring or null
- emailstring or null
lookWidgetLook or null
Enough of the draft to draw a widget's thumbnail in a list.
6 fields
- greetingstring or null
- iconstring or null
- sitesinteger
- themeobject or null
  Any JSON object.
- titlestring or null
- glyphobject or null
  Any JSON object.
publicationstring or null
One oflivestagingunpublished
updated_byActorRef or null
Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
5 fields
- idstring or null
- kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
- namestring or null
- avatar_versionstring or null
- emailstring or null

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X PUT "https://api.mydeepagents.com/v1/widgets/wgt_01jcb9b91yw6e401867mcdfc37/status" \
  -H "Authorization: Bearer $MDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "enabled"
  }'

Response · 200

JSON

{
  "id": "wgt_01jcb9b91yw6e401867mcdfc37",
  "object": "widget",
  "active_keys": 2,
  "agent_id": "agt_01jctdbahw9btk5p831xs974yq",
  "agent_name": "agent name",
  "aliases": {
    "live": 2
  },
  "created_at": "2026-11-10T09:30:00.000Z",
  "created_by": {
    "kind": "user",
    "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  },
  "draft_revision": 2,
  "draft_valid": true,
  "identity_secret_set": true,
  "latest_version": 3,
  "look": {
    "glyph": {},
    "greeting": "greeting",
    "icon": "icon",
    "sites": 2,
    "theme": {},
    "title": "Support triage"
  },
  "name": "Support triage",
  "publication": "live",
  "row_version": 4,
  "sessions_7d": 2,
  "status": "enabled",
  "updated_at": "2026-11-10T09:30:00.000Z",
  "updated_by": {
    "kind": "user",
    "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  },
  "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h"
}

post/v1/widgets/{widget_id}/validate

Validate widget

Needs widget.view

Path parameters

widget_idstringRequired

Request bodyWidgetValidateBody

definitionobject or null
The whole definition document, as JSON. The request example shows a complete, minimal one; the draft endpoints return the same shape.

Response200

objectstring
validation
issuesValidationIssue[]
5 fields
- codestring
- messagestring
- pathstring
- severitystring
  One oferrorwarning
- hintstring or null
validboolean

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X POST "https://api.mydeepagents.com/v1/widgets/wgt_01jcb9b91yw6e401867mcdfc37/validate" \
  -H "Authorization: Bearer $MDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "definition": {}
  }'

Response · 200

JSON

{
  "object": "validation",
  "issues": [
    {
      "code": "code",
      "hint": "hint",
      "message": "Summarise today's open tickets.",
      "path": "path",
      "severity": "error"
    }
  ],
  "valid": true
}

get/v1/widgets/{widget_id}/versions

List widget versions

Needs widget.view

Path parameters

widget_idstringRequired

Response200

objectstring
list
dataWidgetVersion[]
10 fields
- idstring
- objectstring
  widget_version
- aliasesstring[]
- content_hashstring
- created_atstring
- numberinteger
- published_bystring
- schema_versionstring
- statusstring
  One ofpublishedarchived
- widget_idstring
has_moreboolean
next_cursorstring or null
facetsmap<string, map<string, integer>> or null
peoplemap<string, ActorRef> or null
5 fields
- idstring or null
- kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
- namestring or null
- avatar_versionstring or null
- emailstring or null
total_countinteger or null
total_count_exactboolean or null

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl "https://api.mydeepagents.com/v1/widgets/wgt_01jcb9b91yw6e401867mcdfc37/versions" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "object": "list",
  "data": [
    {
      "id": "id",
      "object": "widget_version",
      "aliases": [
        "aliase"
      ],
      "content_hash": "content hash",
      "created_at": "2026-11-10T09:30:00.000Z",
      "number": 3,
      "published_by": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
      "schema_version": "schema version",
      "status": "published",
      "widget_id": "wgt_01jcb9b91yw6e401867mcdfc37"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": 1
}

put/v1/widgets/{widget_id}/aliases/{alias}

Move widget alias

Needs widget.publish

Path parameters

widget_idstringRequired
aliasstringRequired
One ofstaginglive

Request bodyWidgetAliasPut

versionintegerRequired
at least 1

Response200

objectstring
alias
aliasstring
One ofstaginglive
previous_versioninteger or null
versioninteger
widget_idstring

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X PUT "https://api.mydeepagents.com/v1/widgets/wgt_01jcb9b91yw6e401867mcdfc37/aliases/live" \
  -H "Authorization: Bearer $MDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version": 3
  }'

Response · 200

JSON

{
  "object": "alias",
  "alias": "live",
  "previous_version": 2,
  "version": 3,
  "widget_id": "wgt_01jcb9b91yw6e401867mcdfc37"
}

patch/v1/widgets/{widget_id}/keys/{key_id}

Patch widget key

Needs widget.publish

Path parameters

widget_idstringRequired
key_idstringRequired

Request bodyWidgetKeyPatch

allow_localhostboolean or null
domainsstring[] or null
at most 50 items
labelstring or null
at least 1 charactersat most 100 characters
statusstring or null
One ofactivesuspended

Response200

idstring
objectstring
widget_key
aliasstring
One ofstaginglive
allow_localhostboolean
created_atstring or null
domainsstring[] or null
keystring
labelstring
last_used_atstring or null
revoked_atstring or null
statusstring
One ofactivesuspendedrevoked
status_reasonstring or null
surfacestring
One ofembedpageheadless
widget_idstring
created_byActorRef or null
Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
5 fields
- idstring or null
- kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
- namestring or null
- avatar_versionstring or null
- emailstring or null
updated_atstring or null
updated_byActorRef or null
Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
5 fields
- idstring or null
- kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
- namestring or null
- avatar_versionstring or null
- emailstring or null

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X PATCH "https://api.mydeepagents.com/v1/widgets/wgt_01jcb9b91yw6e401867mcdfc37/keys/wgk_01jcjhd18yptvces0car3mxb8d" \
  -H "Authorization: Bearer $MDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "allow_localhost": true,
    "domains": [
      "domain"
    ],
    "label": "label",
    "status": "active"
  }'

Response · 200

JSON

{
  "id": "wgk_01jcjhd18yptvces0car3mxb8d",
  "object": "widget_key",
  "alias": "live",
  "allow_localhost": true,
  "created_at": "2026-11-10T09:30:00.000Z",
  "created_by": {
    "kind": "user",
    "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  },
  "domains": [
    "domain"
  ],
  "key": "key",
  "label": "label",
  "last_used_at": "2026-11-10T09:30:00.000Z",
  "revoked_at": null,
  "status": "active",
  "status_reason": null,
  "surface": "embed",
  "updated_at": "2026-11-10T09:30:00.000Z",
  "updated_by": {
    "kind": "user",
    "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  },
  "widget_id": "wgt_01jcb9b91yw6e401867mcdfc37"
}

delete/v1/widgets/{widget_id}/keys/{key_id}

Revoke widget key

Needs widget.publish

Path parameters

widget_idstringRequired
key_idstringRequired

Response200

idstring
objectstring
widget_key
aliasstring
One ofstaginglive
allow_localhostboolean
created_atstring or null
domainsstring[] or null
keystring
labelstring
last_used_atstring or null
revoked_atstring or null
statusstring
One ofactivesuspendedrevoked
status_reasonstring or null
surfacestring
One ofembedpageheadless
widget_idstring
created_byActorRef or null
Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
5 fields
- idstring or null
- kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
- namestring or null
- avatar_versionstring or null
- emailstring or null
updated_atstring or null
updated_byActorRef or null
Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
5 fields
- idstring or null
- kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
- namestring or null
- avatar_versionstring or null
- emailstring or null

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X DELETE "https://api.mydeepagents.com/v1/widgets/wgt_01jcb9b91yw6e401867mcdfc37/keys/wgk_01jcjhd18yptvces0car3mxb8d" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "id": "wgk_01jcjhd18yptvces0car3mxb8d",
  "object": "widget_key",
  "alias": "live",
  "allow_localhost": true,
  "created_at": "2026-11-10T09:30:00.000Z",
  "created_by": {
    "kind": "user",
    "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  },
  "domains": [
    "domain"
  ],
  "key": "key",
  "label": "label",
  "last_used_at": "2026-11-10T09:30:00.000Z",
  "revoked_at": null,
  "status": "active",
  "status_reason": null,
  "surface": "embed",
  "updated_at": "2026-11-10T09:30:00.000Z",
  "updated_by": {
    "kind": "user",
    "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  },
  "widget_id": "wgt_01jcb9b91yw6e401867mcdfc37"
}

delete/v1/widgets/{widget_id}/preview/uploads/{upload_id}

Preview upload gone

Needs agent.run

Path parameters

widget_idstringRequired
upload_idstringRequired

Response204

Answers 204 with no body.

Status codes

204Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X DELETE "https://api.mydeepagents.com/v1/widgets/wgt_01jcb9b91yw6e401867mcdfc37/preview/uploads/upl_01jczz3sybr5afyn47wt3q32he" \
  -H "Authorization: Bearer $MDA_API_KEY"

post/v1/widgets/{widget_id}/preview/uploads/{upload_id}/complete

Preview upload done

Needs agent.run

Path parameters

widget_idstringRequired
upload_idstringRequired

Response200

idstring
objectstring
widget_upload
content_typestring
kindstring
namestring
sizeinteger
statusstring
One ofpendingready
uploadWidgetUploadTarget or null
Where the browser PUTs the file: the staging bucket, size and type signed.
4 fields
- expires_atstring
- headersmap<string, string>
- methodstring
  PUT
- urlstring

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X POST "https://api.mydeepagents.com/v1/widgets/wgt_01jcb9b91yw6e401867mcdfc37/preview/uploads/upl_01jczz3sybr5afyn47wt3q32he/complete" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "id": "id",
  "object": "widget_upload",
  "content_type": "content type",
  "kind": "kind",
  "name": "Support triage",
  "size": 2,
  "status": "pending",
  "upload": {
    "expires_at": "2026-11-10T09:30:00.000Z",
    "headers": {
      "X-Request-Source": "X-Request-Source"
    },
    "method": "PUT",
    "url": "https://mcp.example.com/mcp"
  }
}

get/v1/widgets/{widget_id}/versions/{number}

Get widget version

Needs widget.view

Path parameters

widget_idstringRequired
numberintegerRequired

Response200

idstring
objectstring
widget_version
aliasesstring[]
content_hashstring
created_atstring
definitionobject
The whole definition document, as JSON. The request example shows a complete, minimal one; the draft endpoints return the same shape.
numberinteger
published_bystring
schema_versionstring
statusstring
One ofpublishedarchived
widget_idstring

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl "https://api.mydeepagents.com/v1/widgets/wgt_01jcb9b91yw6e401867mcdfc37/versions/3" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "id": "id",
  "object": "widget_version",
  "aliases": [
    "aliase"
  ],
  "content_hash": "content hash",
  "created_at": "2026-11-10T09:30:00.000Z",
  "definition": {},
  "number": 3,
  "published_by": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
  "schema_version": "schema version",
  "status": "published",
  "widget_id": "wgt_01jcb9b91yw6e401867mcdfc37"
}

put/v1/widgets/{widget_id}/bindings/{alias}/{slot}

Put widget binding

Needs widget.edit

Path parameters

widget_idstringRequired
aliasstringRequired
One ofdraftstaginglive
slotstringRequired

Request bodyWidgetBindingPut

agent_idstringRequired

Response200

objectstring
binding
aliasstring
One ofdraftstaginglive
revisioninteger
slotstring
target_idstring
target_typestring
One ofconnectionmcp_serverknowledge_baseagentworkflowcode_toola2a_agent
updated_atstring
target_aliasstring or null

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X PUT "https://api.mydeepagents.com/v1/widgets/wgt_01jcb9b91yw6e401867mcdfc37/bindings/live/crm" \
  -H "Authorization: Bearer $MDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_01jctdbahw9btk5p831xs974yq"
  }'

Response · 200

JSON

{
  "object": "binding",
  "alias": "live",
  "revision": 2,
  "slot": "crm",
  "target_alias": "target alias",
  "target_id": "target id",
  "target_type": "connection",
  "updated_at": "2026-11-10T09:30:00.000Z"
}

delete/v1/widgets/{widget_id}/bindings/{alias}/{slot}

Delete widget binding

Needs widget.edit

Path parameters

widget_idstringRequired
aliasstringRequired
One ofdraftstaginglive
slotstringRequired

Response204

Answers 204 with no body.

Status codes

204Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X DELETE "https://api.mydeepagents.com/v1/widgets/wgt_01jcb9b91yw6e401867mcdfc37/bindings/live/crm" \
  -H "Authorization: Bearer $MDA_API_KEY"

Build with us

Ready for your first call?

Early access is open. Tell us what you want your agents to do, and we will help you get your first key.

Talk to us Read the API guide