> For the complete documentation index, see [llms.txt](https://developerdocs.instructure.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developerdocs.instructure.com/services/canvas/resources/ai_experiences.md).

# AI Experiences

API for creating, accessing and updating AI Experiences. AI Experiences are used to create interactive AI-powered learning scenarios within courses.

#### An AiExperience object looks like: <a href="#aiexperience" id="aiexperience"></a>

```js
// An AI Experience for interactive learning
{
  // The ID of the AI experience
  "id": 234,
  // The title for the AI experience
  "title": "Customer Service Simulation",
  // The description of the AI experience
  "description": "Practice customer service skills in a simulated environment",
  // The AI facts for the experience (optional)
  "facts": "You are a customer service representative...",
  // The learning objectives for this experience
  "learning_objective": "Students will practice active listening and problem-solving",
  // The pedagogical guidance for the experience
  "pedagogical_guidance": "A customer is calling about a billing issue",
  // The current published state of the AI experience
  "workflow_state": "published",
  // The course this experience belongs to
  "course_id": 1578941
}
```

## [List AI experiences](#method.ai_experiences.index) <a href="#method.ai_experiences.index" id="method.ai_experiences.index"></a>

[AiExperiencesController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb)

#### `GET /api/v1/courses/:course_id/ai_experiences`

**Scope:** `url:GET|/api/v1/courses/:course_id/ai_experiences`

Retrieve the paginated list of AI experiences for a course

#### Request Parameters:

| Parameter        | Type     | Description                                                                                                          |
| ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `workflow_state` | `string` | <p>Only return experiences with the specified workflow state.<br>Allowed values: published, unpublished, deleted</p> |
| `search_term`    | `string` | Only return experiences whose title matches the search term.                                                         |

Returns a list of [AiExperience](#aiexperience) objects.

## [Show an AI experience](#method.ai_experiences.show) <a href="#method.ai_experiences.show" id="method.ai_experiences.show"></a>

[AiExperiencesController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb)

#### `GET /api/v1/courses/:course_id/ai_experiences/:id`

**Scope:** `url:GET|/api/v1/courses/:course_id/ai_experiences/:id`

Retrieve an AI experience by ID

Returns an [AiExperience](#aiexperience) object.

## [Show new AI experience form](#method.ai_experiences.new) <a href="#method.ai_experiences.new" id="method.ai_experiences.new"></a>

[AiExperiencesController#new](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb)

#### `GET /api/v1/courses/:course_id/ai_experiences/new`

**Scope:** `url:GET|/api/v1/courses/:course_id/ai_experiences/new`

Display the form for creating a new AI experience

## [Show edit AI experience form](#method.ai_experiences.edit) <a href="#method.ai_experiences.edit" id="method.ai_experiences.edit"></a>

[AiExperiencesController#edit](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb)

#### `GET /api/v1/courses/:course_id/ai_experiences/:id/edit`

**Scope:** `url:GET|/api/v1/courses/:course_id/ai_experiences/:id/edit`

Display the form for editing an existing AI experience

## [Create an AI experience](#method.ai_experiences.create) <a href="#method.ai_experiences.create" id="method.ai_experiences.create"></a>

[AiExperiencesController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb)

#### `POST /api/v1/courses/:course_id/ai_experiences`

**Scope:** `url:POST|/api/v1/courses/:course_id/ai_experiences`

Create a new AI experience for the specified course

#### Request Parameters:

| Parameter              | Type              | Description                                                                                                      |
| ---------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------- |
| `title`                | Required `string` | The title of the AI experience.                                                                                  |
| `description`          | `string`          | The description of the AI experience.                                                                            |
| `facts`                | `string`          | The AI facts for the experience.                                                                                 |
| `learning_objective`   | Required `string` | The learning objectives for this experience.                                                                     |
| `pedagogical_guidance` | Required `string` | The pedagogical guidance for the experience.                                                                     |
| `workflow_state`       | `string`          | <p>The initial state of the experience. Defaults to 'unpublished'.<br>Allowed values: published, unpublished</p> |

Returns an [AiExperience](#aiexperience) object.

## [Update an AI experience](#method.ai_experiences.update) <a href="#method.ai_experiences.update" id="method.ai_experiences.update"></a>

[AiExperiencesController#update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb)

#### `PUT /api/v1/courses/:course_id/ai_experiences/:id`

**Scope:** `url:PUT|/api/v1/courses/:course_id/ai_experiences/:id`

Update an existing AI experience

#### Request Parameters:

| Parameter              | Type              | Description                                                                   |
| ---------------------- | ----------------- | ----------------------------------------------------------------------------- |
| `title`                | `string`          | The title of the AI experience.                                               |
| `description`          | `string`          | The description of the AI experience.                                         |
| `facts`                | `string`          | The AI facts for the experience.                                              |
| `learning_objective`   | Required `string` | The learning objectives for this experience.                                  |
| `pedagogical_guidance` | Required `string` | The pedagogical guidance for the experience.                                  |
| `workflow_state`       | `string`          | <p>The state of the experience.<br>Allowed values: published, unpublished</p> |

Returns an [AiExperience](#aiexperience) object.

## [Delete an AI experience](#method.ai_experiences.destroy) <a href="#method.ai_experiences.destroy" id="method.ai_experiences.destroy"></a>

[AiExperiencesController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb)

#### `DELETE /api/v1/courses/:course_id/ai_experiences/:id`

**Scope:** `url:DELETE|/api/v1/courses/:course_id/ai_experiences/:id`

Delete an AI experience (soft delete - marks as deleted)

Returns an [AiExperience](#aiexperience) object.

## [List student AI conversations](#method.ai_experiences.ai_conversations_index) <a href="#method.ai_experiences.ai_conversations_index" id="method.ai_experiences.ai_conversations_index"></a>

[AiExperiencesController#ai\_conversations\_index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb)

#### `GET /api/v1/courses/:course_id/ai_experiences/:id/ai_conversations`

**Scope:** `url:GET|/api/v1/courses/:course_id/ai_experiences/:id/ai_conversations`

Retrieve the latest AI conversation for each student in the course for this AI experience. Only available to teachers and course managers.

## [Show student AI conversation](#method.ai_experiences.ai_conversation_show) <a href="#method.ai_experiences.ai_conversation_show" id="method.ai_experiences.ai_conversation_show"></a>

[AiExperiencesController#ai\_conversation\_show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/ai_experiences_controller.rb)

#### `GET /api/v1/courses/:course_id/ai_experiences/:id/ai_conversations/:conversation_id`

**Scope:** `url:GET|/api/v1/courses/:course_id/ai_experiences/:id/ai_conversations/:conversation_id`

Retrieve a specific student's AI conversation with full message history. Only available to teachers and course managers.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developerdocs.instructure.com/services/canvas/resources/ai_experiences.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.