Botpress Bot CURD Operations

POST /workspaces/{workspaceId}/agent-requests

Validates the input, freezes the selected template and stores an encrypted revision and uploaded files on the server. With review ON, no Botpress creation starts until approval. Acceptance is asynchronous: an HTTP 202 is not a completed bot.

Path parameters

Multipart form fields

Payload fields

Prompt variables

A template prompt such as You represent {{Brand Name}}. receives the value from variables["Brand Name"]. For example, "Brand Name": "Example Steel" produces You represent Example Steel. Names are case-sensitive. Values must be strings, satisfy the template's required-variable checks, be at most 10,000 characters, and contain neither {{ nor }}. Unknown variables are rejected. These are prompt substitutions, not arbitrary Botpress environment/configuration overrides.

There is currently no external template-discovery endpoint. Obtain the allowed name, variable names and any version pin from Versalence. The example below illustrates a template declaring Brand Name; use the actual assigned variable contract.

Document declarations and JSON-to-table conversion

The JSON flag is a literal boolean: true or false. Missing, null, "true", "yes" and 1 are invalid for a .json upload. Filename extension matching is case-insensitive. This requirement also applies to planned UPDATE add/replace operations.

Accepted extensions: .pdf .txt .md .json .jsonl .csv. Maximum 50 files; 50 MiB per file (52,428,800 bytes), 200 MiB total (209,715,200 bytes). Empty files and duplicate sanitised filenames are rejected. Multipart text fields have a 16 MiB limit. JSONL and CSV uploads are knowledge documents; this API's table-conversion option is for .json only.

Table JSON must be a single object or a non-empty array of objects, with at most 19 input fields across the rows. A wrapper object is treated as one row, not automatically unwrapped into its nested array. Nested values become JSON text. Additional row-size validation applies; oversized rows are rejected. Conversion creates a table source, not a second duplicate document source.

Example table file: catalogue.json

[
  { "itemCode": "DEMO-001", "description": "Sample product", "unit": "piece" },
  { "itemCode": "DEMO-002", "description": "Another sample product", "unit": "piece" }
]

Website declarations

To import the seller page, send https://www.24by7.com/sewa-enterprises-newdelhi/ with scope: "page". Website import is asynchronous. A successful submission does not establish that every page was crawled or indexed; inspect the eventual source results and warnings.

Example payload.json

{
  "clientReferenceId": "im-seller-demo-001",
  "template": { "name": "indiamart" },
  "agent": {
    "name": "Example Steel Assistant",
    "description": "Dedicated seller assistant"
  },
  "vcx": {
    "vcxAttachment": "STANDALONE",
    "deploymentMode": "DEDICATED_BOT"
  },
  "variables": { "Brand Name": "Example Steel" },
  "knowledge": {
    "notes": "<p>Answer seller questions using the supplied knowledge.</p>",
    "json": "{\"supportLanguage\":\"English\"}",
    "documents": [
      { "externalSourceId": "catalogue", "uploadField": "file_catalogue", "convertToTable": true },
      { "externalSourceId": "company-data", "uploadField": "file_company", "convertToTable": false },
      { "externalSourceId": "terms", "uploadField": "file_terms" }
    ],
    "websites": [
      {
        "externalSourceId": "seller-page",
        "url": "https://www.24by7.com/sewa-enterprises-newdelhi/",
        "scope": "page"
      }
    ]
  }
}

Curl

Examples use a POSIX shell. Replace the workspace and read the API key from your secure server environment. Save the payload above as payload.json and supply your actual files. Remove both a declaration and its corresponding file part if it is not needed.

curl --request POST \
  'https://backend.versalence.online/api/v2/agent-builder/ext/workspaces/YOUR_WORKSPACE_ID/agent-requests' \
  --header "x-api-key: $VCX_API_KEY" \
  --header 'Idempotency-Key: im-demo-001-create-20261030' \
  --header 'Accept: application/json' \
  --form 'payload=<payload.json' \
  --form 'file_catalogue=@catalogue.json;type=application/json' \
  --form 'file_company=@company.json;type=application/json' \
  --form 'file_terms=@terms.pdf;type=application/pdf'

202 Accepted · application/json · illustrative review-ON response

{
  "success": true,
  "replayed": false,
  "operation": {
    "operationId": "11111111-1111-4111-8111-111111111111",
    "type": "CREATE",
    "status": "pending_review",
    "stage": null,
    "agentId": "22222222-2222-4222-8222-222222222222",
    "revision": 1,
    "review": { "mode": "on", "decision": "pending", "decidedAt": null, "reason": null },
    "createdAt": "2026-10-30T10:00:00.000Z",
    "updatedAt": "2026-10-30T10:00:00.000Z",
    "warnings": [],
    "result": null,
    "error": null,
    "statusUrl": "/api/v2/agent-builder/ext/workspaces/YOUR_WORKSPACE_ID/operations/11111111-1111-4111-8111-111111111111"
  }
}

Idempotency and duplicate sellers

• Same key, same payload and same files: HTTP 200, replayed: true, original operation with its current status. This does not restart execution.
• Same key with different content, filenames or file bytes: HTTP 409 IDEMPOTENCY_KEY_REUSED.
• A different key for a clientReferenceId already in progress or created: HTTP 409 CLIENT_REFERENCE_EXISTS.
• If a network failure leaves acceptance uncertain, replay the identical request with the original key. Do not generate a new key merely because the response was lost.
• A failed operation is not restarted by replay. No public retry endpoint is available yet; coordinate recovery with Versalence, especially if cleanup requires attention.

GET /workspaces/{workspaceId}/operations/{operationId}

Requires operations.read. Use the operationId or relative statusUrl returned by CREATE. Unknown operations and operations outside your partner/workspace are not disclosed. An operation failure is represented inside a successful status lookup; inspect operation.status, not only the HTTP status or top-level success.

Curl

curl \
  'https://backend.versalence.online/api/v2/agent-builder/ext/workspaces/YOUR_WORKSPACE_ID/operations/11111111-1111-4111-8111-111111111111' \
  --header "x-api-key: $VCX_API_KEY" \
  --header 'Accept: application/json'

Statuses

Non-terminal status responses currently include Retry-After: 5. Wait at least that many seconds between polls and back off on network/server errors. Stop polling on a terminal state. Do not treat a null stage or a repeated response as failure. Creation can take longer than a normal HTTP request.

200 Successful lookup · illustrative completion with one text file and one table

{
  "success": true,
  "operation": {
    "operationId": "11111111-1111-4111-8111-111111111111",
    "type": "CREATE",
    "status": "succeeded",
    "stage": null,
    "agentId": "22222222-2222-4222-8222-222222222222",
    "revision": 1,
    "review": {
      "mode": "on", "decision": "approved",
      "decidedAt": "2026-10-30T10:02:00.000Z", "reason": null
    },
    "createdAt": "2026-10-30T10:00:00.000Z",
    "updatedAt": "2026-10-30T10:03:00.000Z",
    "warnings": [],
    "result": {
      "agentId": "22222222-2222-4222-8222-222222222222",
      "lifecycle": "draft",
      "knowledgeFiles": 1,
      "tables": [{ "externalSourceId": "catalogue", "rows": 2, "status": "indexed" }],
      "websites": []
    },
    "error": null
  }
}

The completion above illustrates a separate minimal submission, not the multi-source CREATE example. Counts and source results depend on the actual input. knowledgeFiles is not a count of all tables and websites. Source warnings refer to externalSourceId; retain your own mapping to filenames and URLs.

Status responses omit variable values, uploaded filenames, template contents, Botpress bot/KB IDs and webhook credentials. The vCX agentId cannot be substituted for a botId on the existing bot-credentials API. Integration credentials and activation handover must be coordinated with Versalence; no new partner activation or agent-details endpoint is included in this release.

Design contract only. This endpoint is not implemented or deployed. Do not call it yet.

POST /workspaces/{workspaceId}/agents/{agentId}/update-requests

Planned scope: agents.update. Planned headers: x-api-key and Idempotency-Key. Multipart payload plus files, using the same uploadField matching and mandatory .json convertToTable boolean as CREATE.

Planned update-payload.json

{
  "baseRevision": 1,
  "agent": { "name": "Updated Example Steel Assistant" },
  "variables": { "Brand Name": "Updated Example Steel" },
  "knowledge": {
    "notes": { "op": "replace", "value": "<p>Updated seller instructions.</p>" },
    "json": { "op": "remove" },
    "documents": [
      { "op": "replace", "externalSourceId": "catalogue", "uploadField": "file_catalogue_v2", "convertToTable": true },
      { "op": "add", "externalSourceId": "faq", "uploadField": "file_faq" },
      { "op": "remove", "externalSourceId": "terms" }
    ],
    "websites": [
      { "op": "replace", "externalSourceId": "seller-page", "url": "https://www.24by7.com/sewa-enterprises-newdelhi/", "scope": "page" }
    ]
  }
}

Planned Curl — do not execute until released

curl --request POST \
  'https://backend.versalence.online/api/v2/agent-builder/ext/workspaces/YOUR_WORKSPACE_ID/agents/YOUR_VCX_AGENT_ID/update-requests' \
  --header "x-api-key: $VCX_API_KEY" \
  --header 'Idempotency-Key: im-demo-001-update-002' \
  --form 'payload=<update-payload.json' \
  --form 'file_catalogue_v2=@catalogue-v2.json;type=application/json' \
  --form 'file_faq=@faq.md;type=text/markdown'

The intended response is an asynchronous operation with type UPDATE and a new revision. Live content must remain unchanged while review is pending. An update creates a complete resulting snapshot; it must not lose changes from the pending base. A pending unapproved update may be superseded by a later revision; approved/queued/running work must not be silently superseded.

Planned errors include stale revision, existing/unknown source IDs, repeated operations on one source, operation in progress and no changes. Changing convertToTable on replacement switches the source type. Document/table/website replacement and removal against a live bot still require implementation and acceptance tests. Final response examples will be pinned when the endpoint is built.

Design contract only. No DELETE endpoint is deployed. The DELETE approval policy still requires a decision.

DELETE /workspaces/{workspaceId}/agents/{agentId}

Planned scope: agents.delete. Requires Idempotency-Key and If-Match containing the quoted latest revision number. The JSON body must confirm the same vCX agentId as the path and provide a reason.

{
  "confirmAgentId": "22222222-2222-4222-8222-222222222222",
  "reason": "Seller account closed"
}

Planned Curl — do not execute until released

curl --request DELETE \
  'https://backend.versalence.online/api/v2/agent-builder/ext/workspaces/YOUR_WORKSPACE_ID/agents/22222222-2222-4222-8222-222222222222' \
  --header "x-api-key: $VCX_API_KEY" \
  --header 'Idempotency-Key: im-demo-001-delete-001' \
  --header 'If-Match: "2"' \
  --header 'Content-Type: application/json' \
  --data '{"confirmAgentId":"22222222-2222-4222-8222-222222222222","reason":"Seller account closed"}'

Deletion is intended to be asynchronous and restricted to the partner's agent in its workspace. The worker must remove the Botpress resource and reconcile the vCX record, record cleanup outcomes, and retain the required audit trail. A partly completed delete must remain visibly failed/needs attention, not be reported as complete.

The proposed review behaviour is: while deletion awaits approval, hold other queued work for that agent; do not cancel it yet. Rejection, cancellation or expiry releases the hold. When approved deletion is claimed, cancel held work atomically. New updates are refused while deletion is pending. Running operations must be resolved before deletion. These concurrency rules are requirements, not deployed behaviour.