Scenarios API
A scenario stores a business name, definition and ordered category path for knowledge graph and Wiki organization.
Resources and base paths
Use the instance endpoint followed by /v1. Resources include scenarios, categories and import previews. A scenario has a name, definition, ordered category path and revision. Category knowledge bindings do not inherit a parent binding. Category deletion needs a reviewed impact token. Read the new revision after mutation; HTTP 201 confirms saving, not a subsequent knowledge index build.
Authentication and permissions
scenarios.read permits reads and previews; scenarios.write is required for creation, editing, import and deletion. Send project identity and a project key in headers. Console organization identity does not authorize unrelated project keys. This page covers project resources only.
Endpoint list
Paths below are relative to /v1. Server requests carry X-Appwrite-Project and X-Appwrite-Key; keep the key on the server. Scopes below are necessary; dataset access, ownership and resource state may add checks. HTTP 202 means accepted; use the returned operation identifier to read its terminal result.
| HTTP | Scope | SDK |
|---|---|---|
GET /scenarios | scenarios.read | scenarios.list |
POST /scenarios | scenarios.write | scenarios.create |
GET /scenarios/categories | scenarios.read | scenarios.listCategories |
POST /scenarios/categories | scenarios.write | scenarios.createCategory |
DELETE /scenarios/categories/{categoryId} | scenarios.write | scenarios.deleteCategory |
GET /scenarios/categories/{categoryId}/deletion | scenarios.read | scenarios.getCategoryDeletionImpact |
PATCH /scenarios/categories/{categoryId}/knowledge-binding | scenarios.write | scenarios.updateKnowledgeBinding |
PATCH /scenarios/categories/{categoryId}/name | scenarios.write | scenarios.renameCategory |
POST /scenarios/import | scenarios.write | scenarios.import |
POST /scenarios/import/parse | scenarios.read | scenarios.parseImport |
POST /scenarios/import/preview | scenarios.read | scenarios.previewImport |
GET /scenarios/{scenarioId} | scenarios.read | scenarios.get |
PATCH /scenarios/{scenarioId} | scenarios.write | scenarios.update |
DELETE /scenarios/{scenarioId} | scenarios.write | scenarios.delete |
Requests and responses
GET /scenarios
list
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
limit | query | no | integer | format=int32; default=25 | Page size. |
offset | query | no | integer | format=int32; default=0 | Offset. |
search | query | no | string | default="" | Name contains. |
categories | query | no | array[string] | default=[] | Category path. |
includeDescendants | query | no | boolean | default=true | Include scenarios from descendant categories. |
Success response: HTTP 200 — scenarioList.
Response fields: total (integer), scenarios (array).
POST /scenarios
create
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
scenarioId | body | no | string | default="unique()" | Scenario ID. |
categories | body | yes | array[string] | — | Ordered category path. |
name | body | yes | string | — | Scenario name. |
definition | body | no | string | default="" | Scenario definition. |
Success response: HTTP 201 — scenario.
Response fields: $id (string), $createdAt (string), $updatedAt (string), $permissions (array), name (string), categories (array), definition (string), revision (integer).
GET /scenarios/categories
listCategories
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
limit | query | no | integer | format=int32; default=100 | Page size. |
offset | query | no | integer | format=int32; default=0 | Offset. |
Success response: HTTP 200 — scenarioCategoryList.
Response fields: total (integer), categories (array).
POST /scenarios/categories
createCategory
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
categories | body | yes | array[string] | — | Ordered category path. |
Success response: HTTP 201 — scenarioCategory.
Response fields: $id (string), $createdAt (string), $updatedAt (string), $permissions (array), knowledgeBindings (object), knowledgeBaseId (string), knowledgeTagPath (string), revision (integer), categories (array).
DELETE /scenarios/categories/{categoryId}
deleteCategory
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
categoryId | path | yes | string | — | Category ID. |
token | body | yes | string | — | Token from the reviewed deletion impact. |
Success response: HTTP 204 — No content.
GET /scenarios/categories/{categoryId}/deletion
getCategoryDeletionImpact
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
categoryId | path | yes | string | — | Category ID. |
Success response: HTTP 200 — scenarioCategoryImpact.
Response fields: token (string), categories (array), scenarios (array).
PATCH /scenarios/categories/{categoryId}/knowledge-binding
updateKnowledgeBinding
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
categoryId | path | yes | string | — | Category ID. |
revision | body | yes | integer | format=int32 | Expected binding revision. |
knowledgeBaseId | body | no | string | default="" | Knowledge Base ID, or empty to unlink. |
knowledgeTagPath | body | no | string | default="" | Full tag directory path, or empty to unlink. |
knowledgeBindings | body | no | array[array] | — | Knowledge directory bindings; empty list unlinks all. |
Success response: HTTP 200 — scenarioCategory.
Response fields: $id (string), $createdAt (string), $updatedAt (string), $permissions (array), knowledgeBindings (object), knowledgeBaseId (string), knowledgeTagPath (string), revision (integer), categories (array).
PATCH /scenarios/categories/{categoryId}/name
renameCategory
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
categoryId | path | yes | string | — | Category ID. |
revision | body | yes | integer | format=int32 | Expected category revision. |
name | body | yes | string | — | New category name. |
Success response: HTTP 200 — scenarioCategory.
Response fields: $id (string), $createdAt (string), $updatedAt (string), $permissions (array), knowledgeBindings (object), knowledgeBaseId (string), knowledgeTagPath (string), revision (integer), categories (array).
POST /scenarios/import
import
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
entries | body | yes | array[object] | — | Scenarios to import atomically. |
conflictPolicy | body | no | string | enum=error, skip, overwrite; default="error" | Existing path and name: reject, skip, or overwrite. Unchanged overwrites are skipped. |
Success response: HTTP 201 — scenarioImport.
Response fields: total (integer), scenarios (array), created (integer), updated (integer), skipped (integer).
POST /scenarios/import/parse
parseImport
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
file | formData | yes | file | — | CSV, XLS, or XLSX scenario file. Files are parsed without storage or scenario writes. |
Success response: HTTP 200 — scenarioImportFile.
Response fields: sheets (array).
POST /scenarios/import/preview
previewImport
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
entries | body | yes | array[object] | — | Scenarios to preview without writing. |
conflictPolicy | body | no | string | enum=skip, overwrite; default="skip" | Preview skipping or overwriting existing scenarios. Import re-evaluates conflicts when submitted. |
Success response: HTTP 200 — scenarioImportPreview.
Response fields: total (integer), entries (array), created (integer), updated (integer), skipped (integer).
GET /scenarios/{scenarioId}
get
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
scenarioId | path | yes | string | — | Scenario ID. |
Success response: HTTP 200 — scenario.
Response fields: $id (string), $createdAt (string), $updatedAt (string), $permissions (array), name (string), categories (array), definition (string), revision (integer).
PATCH /scenarios/{scenarioId}
update
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
scenarioId | path | yes | string | — | Scenario ID. |
revision | body | yes | integer | format=int32 | Expected revision. |
categories | body | no | array[string] | — | Ordered category path. |
name | body | no | string | — | Scenario name. |
definition | body | no | string | — | Scenario definition. |
Success response: HTTP 200 — scenario.
Response fields: $id (string), $createdAt (string), $updatedAt (string), $permissions (array), name (string), categories (array), definition (string), revision (integer).
DELETE /scenarios/{scenarioId}
delete
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
scenarioId | path | yes | string | — | Scenario ID. |
revision | body | yes | integer | format=int32 | Expected revision. |
Success response: HTTP 204 — No content.
Errors and boundaries
400/422: check types, enumerations and rules. 401/403: verify identity and scopes; dataset analyses additionally require trace and dataset read access. 404: check that the resource exists in the current project. 409: read current state before deciding to retry. 429: honor Retry-After. After 5xx or network loss, inspect operation state first. Preserve an idempotency key across retries; change it only for a deliberate new operation. Confirm deletion and clearing targets before writing.
Server SDK mapping
The scenarios entries above map to the Node Scenarios service. Python uses snake_case; verify Java/Go signatures against their matching distributions instead of inferring positional arguments from Node. The following request lists scenarios with server injected environment variables.
(
set +x
set -o pipefail
: "${AGENTBASE_API_KEY:?Set AGENTBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "${AGENTBASE_API_KEY:?Set AGENTBASE_API_KEY}" | curl --disable --header @- --fail-with-body --get "$AGENTBASE_ENDPOINT/scenarios" \
-H "X-Appwrite-Project: $AGENTBASE_PROJECT_ID" \
--data-urlencode "limit=25" --data-urlencode "offset=0"
)Import entries are an array of objects with categories/name/definition. The generated array[array] schema and Node TypeScript any[][] annotation are too narrow. This page shows the server validated JSON shape; JavaScript examples reuse parseImport entries. Isolate this annotation mismatch in TypeScript, and do not treat a type assertion as server validation.