Scenes

Create Scene

POST https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/scenes

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

Request Body

scenerequired

Scene

The scene to create.

Curl

curl -L -X POST 'https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/scenes' \
-H 'Grpc-Metadata-X-Authorization-Bearer-Type: studio_api' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic WlpONVlON01ETU5HSQ==' \
--data '{
    "description": "Hero fights a huge dragon in the magic forest.",
    "characters": [
        {
            "character" : "workspaces/{workspace_id}/characters/{character_name}"
        }
    ],
    "displayName": "Forest Battle",
    "commonKnowledge": [
        "workspaces/{workspace_id}/common-knowledge/{common_knowledge_id}"
    ]
}'

Response

{
    "description": "Hero fights a huge dragon in the magic forest.",
    "characters": [
        {
            "character" : "workspaces/{workspace_id}/characters/{character_name}"
        }
    ],
    "displayName": "Forest Battle",
    "commonKnowledge": [
        "workspaces/{workspace_id}/common-knowledge/{common_knowledge_id}"
    ]
}

---

Get Scene

GET https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/scene/{scene_name}

Get a specific scene within a workspace.

Request Body

viewoptional

SceneItemView

Specifies standard view or view with meta info in the response.

Curl

curl -L -X GET 'https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/scenes/{scene_name}' \
-H 'Grpc-Metadata-X-Authorization-Bearer-Type: studio_api' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic WlpONVlON01ETU5HSQ=='

Response

{
    "name": "workspaces/{workspace_id}/scenes/forest_battle",
    "description": "Hero fights a huge dragon in the magic forest with axe",
    "sceneTriggers": [],
    "displayName": "Forest Battle",
    "meta": null,
    "commonKnowledge": [
        "workspaces/magic_world/common-knowledge/{common_knowledge_id}"
    ],
    "timePeriod": "",
    "characters": [
        {
            "character": "workspaces/{workspace_id}/characters/{character_name}",
            "displayTitle": "Axeon the Enchanted",
            "imageUri": "",
            "additionalAgentInfo": ""
        }
    ]
}

---

Deploy Scene

POST https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/scenes/{scene_name}:deploy

Asynchronously deploys the scene. 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 will reflect the updates during their interactions. In the event of a failure, the operation should be retried.

Curl

curl -L -X POST 'https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/scenes/{scene_name}:deploy' \
-H 'Grpc-Metadata-X-Authorization-Bearer-Type: studio_api' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic WlpONVlON01ETU5HSQ=='

Response

{
    "name": "workspaces/{workspace_id}/scenes/{scene_name}/operations/{operation_id}",
    "metadata": {
        "@type": "type.googleapis.com/ai.inworld.studio.v1alpha.DeploySceneAsyncMetadata"
    },
    "done": false
}

---

List Scenes

GET https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/scenes

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

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

• Single Filter: This filter accepts only the full resource name of the scene. For example, to filter a specific character, use scene.name=workspaces/{workspace_id}/scenes/{uuid}.
• Multiple Filters: You can also combine multiple filters using the 'OR' condition. For instance, to filter by two different scenes, use scene.name=workspaces/{workspace_id}/scenes/{uuid1} OR character.name=workspaces/{workspace_id}/scenes/{uuid2}.

Request Body

pageSizeoptional

int32

Indicates the number of items to retrieve per page. Default is 50.

pageTokenoptional

string

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

filteroptional

string

Scenes filter. Filters follow the Google AIP-160 guidelines

Curl

curl -L -X GET 'https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/scenes' \
-H 'Grpc-Metadata-X-Authorization-Bearer-Type: studio_api' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic WlpONVlON01ETU5HSQ=='

Response

{
    "scenes": [
        {
            "name": "workspaces/{workspace_id}/scenes/{scene_name}",
            "description": "Hero fights a huge dragon in the magic forest.",
            "sceneTriggers": [],
            "displayName": "Forest Battle",
            "meta": null,
            "commonKnowledge": [
                "workspaces/{workspace_id}/common-knowledge/{common_knowledge_id}"
            ],
            "timePeriod": "",
            "characters": [
                {
                    "character": "workspaces/{workspace_id}/characters/{character_name}",
                    "displayTitle": "Axeon the Enchanted",
                    "imageUri": "",
                    "additionalAgentInfo": ""
                }
            ]
        },
        {
            "name": "workspaces/{workspace_id}/scenes/{scene_name}",
            "description": "Fight with a dragon in the magic forest",
            "sceneTriggers": [],
            "displayName": "Forest Fight",
            "meta": null,
            "commonKnowledge": [],
            "timePeriod": "",
            "characters": [
                {
                    "character": "workspaces/{workspace_id}/characters/{character_name}",
                    "displayTitle": "Axeon the Enchanted",
                    "imageUri": "",
                    "additionalAgentInfo": ""
                }
            ]
        }
    ],
    "nextPageToken": ""
}

---

Update Scene

PATCH https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/scenes/{scene_name}

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

Request Body

scenerequired

Scene

The scene to update.

Curl

curl -L -X PATCH 'https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/scenes/{scene_name}' \
-H 'Grpc-Metadata-X-Authorization-Bearer-Type: studio_api' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic WlpONVlON01ETU5HSQ==' \
--data '{
    "description": "The hero completes the fight within the magic forest.",
    "characters": [
        {
            "character" : "workspaces/{workspace_id}/characters/{character_name}"
        }
    ],
    "displayName": "Forest Battle",
    "commonKnowledge": [
        "workspaces/{workspace_id}/common-knowledge/{common_knowledge_id}"
    ]
}'

Response

{
    "description": "The hero completes the fight within the magic forest.",
    "characters": [
        {
            "character" : "workspaces/{workspace_id}/characters/{character_name}"
        }
    ],
    "displayName": "Forest Battle",
    "commonKnowledge": [
        "workspaces/{workspace_id}/common-knowledge/{common_knowledge_id}"
    ]
}

---

Delete Scene

DELETE https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/scenes/{scene_name}

Delete a specific scene within a workspace.

Curl

curl -L -X DELETE 'https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/scenes/{scene_name}' \
-H 'Grpc-Metadata-X-Authorization-Bearer-Type: studio_api' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic WlpONVlON01ETU5HSQ=='

Response

{}

---

Check Deployment Status

GET https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/scenes/{scene_name}/operations/{operation_id}

Retrieves the current status of a long-running operation. Clients can use it 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

curl -L -X GET 'https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/scenes/{scene_name}/operations/{operation_id}' \
-H 'Grpc-Metadata-X-Authorization-Bearer-Type: studio_api' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic WlpONVlON01ETU5HSQ==' 

Response

{
    "name": "workspaces/{workspace_id}/scenes/{scene_name}/operations/operation_id",
    "metadata": {
        "@type": "type.googleapis.com/ai.inworld.studio.v1.DeploySceneAsyncMetadata"
    },
    "done": true,
    "response": {
        "@type": "type.googleapis.com/ai.inworld.studio.v1.DeploySceneAsyncMetadata"
    }
}

---

Schemas

Scene

nameoptional

string

Immutable. This field can't be set or changed via API. Automatically generated resource name by the system based on display_name property.

descriptionoptional

string

Scene's description. This field should give clear information about the scene.

sceneTriggersoptional

SceneTrigger

List of assigned triggers and scenes.

displayNameoptional

string

User specified name.

metaoptional

Meta

Immutable. This field can't be set or changed via API. Meta character information.

commonKnowledgeoptional

string

List of assigned common_knowledge (contains resource references).

timePeriodoptional

string

Current time period.

charactersoptional

SceneCharacterReference

List of references to scene characters.

Meta

totalTriggersoptional

int32

Immutable. This field can't be set or changed via API. Indicates the number of triggers created in scene.

totalCharactersoptional

int32

Immutable. This field can't be set or changed via API. Indicates the number of characters created in scene.

totalCommonKnowledgeoptional

int32

Immutable. This field can't be set or changed via API. Indicates the number of common knowledge created in scene.

SceneCharacterReference

characterrequired

string

The resource name of the referenced character. Format: workspaces/{workspace}/characters/{character}

displayTitleoptional

string

Immutable. This field can't be set or changed via API. Character display title.

imageUrioptional

string

Immutable. This field can't be set or changed via API. Character display image.

SceneTrigger

triggeroptional

string

Reference to the trigger.

descriptionoptional

string

Scene-trigger description.

SceneItemView

SceneGetView defines what dependency info should be provided in response. For now only Meta(s) part is optional

Name	Number	Description
SCENE_ITEM_VIEW_UNSPECIFIED	0	Not specified, equivalent to DEFAULT.
SCENE_ITEM_VIEW_DEFAULT	1	Scene information by default.
SCENE_ITEM_VIEW_WITH_META	2	Scene representation with meta.