Docs
Contents

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.

HTTPScopeSDK
GET /scenariosscenarios.readscenarios.list
POST /scenariosscenarios.writescenarios.create
GET /scenarios/categoriesscenarios.readscenarios.listCategories
POST /scenarios/categoriesscenarios.writescenarios.createCategory
DELETE /scenarios/categories/{categoryId}scenarios.writescenarios.deleteCategory
GET /scenarios/categories/{categoryId}/deletionscenarios.readscenarios.getCategoryDeletionImpact
PATCH /scenarios/categories/{categoryId}/knowledge-bindingscenarios.writescenarios.updateKnowledgeBinding
PATCH /scenarios/categories/{categoryId}/namescenarios.writescenarios.renameCategory
POST /scenarios/importscenarios.writescenarios.import
POST /scenarios/import/parsescenarios.readscenarios.parseImport
POST /scenarios/import/previewscenarios.readscenarios.previewImport
GET /scenarios/{scenarioId}scenarios.readscenarios.get
PATCH /scenarios/{scenarioId}scenarios.writescenarios.update
DELETE /scenarios/{scenarioId}scenarios.writescenarios.delete

Requests and responses

GET /scenarios

list

ParameterLocationRequiredTypeConstraints / defaultMeaning
limitquerynointegerformat=int32; default=25Page size.
offsetquerynointegerformat=int32; default=0Offset.
searchquerynostringdefault=""Name contains.
categoriesquerynoarray[string]default=[]Category path.
includeDescendantsquerynobooleandefault=trueInclude scenarios from descendant categories.

Success response: HTTP 200 — scenarioList.

Response fields: total (integer), scenarios (array).

POST /scenarios

create

ParameterLocationRequiredTypeConstraints / defaultMeaning
scenarioIdbodynostringdefault="unique()"Scenario ID.
categoriesbodyyesarray[string]—Ordered category path.
namebodyyesstring—Scenario name.
definitionbodynostringdefault=""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

ParameterLocationRequiredTypeConstraints / defaultMeaning
limitquerynointegerformat=int32; default=100Page size.
offsetquerynointegerformat=int32; default=0Offset.

Success response: HTTP 200 — scenarioCategoryList.

Response fields: total (integer), categories (array).

POST /scenarios/categories

createCategory

ParameterLocationRequiredTypeConstraints / defaultMeaning
categoriesbodyyesarray[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

ParameterLocationRequiredTypeConstraints / defaultMeaning
categoryIdpathyesstring—Category ID.
tokenbodyyesstring—Token from the reviewed deletion impact.

Success response: HTTP 204 — No content.

GET /scenarios/categories/{categoryId}/deletion

getCategoryDeletionImpact

ParameterLocationRequiredTypeConstraints / defaultMeaning
categoryIdpathyesstring—Category ID.

Success response: HTTP 200 — scenarioCategoryImpact.

Response fields: token (string), categories (array), scenarios (array).

PATCH /scenarios/categories/{categoryId}/knowledge-binding

updateKnowledgeBinding

ParameterLocationRequiredTypeConstraints / defaultMeaning
categoryIdpathyesstring—Category ID.
revisionbodyyesintegerformat=int32Expected binding revision.
knowledgeBaseIdbodynostringdefault=""Knowledge Base ID, or empty to unlink.
knowledgeTagPathbodynostringdefault=""Full tag directory path, or empty to unlink.
knowledgeBindingsbodynoarray[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

ParameterLocationRequiredTypeConstraints / defaultMeaning
categoryIdpathyesstring—Category ID.
revisionbodyyesintegerformat=int32Expected category revision.
namebodyyesstring—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

ParameterLocationRequiredTypeConstraints / defaultMeaning
entriesbodyyesarray[object]—Scenarios to import atomically.
conflictPolicybodynostringenum=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

ParameterLocationRequiredTypeConstraints / defaultMeaning
fileformDatayesfile—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

ParameterLocationRequiredTypeConstraints / defaultMeaning
entriesbodyyesarray[object]—Scenarios to preview without writing.
conflictPolicybodynostringenum=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

ParameterLocationRequiredTypeConstraints / defaultMeaning
scenarioIdpathyesstring—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

ParameterLocationRequiredTypeConstraints / defaultMeaning
scenarioIdpathyesstring—Scenario ID.
revisionbodyyesintegerformat=int32Expected revision.
categoriesbodynoarray[string]—Ordered category path.
namebodynostring—Scenario name.
definitionbodynostring—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

ParameterLocationRequiredTypeConstraints / defaultMeaning
scenarioIdpathyesstring—Scenario ID.
revisionbodyyesintegerformat=int32Expected 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.