# Assets

## Overview

Assets are images or video files referenced in assignment files or notes. For example, you might add a screenshot of your software to show a learner where to click. Or you might show a video before your learner starts a challenge.

{% hint style="warning" %}
Assets can only be managed from Instruqt CLI, or directly via the [API](broken://pages/Mz4UAWKsrPjHpzaz6GNC).
{% endhint %}

## Insert assets

Place all your assets in a directory called  `assets` located in the track root directory like in the following example:

```markdown
.
├── 01-title
│   └── assignment.md
├── assets
│   ├── image.png
│   └── video.mp4
├── config.yml
└── track.yml
```

↳ Here the `assets` directory contains a `png` image file and an `mp4` video file. 

### Refer to assets

Refer to assets by using the relative paths. For example, refer to `../assets/img.png` if you want to use the `img.png` file within the `assignment.md` file. The `../` part of the path tells to go up one directory and from there the `assets/` part tells to go to the `assets` subdirectory.

 You can also create nested folders inside the assets directory to keep them organized.

{% hint style="warning" %}
**Windows file paths**

When working from a Windows machine, use the backslash as the directory separator in your relative path— for example, `..\assets\img.png`. Otherwise, you will get an error stating that your asset does not exist when pushing your track to the Instruqt platform.
{% endhint %}

### Local and remote assets

#### Push

Your assets are also pushed when you push a track to the Instruqt platform. And the relative paths to images and videos are converted to fully qualified URLs. So they can be viewed in the sandbox by your learners. 

For example, if your local track has this code in an `assignment.md` file:

```
![My Image](../assets/image.png)
```

The `instruqt track push` command automatically converts this to:

```
![My Image](https://play.instruqt.com/assets/tracks/[TRACK_ID]/[ASSET_HASH]/assets/image.png
```

#### Pull

When you pull a track to your machine, the fully qualified URLs are converted into relative paths to images and videos so you can preview your files locally.

{% hint style="info" %}
**Work with assets from your code editor**

You can install a Markdown plugin in your code editor to make it easy to insert videos and images. The [Markdown All in One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one) plugin works well with VS Code. Point the `completion.root` setting to your `assets` directory and VS Code will show a handy autocomplete menu when you start to insert image code in your markdown.
{% endhint %}

## Examples

#### Embed an image into the assignment text

This example embeds an image in the `assignment.md` sidebar text. This is useful for showing a screenshot or other image to your learner as part of the challenge instructions:

{% tabs %}
{% tab title="YAML/Markdown" %}

```yaml
---
slug: my-challenge
id: un6vygpcp3mj
type: challenge
title: My Challenge
tabs:
- title: Google tab
  type: website
  url: https://google.com
difficulty: basic
timelimit: 600
---

Hello there, assets!
![Image Description](../assets/image.png)
```

{% endtab %}
{% endtabs %}

#### Embed a video in a challenge note

This example embeds a video in a challenge note. Notice the relative path format on line 12 of the `assignment.md` file:

{% tabs %}
{% tab title="YAML/Markdown" %}

```yaml
---
slug: title
id: un6vygpcp3mj
type: challenge
title: Title
tabs:
- title: Challenge title
  type: website
  url: https://google.com
notes:
- type: video
  url: ../assets/video.mp4
difficulty: basic
timelimit: 600
---

See the video URL on line 12 of this file.
```

{% endtab %}
{% endtabs %}

#### Embed an image in the track description

This example embeds an image in the track description. Notice how there is only a single dot before the slash `./` which means the `assets` directory is in the current directory:

{% tabs %}
{% tab title="YAML/Markdown" %}

```yaml
slug: my-new-track
id: 7gespmlsjdzq
type: track
title: Track Title Here
teaser: This is the best track ever!
description: |-
  Want to put an image in your track description? It's easy:
  ![Image Description](./assets/image.png)
```

{% endtab %}
{% endtabs %}

## Assets API

Then assets API is HTTP based and in order to consume it you must have a valid *authentication token* (will be referred as **token**). The API supports uploading, fetching and getting information about your asset.

### Uploading asset

#### Request

HTTP Method: **POST**\
\
`https://play.instruqt.com/assets/tracks/<track_id>`\
↳ Replace `<track_id>`&#x20;

#### Request headers

| Name            | Value            |
| --------------- | ---------------- |
| `Authorization` | `Bearer <token>` |

#### Response

Asset MD5 hash value encoded to string will be returned in response body.

### Fetching asset

#### Request

HTTP Method: **GET**\
\
`https://play.instruqt.com/assets/tracks/<track_id>/<asset_hash>`

#### Request headers

<table><thead><tr><th width="374">Name</th><th>Value</th></tr></thead><tbody><tr><td><code>Authorization</code></td><td><code>Bearer </code><strong><code>token</code></strong></td></tr></tbody></table>

#### Response

Asset will be returned in response body as a binary stream.

**Response headers**

| Name             | Value                                    |
| ---------------- | ---------------------------------------- |
| `Content-Length` | Size of a requested asset in bytes       |
| `Content-Type`   | Content-type of an asset, f.e. image/png |

### Asset info

#### Request

HTTP Method: **HEAD**\
\
`https://play.instruqt.com/assets/tracks/<track_id>/<asset_hash>`

#### Response

Empty

#### Response headers

| Name             | Value                              |
| ---------------- | ---------------------------------- |
| `Content-Length` | Size of a requested asset in bytes |

### HTTP status codes

| Code | Meaning                                                     |
| ---- | ----------------------------------------------------------- |
| 200  | Request was successful                                      |
| 404  | Requested asset not found                                   |
| 500  | Internal Instruqt error or error in the underlying storage. |

### Use assets in assignments

You can refer to an uploaded asset inside a markdown using the same URL which is used to fetch an uploaded asset

`https://play.instruqt.com/assets/tracks/<track_id>/<asset_hash>`

#### Embed an image into the assignment text

This example embeds an image in the `assignment.md` sidebar text. This is useful for showing a screenshot or other image to your learner as part of the challenge instructions:

{% tabs %}
{% tab title="YAML/Markdown" %}

```yaml
---
slug: my-challenge
id: un6vygpcp3mj
type: challenge
title: My Challenge
tabs:
- title: Google tab
  type: website
  url: https://google.com
difficulty: basic
timelimit: 600
---

Hello there, assets!
![Image Description](https://play.instruqt.com/assets/tracks/mk9ukiebswjx/ed965e981aa26d375329f4bd1575bc49)
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.instruqt.com/reference/cli/assets.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.