Skip to main content

Knowledge

Create Knowledge

POST https://api.inworld.ai/studio/v1/workspaces/{workspace_name}/common-knowledge

Initiates the creation of a knowledge collection that requires subsequent deployment for activation.

Request Body

commonKnowledge Required

The knowledge collection to create.

knowledgeRecords Optional
Individual pieces of data to include in the knowledge collection.

curl -L -X POST 'https://api.inworld.ai/studio/v1/workspaces/magic_world/common-knowledge' \
-H 'Grpc-Metadata-X-Authorization-Bearer-Type: studio_api' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic WlpONVlON01ETU5HSQ==' \
-d '{
"description": "info about dragon",
"displayName": "Magic Dragon",
"knowledgeRecords": [
{
"text":"dragon lives in the magic forest"
}
]
}'

Get Knowledge

GET https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/common-knowledge/{common_knowledge_id}

Get a specific common knowledge entry within a workspace.

curl -L -X GET 'https://api.inworld.ai/studio/v1/workspaces/magic_world/common-knowledge/70adc1cc-8478-4ce9-860a-c70efded11b6' \
-H 'Grpc-Metadata-X-Authorization-Bearer-Type: studio_api' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic WlpONVlON01ETU5HSQ=='

Deploy Knowledge

POST https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/common-knowledge/{common_knowledge_id}:deploy

Asynchronously deploys knowledge collection. The deployment process is managed as a long-running operation (LRO).

The progress and result of this operation should be monitored using the returned LRO object. Upon successful completion, all characters that incorporate this knowledge collection reflect the updates during their interactions. In the event of a failure, the operation should be retried.

curl -L -X POST 'https://api.inworld.ai/studio/v1/workspaces/magic_world/common-knowledge/70adc1cc-8478-4ce9-860a-c70efded11b6:deploy' \
-H 'Grpc-Metadata-X-Authorization-Bearer-Type: studio_api' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic WlpONVlON01ETU5HSQ=='

List Knowledge

GET https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/common-knowledge/

Returns a list of knowledge collections that can be filtered by several criteria. When using pagination, ensure that all other parameters provided initially remain unchanged.

Query Parameters

pageSize int32 Optional

Max number of items to retrieve per page. Default is 50.

Use the following format to specify number: pageSize={number}

  • Example: https://api.inworld.ai/studio/v1/workspaces/magic_world/common-knowledge?pageSize=200

pageToken String Optional

A page token, received from a previous ListCommonKnowledge call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to ListCommonKnowledgeRequest must stay the same.

filter String Optional

Commonknowledge filter. Filters follow the Google AIP-160 Guidelines.

Filters can be applied to ListCommonKnowledgeRequest. Filters follow the Google AIP-160 Guidelines.

  • common_knowledge.name: This filter accepts only the full resource name of common_knowledge. For example, to filter a specific common knowledge item, use: common_knowledge.name=workspaces/{workspace_id}/common-knowledge/{uuid}.
  • Multiple Filters: You can also combine multiple filters using the 'OR' condition. For instance, to filter by two different common knowledge items, use: common_knowledge.name=workspaces/{workspace}/common-knowledge/{uuid1} OR common_knowledge.name=workspaces/{workspace}/common-knowledge/{uuid2}.
curl -L -X GET 'https://api.inworld.ai/studio/v1/workspaces/magic_world/common-knowledge/70adc1cc-8478-4ce9-860a-c70efded11b6' \
-H 'Grpc-Metadata-X-Authorization-Bearer-Type: studio_api' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic WlpONVlON01ETU5HSQ=='

Update Knowledge

PATCH https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/common-knowledge/{common-knowledge_id}

Updates the specified knowledge collection. Changes to knowledge are not reflected in conversation until the knowledge collection is deployed.

Request Body

commonKnowledge Required

The common knowledge to update.

curl -L -X PATCH 'https://api.inworld.ai/studio/v1/workspaces/magic_world/common-knowledge/70adc1cc-8478-4ce9-860a-c70efded11b6' \
-H 'Grpc-Metadata-X-Authorization-Bearer-Type: studio_api' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic WlpONVlON01ETU5HSQ==' \
-d '{
"description": "Information about the dragon",
"knowledgeRecords": [
{
"text":"Dragon is not nice"
},
{
"text":"Dragon is very strong"
}
]
}'

Delete Knowledge

DELETE https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/common-knowledge/{common_knowledge_id}

Delete a specific common knowledge entry within a workspace.

curl -L -X DELETE 'https://api.inworld.ai/studio/v1/workspaces/magic_world/common-knowledge/70adc1cc-8478-4ce9-860a-c70efded11b6' \
-H 'Grpc-Metadata-X-Authorization-Bearer-Type: studio_api' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic WlpONVlON01ETU5HSQ=='

Check Deployment Status

GET https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/common-knowledge/{common_knowledge_id}/operations/{operation_id}

Retrieves the current status of a long-running operation.

Many developers use this to periodically poll for the operation's result, following the interval recommendations provided by the API service. This approach is useful for tracking the progress and completion status of operations that are not immediately finalized.

curl -L -X GET 'https://api.inworld.ai/studio/v1/workspaces/magic_world/common-knowledge/70adc1cc-8478-4ce9-860a-c70efded11b6/operations/1704230000638-3DlHAa' \
-H 'Grpc-Metadata-X-Authorization-Bearer-Type: studio_api' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic WlpONVlON01ETU5HSQ=='

Schemas

CommonKnowledge

displayName

String Optional

Display name of the common knowledge.

description

String Optional

Free form description outlining the character's behavior and purpose.

memoryRecords [deprecated]

String Optional

A list of memory records in a flexible free form format. Maximum length of individual record is 255 characters. Maximum amount of records per knowledge is 10000.

knowledgeRecords

String Optional

A list of knowledge records objects. This is a replacement for memoryRecords. Memory records will be internally converted to knowledge records. The maximum number of entries in a list is 1000. Note you should specify knowledgeRecords going forward but not use both memoryRecords and knowledgeRecords at the same time.

KnowledgeRecord

Describes a single knowledge record.

Text Required

Free-form format that describes a single knowledge record. The maximum length is 600 characters.