# Voshi Developer Docs (complete)

> Voshi connects educational tools to Learning Management Systems (Canvas, Blackboard, Moodle, and other LTI 1.3 platforms). Most tools are hosted by Voshi: a web component built in the dashboard or uploaded, which receives a VoshiApi object carrying the launch, storage, files, and grade passback. A self-hosted tool instead receives launches as a signed JWT POSTed to its own HTTPS endpoints and calls the REST APIs directly.

# Welcome to Voshi

> Build an educational tool once, and reach every LMS through the Voshi platform.

Source: https://myeducator-llc.github.io/voshi-docs/

Voshi connects your educational tool to Learning Management Systems — Canvas, Blackboard, Moodle, and any other LTI 1.3 platform — without you writing a single line of LTI code, and without you running a server.

You describe the tool you want in the dashboard's **AI Builder**, or upload code you wrote yourself. Voshi hosts it, puts it in front of instructors, launches it inside their courses, keeps each student's work, and sends scores to the gradebook. Your tool is a small piece of browser code that talks to Voshi through one object, the **Voshi API**.

<Note>
Voshi is in early stages of development. These docs and the related features can and probably will change — we'll keep you appraised of changes that impact you.
</Note>

<Note>
**Building with an AI assistant?** The entire documentation is available as a single markdown file at [https://myeducator-llc.github.io/voshi-docs/llms-full.txt](https://myeducator-llc.github.io/voshi-docs/llms-full.txt) — point your assistant at that URL and it has everything. A page index lives at [/llms.txt](https://myeducator-llc.github.io/voshi-docs/llms.txt).
</Note>

## How it works

1. **You register your tool** in the [Voshi dashboard](https://zen.voshi.com/app/ltiaas/s/) — a name and a description.
2. **You build it.** Tell the AI Builder what the learner should be doing and it writes the tool; or write the code yourself and upload the folder. Either way, the result runs immediately in the dashboard's **Sandbox**, a practice course where you can open your tool as a student or as an instructor.
3. **You add locations.** A *location* is one thing in your tool an instructor can put in a course — a quiz, a chapter, a lab. A tool with a single activity has a single location.
4. **You publish.** Publishing makes a numbered version of your tool that courses can adopt.
5. **An instructor adds your tool** to a course. They pick one of your locations, and Voshi creates the link (and the gradebook column, for graded work).
6. **A student opens it.** Voshi loads your tool inside the course page and hands it the Voshi API: who launched, which location, and where to save their work.
7. **Your tool reports a score** (optional) with one call. Voshi puts it in the gradebook.

```mermaid
sequenceDiagram
    autonumber
    participant LMS
    participant Voshi
    participant Tool as Your tool (in the browser)
    LMS->>Voshi: Instructor places one of your locations
    LMS->>Voshi: Student opens the link
    Voshi->>Tool: Load your files, construct your element with the Voshi API
    Tool->>Voshi: Read and save the student's work (api.storage)
    Tool->>Voshi: Report a score (api.submitGrade)
    Voshi->>LMS: Sync the score to the gradebook
```

## What Voshi gives your tool

Everything arrives on one object, `api`, that Voshi passes to your tool when it starts:

- **Who launched**: a stable user ID, whether they are a student or course staff, and their name and email when they are staff. Students are anonymous to your tool.
- **Where**: the course and the school.
- **What**: which of your locations was opened.
- **Storage**: four places to keep JSON data and files — per course, per location, per student, and per student-at-a-location. No database to set up.
- **Grades**: `api.submitGrade()`, available whenever the launched location has a gradebook column.

## Start building

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Register a tool, build it in the AI Builder, run it in the Sandbox, and publish.
  </Card>
  <Card title="Concepts" icon="book" href="/concepts">
    Locations, extids, and placements — the vocabulary everything else uses.
  </Card>
  <Card title="How a hosted tool works" icon="puzzle-piece" href="/building/how-it-works">
    What your code is, what Voshi does for it, and the rules it lives by.
  </Card>
  <Card title="The Voshi API" icon="code" href="/api/overview">
    The one object your tool talks to: launch details, storage, files, and grades.
  </Card>
</CardGroup>

## Running your own server instead

Most tools are hosted by Voshi. If your tool needs its own backend — a database of its own, server-side grading, an existing product you are connecting — Voshi can hand launches to your server over HTTPS instead. That is a different integration, with endpoints to build and a signed token to verify. It is covered in [Advanced: your own server](https://myeducator-llc.github.io/voshi-docs/advanced/overview), and the choice is made once, when you register the tool.

---

# Quickstart

> Build your first Voshi tool: register, describe it to the AI Builder, run it in the Sandbox, and publish.

Source: https://myeducator-llc.github.io/voshi-docs/quickstart

This walkthrough takes you from nothing to a tool that instructors can place in a course. You will not write a server, configure a web host, or handle a login — Voshi does all of that. What you write (or have the AI write) is the tool itself.

## What you'll need

- A Voshi builder account — contact the MyEducator team if you don't have dashboard access yet.
- An idea of what the learner should be doing. That is the whole brief.

<Steps>
  <Step title="Register your tool">
    Open the [Voshi dashboard](https://zen.voshi.com/app/ltiaas/s/), go to **Tools → New Tool**, and fill in:

    - **Tool Name** — shown to instructors when they add your tool to a course.
    - **Hosting** — leave it on **Voshi Hosted**. This is the choice these docs describe, and it cannot be changed later. (**Self Hosted** means you run your own server; see [Advanced: your own server](https://myeducator-llc.github.io/voshi-docs/advanced/overview).)
    - **Description** — optional, but instructors see it.

    Your new tool opens on its **AI Builder** page.
  </Step>

  <Step title="Describe your tool">
    In the **Discuss Design** panel, say what the learner should be learning or doing. Write it the way you would explain it to a colleague:

    > A flashcard drill for ten accounting terms. The student flips each card, marks whether they knew it, and sees a score at the end. The score goes to the gradebook.

    The AI replies with questions or with a plan. Answer what matters to you; it fills in the rest. When you are ready, press the **build** button (the wand). Building takes a few minutes.
  </Step>

  <Step title="Run it">
    When the build finishes, the **Running Tool** panel on the right launches your tool for real, in your tool's private **Sandbox** course. Pick a location and a role — **student** or **instructor** — and use the tool exactly as a learner would.

    This is not a preview. The tool is saving data, checking roles, and reporting scores against a real course, so what works here works in a school's LMS.
  </Step>

  <Step title="Refine it">
    Keep talking in the chat. "Make the cards bigger." "Add a timer." "Let the instructor change the terms." Each build replaces your tool's **draft**, and the Running Tool panel reloads it.

    You can also take the code elsewhere: **Download Code** gives you the folder, including an `AGENTS.md` that briefs your own coding assistant on the rules, and **Upload Code** puts your edited folder back. See [Your tool's files](https://myeducator-llc.github.io/voshi-docs/building/files).
  </Step>

  <Step title="Check your locations">
    A **location** is one thing an instructor can put in a course. A one-activity tool has one location, called `home`, and the AI Builder creates it for you. Open the **Locations** tab to see what your tool offers, and to add more if your tool has several activities — one per graded thing, one per distinct thing a student can open. See [Locations](https://myeducator-llc.github.io/voshi-docs/building/locations).

    Only an `assessment` location can report a grade. Check its **points**: that becomes the gradebook column's value when an instructor places it.
  </Step>

  <Step title="Test like an instructor">
    The **Sandbox** tab is the course your tool has been running in. Its **Links** tab lets you place your locations the way an instructor would, through the same picker they see. Launch each link as a student and as an instructor, then check the Sandbox's **Launches** and **Grades** tabs to see what Voshi recorded. See [Testing in the Sandbox](https://myeducator-llc.github.io/voshi-docs/building/sandbox).
  </Step>

  <Step title="Publish">
    The Sandbox runs your **draft** — whatever you built or uploaded last. Courses never run the draft. When the tool is ready, **publish** it: Voshi records the draft as version 1, and that is the version a course gets when an instructor adds your tool. Later publishes make version 2, 3, and so on; courses keep the version they adopted until their instructor chooses to upgrade. See [Versions](https://myeducator-llc.github.io/voshi-docs/building/versions).
  </Step>

  <Step title="Go live">
    Your tool starts in **draft** status, which means instructors cannot see it yet. Once it works in the Sandbox and you have published a version, **contact the MyEducator team to activate your tool**. After activation, instructors can add it to their courses.
  </Step>
</Steps>

## Where to next

<CardGroup cols={2}>
  <Card title="How a hosted tool works" icon="puzzle-piece" href="/building/how-it-works">
    What your code is, what Voshi does for it, and the rules it lives by.
  </Card>
  <Card title="The Voshi API" icon="code" href="/api/overview">
    Launch details, storage, files, and grades — everything your tool can ask Voshi for.
  </Card>
  <Card title="Your tool's files" icon="folder" href="/building/files">
    What is in the folder, what manifest.json does, and how to edit the code yourself.
  </Card>
  <Card title="Versions" icon="code-branch" href="/building/versions">
    Draft, published versions, and how courses adopt them.
  </Card>
</CardGroup>

---

# Concepts

> Locations, extids, and other key terms — the vocabulary the rest of these docs is written in.

Source: https://myeducator-llc.github.io/voshi-docs/concepts

<CardGroup cols={2}>
  <Card title="Location" icon="location-dot" href="#location">
    A "thing" your tool provides that can be placed in a course.
  </Card>
  <Card title="Extid" icon="key" href="#extid">
    Your own permanent identifier for a location.
  </Card>
  <Card title="Placement" icon="link" href="#placement">
    An instructor putting one of your locations into their course.
  </Card>
</CardGroup>

## Location

A **location** is a "thing" that your tool provides.

**Every graded item in your tool should be one location**, and every non-graded thing you want a student to be able to open should be one too. A location's grades land in a single gradebook column, so if you want two graded activities, you define two locations.

Most tools offer several "things" that can be placed in a course. Locations are how you define them. For example:

- A quiz on architecture in the Persian Empire.
- A currency conversion tool your tool provides.
- A digital textbook titled *Introductory Law* that your tool publishes.

A tool that provides only one "thing" should define a single location. Hosted tools call that one location `home`.

### Internal and external identifiers

Every location has two IDs, and both arrive in every launch:

| ID | Assigned by | What it's for |
| --- | --- | --- |
| **extid** | **Your tool** | The primary way your tool identifies a location. A location is found by tool id + extid. |
| **location id** | Voshi | Voshi's internal identifier. These start with the letter `I` and are unique across the entire Voshi ecosystem — across tools, schools, and courses. |

Your tool should key its own data and its own routing on the **extid**. The internal ID is there for correlating with Voshi's dashboard and logs.

## Extid

Extids are the primary way tools identify locations — during instructor linking and during student launches.

An extid is how your tool declares that a resource exists and can be added to a course. **Each extid must represent a unique "thing" that has identity and can be linked within a course.**

Extids are created by **your tool**, not by Voshi and not by the LMS. That is deliberate: it means your tool controls what "location" means inside your product.

### Extids identify a resource everywhere

An extid should identify the same resource consistently across semesters, courses, and schools. If a quiz on Persian architecture has `extid = quiz1` in one course, that same quiz in a second course also has `extid = quiz1`.

<Warning>
**Defining your extids is one of the most important design decisions your tool makes.** Extids are permanent and **cannot be changed once they have been linked into a course.** When you design your extid strategy, think through:

- **Resource identity** — what counts as one distinct "thing" in your tool? What things are graded?
- **Cross-semester persistence** — if an instructor is teaching the same course again next semester, they will likely want the same locations (perhaps with minor changes). Will these ids still be valid then?
- **Provisioning** - what needs to be set up (database objects, etc.) when a new course starts? When a new semester starts?
</Warning>

### Rules for extids

- Extids may contain **letters, numbers, dashes, and underscores**. No other special characters.
- Extids should **not** normally include course-specific identifiers — no context id, semester code, or instructor id.

### When extids are used

1. **During placement**, when an instructor adds links to your tool in their course, Voshi shows them the locations your tool currently offers — each one an extid plus a label, a description, points, and so on. A hosted tool declares them in the dashboard or in its `manifest.json` (see [Locations](https://myeducator-llc.github.io/voshi-docs/building/locations)); a self-hosted tool answers a request from Voshi with the list (see [Serving your locations](https://myeducator-llc.github.io/voshi-docs/advanced/locations-endpoint)).
2. **Extids must be assigned during link placement, at course setup time.** They cannot be assigned later, during student launches.
3. **When a student clicks a link**, the launch names the linked extid. Your tool reads the extid and shows the matching resource, quiz, or tool. In a hosted tool it is `api.location.extid`.
4. **When your tool reports a grade**, the score goes to the gradebook column for that student at that location. The extid the instructor placed is what decides which column the score lands in.

### Examples of extid strategies

<Expandable title="Static extids: a music tool with five instruments">
A music tool provides five digital instruments for students to interact with. The builder decides each instrument is a linkable resource, and defines five static extids offered to every course: `clarinet`, `piano`, `trumpet`, `violin`, `timpani`.
</Expandable>

<Expandable title="Static extids: a test prep tool with three practice exams">
A test prep tool provides three practice exams. It defines three static extids offered to every course: `practice1`, `practice2`, `practice3`.
</Expandable>

<Expandable title="Dynamic extids: a lecture discussion app">
A discussion tool lets students post questions and answers during instructor lectures. Instructors are expected to place many links in a course — one per lecture day. Each link holds its own discussion and its own distinct data, so each link genuinely is its own "thing." Each time an instructor places a link, this tool generates a single `uuid4`-based extid as its available location. This tool therefore creates a large number of dynamic locations, one at a time as links are placed. Only a [self-hosted](https://myeducator-llc.github.io/voshi-docs/advanced/overview) tool can do this, because it needs a server to answer each placement with a fresh extid; a hosted tool offers a fixed list.
</Expandable>

## Placement

A **placement** is an instructor putting one of your locations into their course — the link students click. Placements happen through a content picker that Voshi presents: the instructor sees the locations your tool currently offers, picks one, and confirms. For a graded location, that's also when the gradebook column is created.

Placement is where an extid gets attached. Everything downstream — the launches students produce, the storage rows, the gradebook column your grades land in — follows from the extid the instructor placed.

### One location per thing

The rule that keeps an integration simple:

> **Define one location for each thing you want graded, and one location for each non-graded thing you want to show.**

If it needs its own gradebook column, it's its own location. If it's a distinct thing a student can open, it's its own location. Nothing else needs to exist.

<Warning>
**Don't design around placing the same location more than once in a course.** A location is one "thing" in your tool, and it should correspond to one link in the course and — when it's graded — one gradebook column.

If you want two graded activities, define two locations with two extids. Reaching for two placements of the same location instead means both links point at the same resource, share the same [storage](https://myeducator-llc.github.io/voshi-docs/api/storage) rows, and compete for the same gradebook column. All grades for a location go to a single column regardless of how many links exist, so the extra placement gets you nothing and confuses the instructor's gradebook.
</Warning>

### Duplicate placements happen anyway

Even though your tool shouldn't rely on them, duplicate links to the same location do occur, and you can't prevent them: instructors duplicate links, LMS platforms roll courses forward into new terms in their own ways, and a link deleted from one module can be added back in another. Your tool is never notified when any of that happens.

Your tool doesn't need to do anything about it — the behavior is already consistent:

- All launches carry the same `location.extid`, so they all resolve to the same resource in your tool.
- All of them share the same location storage rows.
- **Grades always go to the first gradebook line item** for that extid, so a student's score for a location always lands in the same place.

<Note>
This is exactly why Voshi identifies resources by location and extid. The individual links in the course — and the LTI `resource_link_id` behind them — are outside Voshi's control and shouldn't carry meaning in your tool. **Identify your resources by extid.**
</Note>

## Next

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Register a tool, build it, run it in the Sandbox, and publish.
  </Card>
  <Card title="Locations" icon="location-dot" href="/building/locations">
    Types, points, and how to declare the locations your tool offers.
  </Card>
</CardGroup>

---

# How a hosted tool works

> Your tool is a small piece of browser code. Voshi hosts it, launches it, and hands it everything it needs.

Source: https://myeducator-llc.github.io/voshi-docs/building/how-it-works

A hosted tool is a **web component**: one custom HTML element, defined in a JavaScript file, that Voshi loads inside the course page when someone opens your tool. Voshi does everything around it — the LMS integration, hosting your files on a CDN, logging the student in, placement in courses, provisioning, storage, and grade passback. Your code draws the activity and talks to Voshi through one object.

## The lifecycle of a launch

```mermaid
sequenceDiagram
    autonumber
    participant LMS
    participant Voshi
    participant Tool as Your element
    LMS->>Voshi: Student clicks your link in the course
    Voshi->>Tool: Load your files, then new YourTool(api)
    Tool->>Voshi: api.storage.memberLocation.get()
    Tool->>Tool: Render the activity
    Tool->>Voshi: api.submitGrade({ score: 0.8 })
    Voshi->>LMS: Score lands in the gradebook
```

1. **Someone opens your tool** from a course. Voshi handles the LMS side and works out who they are, which course they are in, and which of your [locations](https://myeducator-llc.github.io/voshi-docs/building/locations) the link points at.
2. **Voshi loads your code** — the version of your tool that course runs — and your styles and templates.
3. **Voshi constructs your element**, passing it one argument: the [Voshi API](https://myeducator-llc.github.io/voshi-docs/api/overview), already loaded with the launch details and ready to call.
4. **Your element renders** whatever the learner should see, reads any saved work from `api.storage`, and, when the learner finishes graded work, calls `api.submitGrade()`.

The page around your element belongs to Voshi. It watches your element's height and tells the LMS, so the frame fits your content — give your element `:host { display: block }` and it just works.

## What your code looks like

The smallest possible tool:

```javascript
// app.js
class HelloTool extends HTMLElement {
    constructor(api) {
        super()
        this.api = api                          // keep the Voshi API for later
        this.attachShadow({ mode: 'open' })     // your markup and styles live in here
    }

    connectedCallback() {
        const name = this.api.isStaff ? this.api.user.full_name : 'there'
        this.shadowRoot.innerHTML = `<p>Hello, ${name}. You opened ${this.api.location.label}.</p>`
    }
}

customElements.define('hello-tool', HelloTool)
```

Three things every tool does, and the AI Builder does them for you:

- **The constructor takes `api` and stores it.** It attaches a shadow root and nothing else; browsers forbid a constructor from touching the page.
- **Rendering happens in `connectedCallback`**, after the element is on the page. Query `this.shadowRoot`, never `document` — your element's markup is inside the shadow root, and `document.querySelector` cannot see it. This is the most common mistake in hand-written tools.
- **The tag is registered with `customElements.define`.** The tag must be lowercase and contain a dash.

A real tool usually keeps its markup in `index.html` and its styles in `styles.css`, which Voshi loads for it and hands over as `api.assets`. See [Your tool's files](https://myeducator-llc.github.io/voshi-docs/building/files) and [Assets](https://myeducator-llc.github.io/voshi-docs/api/assets).

## What Voshi does for you

| Need | How it is met |
| --- | --- |
| Hosting | Your files are served from a CDN. Upload or build, and they are live in the Sandbox. |
| Login and identity | `api.user` says who launched, with a stable ID. No passwords, no accounts, no sessions to manage. |
| Which course, which activity | `api.course` and `api.location`. |
| Saving work | `api.storage` — four JSON rows per launch, plus files on each. See [Storage](https://myeducator-llc.github.io/voshi-docs/api/storage). |
| Grades | `api.submitGrade()`. See [Grades](https://myeducator-llc.github.io/voshi-docs/api/grades). |
| Course setup | Automatic. When a course is copied into a new term, its course and location storage come along. |
| Placement in courses | Instructors pick from your [locations](https://myeducator-llc.github.io/voshi-docs/building/locations) in a picker Voshi presents. |
| Versions | You publish; courses adopt a version and keep it. See [Versions](https://myeducator-llc.github.io/voshi-docs/building/versions). |

## The rules

Hosted tools run inside other people's course pages, so a few things are off limits. Voshi checks what it can at upload time, and the AI Builder already follows them.

- **No server, no network calls of your own.** Everything your tool needs from the platform comes through `api`; the only thing it ever fetches is its own files, through `api.assets`. There is no API key, because there is no server to keep one on.
- **No libraries, no CDNs, no build step.** Your files are plain JavaScript, CSS, and HTML, served exactly as uploaded. `import` other files of your own by relative path; a bare name like `import 'lit'` cannot be resolved.
- **No `localStorage` or `sessionStorage`.** Nothing about a learner may be kept in the browser. Use `api.storage`.
- **No `document` queries, no `eval`.** Work inside `this.shadowRoot`.
- **Keep state in the element** unless it must survive between visits, in which case it goes in `api.storage`.

## Where things happen

Everything about your tool lives in the [dashboard](https://myeducator-llc.github.io/voshi-docs/building/dashboard): building, testing, locations, versions, logs. There is nothing to configure anywhere else.

## Next

<CardGroup cols={2}>
  <Card title="The dashboard" icon="table-columns" href="/building/dashboard">
    AI Builder, Sandbox, Locations, Launches, Grades, Pricing, Settings.
  </Card>
  <Card title="The Voshi API" icon="code" href="/api/overview">
    Everything on the `api` object.
  </Card>
</CardGroup>

---

# The dashboard

> Where you build, test, and manage your tool: a tour of each tab.

Source: https://myeducator-llc.github.io/voshi-docs/building/dashboard

Everything about a hosted tool happens in the [Voshi dashboard](https://zen.voshi.com/app/ltiaas/s/). Open **Tools**, pick your tool, and the tabs below are down the left side.

<Note>
**The dashboard calls tools "tools".** These docs say *tool* for what you build and *tool* only where the API does; the two mean the same thing.
</Note>

## AI Builder

Your tool's first page, and where it gets built. The page has two panels:

- **Discuss Design** on the left is a conversation. Describe what the learner should be doing; the AI asks what it needs to know and says when it has enough. The **build** button (the wand) hands the whole conversation to the builder, which writes the tool and uploads it as your **draft**. A correction is just another message, followed by another build. A message that led things astray can be set aside (dimmed and struck through, reversibly) so the next build ignores it. **New conversation** starts over against the same tool; past conversations are kept.
- **Running Tool** on the right launches your draft — a real launch, in your tool's [Sandbox](https://myeducator-llc.github.io/voshi-docs/building/sandbox) course. Choose which location to launch and whether to launch as a **student** or an **instructor**. Both roles share one course, so an instructor launch sees what the student launch just saved, exactly as in a real course. **Refresh** launches again.

The Running Tool header also holds the two code controls:

- **Download Code** gives you the draft as a zip. It includes an `AGENTS.md` that briefs a coding assistant (Claude Code, Cursor, and the like) on the rules of a hosted tool, so you can edit the code outside the dashboard and bring it back.
- **Upload Code** takes a folder from your computer and makes it the draft. Choose the folder that holds `manifest.json`, or that holds `app.js` if there is no manifest.

See [Your tool's files](https://myeducator-llc.github.io/voshi-docs/building/files) for what is in the folder.

## Sandbox

A private practice course that only you can see, with your tool already in it. Its tabs mirror what a course has:

- **Links** are placements of your tool in the Sandbox course. **New Link** opens the same picker an instructor uses, so you can place any of your locations and launch it as a student or an instructor. **Reset** throws away everything stored at a link, so the next launch starts as a first launch; **Remove** deletes the link.
- **Launches** lists every launch in the Sandbox.
- **Grades** is the Sandbox's gradebook: the scores your tool reported, by link and by persona.

The Sandbox always runs your **draft**. See [Testing in the Sandbox](https://myeducator-llc.github.io/voshi-docs/building/sandbox).

## Locations

The destinations your tool offers an instructor — each with a **name**, an **external ID** (your tool's own, permanent identifier for it), a **Voshi ID**, and a **type**. **Add Location** adds one; **Edit** changes its label and type; **Stop offering** hides it from the picker without breaking links already placed. A tool with one activity has one location, `home`. See [Locations](https://myeducator-llc.github.io/voshi-docs/building/locations).

## Launches

Every launch of your tool, from every course: when, which course, which user, which location, and whether it succeeded. Filter by course, user, or location to follow one student's path, or to see whether a particular placement is being used.

## Grades

Every score your tool reported, from every course, with the result the LMS gave. A score the LMS refused shows here with the reason. Open one to see the full record.

## Pricing

Whether a student pays to launch your tool, and how much, with different prices for different audiences. A tool with no prices is free. Pricing is described on the Pricing tab itself and on Voshi's website; it is not part of your code — a paying student is sent to checkout before your tool is launched, and your tool never knows the difference.

## Settings

The tool's identity: its **Tool ID**, its **platform status**, its **hosting** (which was fixed at registration), and the **name** and **description** instructors see.

| Platform status | Meaning |
| --- | --- |
| **Draft** | The initial status. Instructors cannot see the tool, and it launches only from the Sandbox. |
| **Active** | Live: instructors can add it to courses. |
| **Suspended** | Disabled by the platform team. |

Only the Voshi platform team changes the status. When your tool works in the Sandbox and you have [published](https://myeducator-llc.github.io/voshi-docs/building/versions) a version, contact the MyEducator team to activate it.

A hosted tool has **no API key** and no URLs to configure, because it has no server. Those fields exist only for a [self-hosted](https://myeducator-llc.github.io/voshi-docs/advanced/overview) tool.

## Team members

Tools are managed by their members, and membership is flat: every member has full rights over the tool. The dashboard has no members screen yet — ask the MyEducator team to add or remove teammates.

---

# Your tool's files

> What is in a hosted tool's folder, what manifest.json does, and how to edit the code outside the dashboard.

Source: https://myeducator-llc.github.io/voshi-docs/building/files

A hosted tool is a folder of plain browser files. The AI Builder writes the folder for you; **Download Code** hands it to you as a zip, and **Upload Code** takes it back. Nothing in it is compiled, bundled, or installed — what you upload is what runs.

## The folder

A typical tool:

```
my-tool/
├── manifest.json     how to load the tool, and the locations it offers
├── app.js            the entry: defines the custom element
├── styles.css        the tool's styles
├── index.html        the tool's markup
└── lib/
    └── scoring.js    another module, imported by app.js
```

| File | Role |
| --- | --- |
| **The entry** (`app.js`) | Required. An ES module that defines your element and calls `customElements.define`. It is the only file Voshi imports; everything else it loads is what the entry imports or the manifest names. |
| **Stylesheets** (`.css`) | Voshi loads them and adopts them into your element's shadow root before it renders, so your styles apply without you doing anything. See [Assets](https://myeducator-llc.github.io/voshi-docs/api/assets). |
| **Templates** (`.html`) | Markup fragments — no `<html>`, `<head>`, `<body>`, `<script>`, or `<style>`. Voshi loads them and you render one with `api.assets.template('index.html')`. |
| **Other modules** (`.js`, `.mjs`) | Imported by the entry or by each other, with relative paths: `import { score } from './lib/scoring.js'`. The `.js` extension is required; the browser has no module resolver. A `.json` file can be imported too: `import words from './words.json' with { type: 'json' }`. |
| **Everything else** | Images, fonts, data files. Reach one with `api.assets.url('map.png')`. |

**Everything in the folder is uploaded**, at its own path. Left out on purpose: dotfiles and dot-folders (`.git`, `.env`), `node_modules`, `__MACOSX`, and `AGENTS.md`. Anything else you leave in the folder — a `README`, a scratch `preview.html` — is published with the tool, so delete what you don't want served.

### Limits

| | Limit |
| --- | --- |
| One file | 10 MB |
| The whole tool | 50 MB, 200 files |
| `manifest.json` | 64 KB, at most 200 locations |
| Stylesheets and templates together | 20, because every one is fetched on every launch |
| Paths | Letters, digits, `.`, `_`, `-`; no name starting with `-`; at most 4 folders deep. Two paths that differ only in case are refused. |

## manifest.json

The manifest sits at the root of the folder and says two things: how Voshi should load the tool, and which [locations](https://myeducator-llc.github.io/voshi-docs/building/locations) it offers. It does not list the tool's files.

```json
{
  "manifest_version": 2,
  "app": {
    "entry": "app.js",
    "tag": "flashcard-drill",
    "styles": ["styles.css"],
    "templates": ["index.html"]
  },
  "locations": {
    "home": {
      "type": "assessment",
      "label": "Flashcard Drill",
      "description": "Ten accounting terms, flipped and self-marked.",
      "points": 10
    }
  }
}
```

| Key | Meaning |
| --- | --- |
| `manifest_version` | `2`. (A version 1 manifest has no `app` section and is still accepted.) |
| `app.entry` | The entry module. Without it, Voshi uses the folder's only `.js` file, or else `app.js`. |
| `app.tag` | The custom element tag the entry defines. Optional, but if present it must match. |
| `app.styles` | The stylesheets to load, in order. Leave it out to load every `.css` in the folder; `[]` loads none. |
| `app.templates` | The templates to load. Leave it out to load every `.html` in the folder; `[]` loads none. |
| `locations`, `grouped_locations` | The locations the tool offers, in the same shape a self-hosted tool [serves](https://myeducator-llc.github.io/voshi-docs/advanced/locations-endpoint#the-response). See [Locations](https://myeducator-llc.github.io/voshi-docs/building/locations) for what uploading one does to the Locations tab. |

A manifest can declare the locations and leave `app` out, or the other way round. An upload with no `manifest.json` at all keeps the tool's locations exactly as they are.

## Editing the code yourself

The AI Builder is one way to write a tool, not the only one. The code it produces is ordinary and readable, and the loop for editing it elsewhere is:

<Steps>
  <Step title="Download Code">
    From the Running Tool panel. The zip holds the draft, plus an `AGENTS.md` written for a coding assistant: it states the rules of a hosted tool, lists the tool's locations, and says what the platform will refuse. Point Claude Code, Cursor, or whatever you use at the folder and it knows what it is editing. The file is skipped on upload, so leave it there.
  </Step>
  <Step title="Edit">
    Any editor. There is no build step, so there is nothing to install or run. For layout work, `AGENTS.md` includes a small `preview.html` you can serve from the folder with any static server; grades and storage only work in a real launch, so test those in the Sandbox.
  </Step>
  <Step title="Upload Code">
    Choose the folder. The upload replaces the draft, and the Running Tool panel reloads. If the upload is refused, the message names the file and the rule — a missing import, a bare module name, an entry that defines a different tag than the manifest says.
  </Step>
</Steps>

<Warning>
**Every upload replaces the whole draft.** The previous draft is gone; there is no history of drafts. Keep your own copy of code you care about, and [publish](https://myeducator-llc.github.io/voshi-docs/building/versions) when a draft is worth keeping — a published version is permanent.
</Warning>

### The `api.assets` rule

Your files are served from a directory named by their content hash, so every upload and every version lives at a different address. Never write an absolute URL to one of your own files, and never fetch `styles.css` or `index.html` yourself: Voshi has already loaded them. Use [`api.assets`](https://myeducator-llc.github.io/voshi-docs/api/assets) — `template()`, `styles`, `url()` — and the right copy is always the one you get.

## What the platform refuses

These are the upload's own messages, so you can recognize them:

- `manifest.json names styles.css, which is not in the upload`
- `More than one .js file could be the entry (a.js, b.js): add a manifest.json whose app.entry names it, or name it app.js`
- `The upload has no .js file: upload the module that defines the custom element`
- `app.js imports ./lib/cards.js, which is not in the upload`
- `app.js imports ./styles.css: the page loads stylesheets itself (every .css, or manifest.json app.styles)`
- `app.js imports 'lit', a bare module name, and nothing on the page can resolve one`
- `app.js imports ../../x.js, which is outside the tool`
- `manifest.json says app.tag is 'my-tool', and app.js defines 'other-tool': make them the same`
- `App.js and app.js differ only in case; rename one of them`
- `media/video.mp4 is larger than 10 MB` / `The tool is larger than 50 MB in total`

---

# Locations

> The destinations in your tool that instructors can place in their courses, and how a hosted tool declares them.

Source: https://myeducator-llc.github.io/voshi-docs/building/locations

A **location** is one thing in your tool an instructor can put in a course — a quiz, a chapter, a lab, a practice set. When an instructor adds your tool to a course, they choose a location, and every launch from that link tells your tool which one it is for.

A tool with a single activity has a single location, called **`home`**. A tool that is genuinely several activities — a practice set and the quiz that follows it, four separate labs — has one location per activity, and the instructor places whichever they want where they want it.

<Note>
If you haven't read [Concepts](https://myeducator-llc.github.io/voshi-docs/concepts) yet, start there. It defines locations, extids, and placements, and explains why the extid you choose is the most consequential decision you make.
</Note>

## What a location is made of

| Field | Meaning |
| --- | --- |
| **External ID** (`extid`) | Your tool's own name for the location: `home`, `ch3_quiz`, `lab-2`. Letters, digits, dashes, and underscores. **Permanent**: links placed in courses and the data students saved there are bound to it, and it can never be changed. |
| **Label** | What the instructor sees in the picker, and the default name of the link they place. |
| **Description** | Optional. Shown in the picker. |
| **Type** | What the location is for — see below. |
| **Points** | For an `assessment`: what the gradebook column is worth when an instructor places it. 100 if you don't say. Your tool should send the same number as `maxScore` when it [reports a grade](https://myeducator-llc.github.io/voshi-docs/api/grades). |
| **Voshi ID** | Voshi's own identifier for the location, assigned when it is created. Starts with `I`. Useful for matching the dashboard's logs; your code uses the extid. |

### Types

| Type | Meaning |
| --- | --- |
| `assessment` | Graded work. **The only type that can report a grade.** Placing it creates a gradebook column. |
| `practice` | Student practice; no grade attached. |
| `content` | Reading or reference material. |
| `setup` | A configuration screen for the instructor, not a student-facing activity. |

## How many locations

The rule: **one location for each thing you want graded, and one for each non-graded thing you want a student to be able to open.** A location's grades land in one gradebook column, so two graded activities need two locations.

Don't plan on an instructor placing the same location twice to get two of anything. Both links point at the same activity, share the same storage, and feed the same gradebook column. Duplicate links happen anyway (course copies, module edits), and your tool needs no special handling for them: every launch of the location carries the same extid.

## Declaring your locations

A hosted tool has no server for Voshi to ask, so its locations are recorded in the dashboard, and there are two ways to put them there.

### In the Locations tab

**Add Location** creates one: name, external ID, type, and points. **Edit** changes the label and type. The AI Builder creates `home` for you when it first builds the tool, and adds locations when the conversation calls for several activities.

### In manifest.json

The tool's own code can declare them, in the `locations` key of [`manifest.json`](https://myeducator-llc.github.io/voshi-docs/building/files#manifestjson). The shape is the same one a self-hosted tool serves, so one definition of a location serves both:

```json
{
  "manifest_version": 2,
  "locations": {
    "ch3_practice": {
      "type": "practice",
      "label": "Chapter 3 Practice",
      "description": "Try the problems before the quiz."
    },
    "ch3_quiz": {
      "type": "assessment",
      "label": "Chapter 3 Quiz",
      "description": "20 questions on normal distributions.",
      "points": 50
    }
  }
}
```

Uploading a manifest **syncs** the Locations tab to it: a new extid is created, an existing one is updated, and an extid that has left the manifest is retired (below). Locations can also be arranged into named, collapsible groups with `grouped_locations`, up to five levels deep, exactly as in the [self-hosted response](https://myeducator-llc.github.io/voshi-docs/advanced/locations-endpoint#grouped_locations--arranging-a-large-catalog). Grouping is presentation only; it never appears in a launch.

Download Code always includes a `manifest.json` with the tool's current locations in it, so once you have downloaded once, the manifest is the natural place to keep them.

<Note>
An upload **without** a manifest changes nothing about your locations. Only a manifest that is present and has a `locations` key is treated as the list.
</Note>

## Handling locations in your code

Every launch says which location it is for: `api.location.extid`. A tool with several activities switches on it:

```javascript
connectedCallback() {
    switch (this.api.location.extid) {
        case 'ch3_practice': this.renderPractice(); break
        case 'ch3_quiz':     this.renderQuiz();     break
        default:             this.renderUnknown()   // a retired location, or one the code doesn't know yet
    }
}
```

The launch also carries the location's `id`, `type`, and `label`, as Voshi recorded them when the link was placed. Nothing else: there is no per-location configuration object. If an instructor needs to configure an activity, keep that in `api.storage.location`, which is theirs to write and everyone's to read.

## Retiring a location

**Stop offering** on the Locations tab, or removing an extid from `manifest.json`, retires the location: instructors are no longer offered it. **Links already placed keep working**, with their data and grades, and your code must go on handling the extid — courses are copied forward term after term, and a link can outlive your catalog by years. Offer it again at any time and it comes back with its original Voshi ID. A location is never deleted, and `home` is always offered.

<Warning>
**Never rename an extid.** A renamed extid is a new, empty location, and the old one is retired with every link and every student's data still bound to it. Pick extids you can live with: `ch3_quiz`, not `fall2026_cs101_quiz3`. Course, term, and person already arrive separately in every launch.
</Warning>

## In the picker

When an instructor adds your tool to a course, Voshi shows them your offered locations — labels and descriptions, groups collapsed — and they choose one or several. Placing an `assessment` creates the gradebook column, worth its points. Voshi copies the location's label and type into the link at that moment; a later edit to the label applies to new placements, while existing links keep what they were placed with.

---

# Testing in the Sandbox

> A private course where your draft runs for real, as a student or as an instructor.

Source: https://myeducator-llc.github.io/voshi-docs/building/sandbox

Every tool has a **Sandbox**: a private course that only you can see, with your tool already in it. Launches there are the genuine article — Voshi plays the part of the LMS, and everything downstream is real: the picker, provisioning, storage, roles, and a gradebook that takes your scores. If your tool works here, it works in a school's LMS.

The Sandbox always runs your **draft**, the code you last built or uploaded. See [Versions](https://myeducator-llc.github.io/voshi-docs/building/versions).

## Two ways in

- **The Running Tool panel** on the AI Builder page is a Sandbox launch of one location, as one role, with a Refresh button. It is the fast loop: build, look, change, build.
- **The Sandbox tab** is the whole course: its links, its launches, its gradebook. It is where you test the way an instructor and a student will actually use the tool.

## Links

A link is a placement of your tool in the Sandbox course, like a placement in a real course.

<Steps>
  <Step title="Place a link">
    **New Link** opens your tool's content picker — the same one an instructor sees, listing your offered [locations](https://myeducator-llc.github.io/voshi-docs/building/locations). Pick one and confirm. For an `assessment`, this is also where the gradebook column is created, worth the location's points.
  </Step>
  <Step title="Launch it">
    Launch a link as a **student** or as an **instructor**. Each role is a separate person in the course with its own saved work, and they share the course, so an instructor launch sees what the student launch saved — the right way to test an instructor setup screen or a review view.
  </Step>
  <Step title="Reset when you want a clean run">
    **Reset** throws away everything stored at that link — the location's data, every persona's work, and their grades — so the next launch is a first launch again. This is the only place in Voshi where saved data is deliberately discarded. **Remove** deletes the link; the location itself is kept and can be placed again.
  </Step>
</Steps>

The **Provisioned** column shows whether the link's course setup has run. A hosted tool's provisioning is automatic, so it reads **Yes** as soon as the link is placed or first launched.

## Launches and Grades

The Sandbox's **Launches** tab lists each launch in the course. Its **Grades** tab is the course gradebook: every score your tool reported, by link and by persona, with the result. A score refused by the gradebook shows the reason, so a wrong `maxScore` or a call made when `canSubmitGrade` was false is visible here, not just in the browser console.

## What to check before publishing

- **Every location launches** and shows the right activity for its `extid`.
- **A student can save and come back.** Launch as a student, do some work, launch again: it should still be there.
- **Roles are respected.** An instructor sees the setup or review features; a student does not. A student launch never calls `submitGrade` for an instructor, and an instructor previewing the activity does not score themself.
- **Grades land.** Finish the activity as a student and find the score in the Grades tab.
- **The frame fits.** The tool should not scroll inside itself unless you mean it to; give the element `:host { display: block }` and Voshi sizes the frame.

<Note>
A Sandbox launch signs your browser in as the test student or instructor, not as yourself. Expect to sign back into the dashboard afterwards if you opened a launch in its own window.
</Note>

---

# Versions

> The draft you work on, the versions you publish, and how courses adopt them.

Source: https://myeducator-llc.github.io/voshi-docs/building/versions

A hosted tool has one **draft** and any number of **published versions**.

- **The draft** is the code you are working on. Every build in the AI Builder and every Upload Code replaces it, and the previous draft is gone — there is no history of drafts. The [Sandbox](https://myeducator-llc.github.io/voshi-docs/building/sandbox) runs the draft. No course ever does.
- **A published version** is a permanent, numbered copy of the draft: 1, 2, 3, and so on. A single number, not `major.minor.patch`. Publishing records the draft as the next number; the draft itself is unchanged and you keep working on it. A version can never be edited or deleted — a fix is the next number.
- **The current version** is the one you published most recently. It is what a course gets when it adopts your tool.

Publishing is refused when the draft has not changed since the last version, so a version is always a real change.

## How courses adopt a version

When an instructor adds your tool to a course, the course **pins** to the current version, and keeps it. From then on every launch in that course runs that version — through the whole term, and in every term the course is copied into.

**Publishing a new version does not change any course.** Courses are never upgraded automatically, not when you publish and not when a course rolls forward into a new semester. The instructor signed up for a specific set of features; swapping them out under a running course would be disruptive, and most universities value stability and consistency over new features. Upgrading is strictly opt-in: when a newer version exists, the instructor is offered the upgrade when they launch the tool, and the course moves to it only when they accept.

So at any moment several courses can be running several versions of your tool, and that is normal. Two consequences for your code:

- **Read what older versions wrote.** A course that upgrades keeps its stored `api.storage` rows, so new code must accept the shapes earlier code saved. Add fields with defaults; don't rename or repurpose them.
- **Keep handling old locations.** A retired [location](https://myeducator-llc.github.io/voshi-docs/building/locations#retiring-a-location) is still placed in courses on older versions.

## Pinning a course to the draft

Normally only the Sandbox runs the draft. If you have a real course of your own — a class you teach, say — you can ask for it to be pinned to the draft instead of a version, which turns it into a second testing course that runs your latest build. Ask the MyEducator team to set that up.

## In practice

1. Build and test in the Sandbox until the draft is right.
2. **Publish.** The draft becomes version *n*, and new courses adopt it from now on.
3. Keep building. The draft moves on; version *n* does not.
4. Fix a problem in a published version by publishing the fix as *n+1*. Instructors on *n* are offered it at their next launch.

---

# The Voshi API

> The one object your tool talks to: what it holds, how to call it, and how it reports problems.

Source: https://myeducator-llc.github.io/voshi-docs/api/overview

Your tool never builds a URL, sends a token, or calls `fetch()`. Everything it needs from Voshi is on one object, `api`, which Voshi constructs from the launch and passes to your element.

```javascript
class MyTool extends HTMLElement {
    constructor(api) {
        super()
        this.api = api
        this.attachShadow({ mode: 'open' })
    }

    async connectedCallback() {
        this.shadowRoot.replaceChildren(this.api.assets.template('index.html'))
        try {
            const saved = await this.api.storage.memberLocation.get()
            this.render(saved)
        } catch (err) {
            this.showError(err.message)
        }
    }
}

customElements.define('my-tool', MyTool)
```

## What is on it

| | What | Page |
| --- | --- | --- |
| `api.user`, `api.isStaff`, `api.isStudent`, `api.groups` | Who launched, and their role in the course | [Who launched](https://myeducator-llc.github.io/voshi-docs/api/launch) |
| `api.location`, `api.course`, `api.organization` | Which of your locations, in which course, at which school | [Who launched](https://myeducator-llc.github.io/voshi-docs/api/launch) |
| `api.canSubmitGrade` | Whether this launch has a gradebook column | [Grades](https://myeducator-llc.github.io/voshi-docs/api/grades) |
| `api.submitGrade(...)` | Report a score | [Grades](https://myeducator-llc.github.io/voshi-docs/api/grades) |
| `api.storage.course`, `.location`, `.member`, `.memberLocation` | Four JSON objects your tool owns, each with `get`, `set`, `update`, `patch` | [Storage](https://myeducator-llc.github.io/voshi-docs/api/storage) |
| `api.storage.<scope>.files` | Files kept beside each of those, with `list`, `info`, `get`, `put`, `remove` | [Files](https://myeducator-llc.github.io/voshi-docs/api/files) |
| `api.assets` | Your tool's own stylesheets, templates, and file URLs | [Assets](https://myeducator-llc.github.io/voshi-docs/api/assets) |
| `api.launch_data` | The whole launch, for anything the properties above don't cover | [Who launched](https://myeducator-llc.github.io/voshi-docs/api/launch#the-whole-launch) |

## Three habits

**Every call that reaches Voshi is `async`.** `await` it. Reading storage, saving, reporting a grade, listing files — all of them return promises.

**Every call throws on failure.** A method never returns an error object or a status code; if something went wrong, it throws, and `err.message` says what. So wrap calls in `try`/`catch` and tell the learner what happened. See [Errors](https://myeducator-llc.github.io/voshi-docs/api/errors) for the kinds of error and what each means.

**Check before you act.** `api.canSubmitGrade` before `submitGrade()`; `api.isStaff` before showing instructor features or writing the shared rows. The checks are properties, not calls, and they are correct for this launch.

## Versions of the client

The Voshi API is a file Voshi serves alongside your tool, and it has a major version — the `1` in `voshi-api.1.js`. Breaking changes move to a new number; within a number, updates arrive rarely and between semesters, and your tool receives them without doing anything. Everything in these pages is version 1.

---

# Who launched

> What the api object says about the person, the course, and the location this launch is for.

Source: https://myeducator-llc.github.io/voshi-docs/api/launch

When your element is constructed, `api` already knows who opened the tool, from where, and into which location. These are plain properties — no calls, no waiting.

## The person

<ResponseField name="api.user" type="object">
  The person who launched.
  <Expandable title="fields">
    <ResponseField name="id" type="string">
      Their Voshi user ID. Stable across every launch, every course, and every school: the same person is the same `id` next term and at another institution. Use it to recognize a returning user.
    </ResponseField>
    <ResponseField name="member" type="string">
      Their membership in **this course**. A person has one `id` and one `member` per course they are in. Enrollment-specific state keys on this.
    </ResponseField>
    <ResponseField name="groups" type="string[]">
      Their role groups in this course: `student`, `instructor`, `assistant`, `manager`, and occasionally `mentor` (an observer). Usually one.
    </ResponseField>
    <ResponseField name="given_name, family_name, full_name, email" type="string | null">
      Present **only for course staff**. On a student launch all four are `null` — students are anonymous to your tool, by design. Never rely on a name being there.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="api.groups" type="string[]">
  The same list as `api.user.groups`, always an array.
</ResponseField>

<ResponseField name="api.isStaff" type="boolean">
  `true` for an `instructor`, `assistant`, or `manager` launch. Staff can write all four [storage](https://myeducator-llc.github.io/voshi-docs/api/storage) scopes and should see your tool's setup and review features.
</ResponseField>

<ResponseField name="api.isStudent" type="boolean">
  `true` for a `student` launch that is not also staff. Students can write only their own two storage scopes.
</ResponseField>

<ResponseField name="api.hasGroup(group)" type="boolean">
  Whether the launched person holds `group`: `api.hasGroup('assistant')`.
</ResponseField>

```javascript
this.$('#setup-button').hidden = !this.api.isStaff
this.$('#submit-button').hidden = !(this.api.isStudent && this.api.canSubmitGrade)
```

## The place

<ResponseField name="api.location" type="object">
  Which of your [locations](https://myeducator-llc.github.io/voshi-docs/building/locations) this launch is for: `{ id, extid, type, label }`. Switch on **`extid`** — it is your own identifier, exactly as you declared it. `id` is Voshi's; `type` and `label` are what was recorded when the link was placed.
</ResponseField>

<ResponseField name="api.course" type="object">
  The course: `{ id, name, label }`. `name` is its title ("Intro to Computing"), `label` its short code ("CS101").
</ResponseField>

<ResponseField name="api.context" type="string">
  The course's ID, the same as `api.course.id`.
</ResponseField>

<ResponseField name="api.organization" type="object">
  The school's side: `{ title, issuer, client, deployment }`. `title` is the institution's name; the other three are Voshi IDs for the LMS installation your tool was launched from. Most tools only ever read `title`.
</ResponseField>

<ResponseField name="api.app" type="string">
  Your tool's ID — the one on the Settings tab.
</ResponseField>

<ResponseField name="api.launchId" type="string">
  This launch's ID, one per visit. It matches the Launches tab in the dashboard.
</ResponseField>

## Grading

<ResponseField name="api.canSubmitGrade" type="boolean">
  Whether this launch has a gradebook column to report to: an `assessment` location that was placed through the picker. When it is `false`, say nothing about grades at all. See [Grades](https://myeducator-llc.github.io/voshi-docs/api/grades).
</ResponseField>

## The whole launch

<ResponseField name="api.launch_data" type="object">
  Everything Voshi sent, as received. The properties above cover what a tool needs; this is the escape hatch. Its fields are documented in the [Launch Data reference](https://myeducator-llc.github.io/voshi-docs/advanced/launch/launch-claims) — the same payload a self-hosted tool receives as a signed token. Your tool never needs the `api`, `storage`, `files`, or `grade` entries in it; those are what the client already uses on your behalf.
</ResponseField>

## What a launch does not tell you

- **Nothing in advance.** Voshi does not announce a school, course, or student before they launch. The first launch is the first your tool hears of any of them.
- **No LMS internals.** Every ID is Voshi's own. There is no LMS user ID, course ID, or link ID in the launch.
- **No history.** A repeat launch looks like the first one. Recognize a returning learner by `api.user.member` and resume from what you saved in [storage](https://myeducator-llc.github.io/voshi-docs/api/storage).

---

# Storage

> Four JSON objects your tool owns for every launch: per course, per location, per student, and per student at a location.

Source: https://myeducator-llc.github.io/voshi-docs/api/storage

Your tool has four places to keep data, and most tools need no other persistence at all — no database, no accounts, no schema. Each is one JSON object that is entirely yours; Voshi never reads or interprets it.

```javascript
// Save a student's answer
await this.api.storage.memberLocation.update({ q3: 'B', lastSaved: Date.now() })

// Read it back on the next visit
const work = await this.api.storage.memberLocation.get()     // {} if nothing was ever saved
```

## The four scopes

| Scope | One object per… | Typical use |
| --- | --- | --- |
| `api.storage.course` | course | Course-wide settings the instructor made: term dates, which modules are open |
| `api.storage.location` | location × course | The instructor's setup of one activity: the word list, the due date, the question pool |
| `api.storage.member` | person × course | The student's state across your whole tool in this course: preferences, cumulative progress |
| `api.storage.memberLocation` | person × location × course | The student's work on one activity: answers, attempts, the saved draft |

The two **member** scopes are the student's own. The **course** and **location** scopes are shared by everyone in the course, which is why only staff can write them.

Every scope points at the right object for *this* launch: this course, this location, this person. Your tool never says which course or which student it means — the launch already did.

## Who can write what

| | `student` | `instructor` / `assistant` / `manager` |
| --- | --- | --- |
| `course`, `location` | read | read and write |
| `member`, `memberLocation` | read and write (their own) | read and write |

A student writing `course` or `location` throws a [`VoshiPermissionError`](https://myeducator-llc.github.io/voshi-docs/api/errors). So course-wide state that students need to change has to live in their own `member` object instead.

Course staff read and write the same `member` and `memberLocation` objects — their own, in a staff launch. Reading a *particular student's* work from an instructor launch is not something the client does today; design an instructor's review view around the shared scopes, or around what the student's own launch wrote into them.

## The methods

Each scope has the same four methods. All are `async` and throw on failure.

<ResponseField name="get()" type="Promise<object>">
  The stored object, or `{}` when nothing has been stored yet.
</ResponseField>

<ResponseField name="set(data)" type="Promise<void>">
  Replace the whole object with `data`.
</ResponseField>

<ResponseField name="update(changes)" type="Promise<void>">
  Merge `changes` into the object: each top-level key in `changes` is set, and other keys are left alone. A key whose value is `undefined` is removed. **Prefer this over get-then-set** for small changes — it is one request, and it does not overwrite a key another tab or the instructor changed in between.
</ResponseField>

<ResponseField name="patch(operations)" type="Promise<void>">
  Apply a [JSON Patch](https://jsonpatch.com/) (RFC 6902): an array of operations like `{ op: 'add', path: '/answers/-', value: 4 }`. For changes deeper than the top level, such as appending to a list or setting one key inside a nested object. Missing intermediate paths are created for you, and a `remove` or `replace` of a path that does not exist is tolerated.
</ResponseField>

```javascript
// An instructor saves the activity's setup
if (this.api.isStaff) {
    await this.api.storage.location.set({ words: ['asset', 'liability', 'equity'], shuffle: true })
}

// A student appends an attempt without touching anything else
await this.api.storage.memberLocation.patch([
    { op: 'add', path: '/attempts/-', value: { score: 0.8, at: Date.now() } },
])
```

## Size

The JSON object is limited to **512 KB** on the two member scopes and **1 MB** on the course and location scopes, measured as compact JSON. That is configuration and state, not a file store. Anything larger — an image, a recording, an essay as a PDF, a big dataset — belongs in [files](https://myeducator-llc.github.io/voshi-docs/api/files), which each scope keeps beside its object.

## Things worth knowing

- **Reads return exactly what you last wrote.** No envelope, no metadata.
- **Writes are atomic.** Two writes to the same object serialize; a `patch` or `update` never half-applies.
- **Copied courses keep their setup.** When a school copies a course into a new term, the new course's `course` and `location` objects start as copies of the old course's. The instructor's setup carries forward; students' `member` objects do not, because the students are new.
- **Nothing is ever torn down.** Objects persist for as long as the course does. There is no API to delete them; the Sandbox's **Reset** is the one place data is discarded.
- **Versions share storage.** A course that [upgrades](https://myeducator-llc.github.io/voshi-docs/building/versions) to a newer version of your tool keeps its objects, so new code must read what old code wrote.

---

# Files

> Files your tool keeps beside each storage object: uploads, recordings, images, anything too big or not JSON.

Source: https://myeducator-llc.github.io/voshi-docs/api/files

Each of the four [storage](https://myeducator-llc.github.io/voshi-docs/api/storage) scopes also keeps **files**: data too large for the JSON object, or not JSON at all — a student's essay as a PDF, a photo of their lab setup, an audio recording, a map the instructor uploaded for everyone. Who can read and write them follows the same rules as the scope's object.

```javascript
// A student uploads their submission
const input = this.shadowRoot.querySelector('input[type=file]')
await this.api.storage.memberLocation.files.put('essay.pdf', input.files[0])

// Later, show what they uploaded
const files = await this.api.storage.memberLocation.files.list()   // [{ key, size, modified }]

// Display an image the instructor stored for the course
const { url } = await this.api.storage.course.files.info('diagram.png')
img.src = url                                                        // valid for a few minutes
```

Each file has a **key** your tool chooses — 1 to 128 characters, letters, digits, `.`, `_`, and `-`, starting with a letter or digit, no `/`. A `put` to a key that already holds a file replaces it.

## The methods

All are on `api.storage.<scope>.files`, all are `async`, and all throw on failure.

<ResponseField name="list()" type="Promise<Array>">
  Every file on the scope: `[{ key, size, modified }]`, with `size` in bytes and `modified` in milliseconds since the epoch. Empty when there are none.
</ResponseField>

<ResponseField name="info(key)" type="Promise<object>">
  One file: `{ key, size, modified, content_type, url, expires }`. `url` downloads the file until `expires` (milliseconds since the epoch, a few minutes away). Put it in an `<img>`, an `<a>`, or an `<audio>` right away; ask again for a fresh one rather than keeping it. Throws `VoshiNotFoundError` when no file has the key.
</ResponseField>

<ResponseField name="get(key)" type="Promise<Blob>">
  The file's contents, as a Blob — for a file your code reads, such as JSON or text your tool saved earlier. For something the browser displays, `info().url` is cheaper.
</ResponseField>

<ResponseField name="put(key, file, options?)" type="Promise<void>">
  Store `file` (a `File` from an input, or any `Blob`) at `key`, replacing what was there.

  <Expandable title="options">
    <ResponseField name="filename" type="string">
      The name a download is saved as. The `File`'s own name by default, else the key.
    </ResponseField>
    <ResponseField name="contentType" type="string">
      The file's type. The Blob's type by default, else guessed from the name.
    </ResponseField>
    <ResponseField name="attachment" type="boolean" default="false">
      Make downloads save the file rather than open it in the browser.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="remove(key)" type="Promise<void>">
  Delete the file. Removing a key that holds nothing is not an error.
</ResponseField>

## Limits

| | Limit |
| --- | --- |
| One file | 25 MB |
| Files on one scope | 100 files, 100 MB together |

A `put` that would exceed the scope's quota throws before anything is uploaded.

## How it works, briefly

The bytes go straight between the browser and Voshi's file storage, not through the API, which is why `info()` hands you a short-lived URL instead of the file. Your tool does not need to know this — but it explains why a stored URL stops working after a few minutes, and why you should ask for a new one each time you render.

## Saving something that is not a file

A `Blob` can be made from anything:

```javascript
const blob = new Blob([JSON.stringify(bigDataset)], { type: 'application/json' })
await this.api.storage.memberLocation.files.put('dataset.json', blob)

const back = JSON.parse(await (await this.api.storage.memberLocation.files.get('dataset.json')).text())
```

Use this when a student's work outgrows the storage object's [size limit](https://myeducator-llc.github.io/voshi-docs/api/storage#size).

---

# Grades

> Report a score to the course gradebook with one call.

Source: https://myeducator-llc.github.io/voshi-docs/api/grades

When a student finishes graded work, your tool reports the score and Voshi puts it in the LMS gradebook. One call, no gradebook plumbing:

```javascript
async finish(correct, total) {
    if (!this.api.canSubmitGrade) return        // no gradebook column here: say nothing about grades

    this.setStatus('Reporting your score to your course…')
    try {
        await this.api.submitGrade({
            score: correct / total,              // a fraction from 0 to 1
            maxScore: total,                     // the points the activity is worth
            comment: `${correct} of ${total} correct`,
        })
        this.setStatus('Your score has been reported to your course.')
    } catch (err) {
        this.setStatus(`Your score could not be reported: ${err.message}`)
    }
}
```

## When you can report a grade

`api.canSubmitGrade` is `true` when this launch has a gradebook column: the launched [location](https://myeducator-llc.github.io/voshi-docs/building/locations) is an `assessment`, and the instructor placed it through the picker so the column was created. It is `false` for every other launch — a `content` or `practice` location, or an assessment placed as a plain link.

When it is `false`, run the activity and say nothing about grades. Calling `submitGrade()` anyway throws a `VoshiGradeUnavailableError` before anything is sent.

<Note>
Check `api.isStudent` as well before scoring. An instructor previewing the activity would otherwise report a score for themself.
</Note>

## submitGrade(options)

<ParamField body="score" type="number" required>
  The fraction earned, **from 0 to 1**. `0.85` is 85%. Not points.
</ParamField>

<ParamField body="maxScore" type="number">
  The points the activity is worth. The gradebook column is set to this many points before the score is published, so the LMS shows `score × maxScore` out of `maxScore` — a `0.7` with `maxScore: 10` shows as 7/10. **Send the same number every time** for a location, and make it the location's **points**. Without it, the fraction applies to whatever the column is already worth, which the instructor may have changed.
</ParamField>

<ParamField body="comment" type="string">
  Shown to the student beside the grade in the LMS. The one place your tool can explain the number.
</ParamField>

<ParamField body="activityProgress" type="string" default="Completed">
  `Completed` or `Submitted`: has the student finished the activity?
</ParamField>

<ParamField body="gradingProgress" type="string" default="FullyGraded">
  `FullyGraded` or `Pending`: is this score final? Send `Submitted` and `Pending` for a provisional score, then call again with the defaults when it is final.
</ParamField>

Returns the recorded attempt — `status` is `'success'`, and `score`, `max_score`, and `submitted` say what was published. Throws:

- `VoshiGradeUnavailableError` — `canSubmitGrade` was false.
- `VoshiGradeRejectedError` — Voshi recorded the attempt, but the LMS refused the score. `err.message` says why; `err.passback.data.error` has the LMS's own words.
- Any other [`VoshiApiError`](https://myeducator-llc.github.io/voshi-docs/api/errors) for a network or server problem.

## How to call it

- **Once per completed attempt**, at the moment the learner finishes — not on every answer, and never on load.
- **Awaited, inside `try`/`catch`**, with the outcome shown to the learner. Never say a score was reported before the call has resolved.
- **Again, if they try again.** Every call is a new attempt. Nothing is overwritten and there is no "update": a second call publishes a second score, which the LMS takes as the newer one. Regrading, correcting, and retrying a failure are all just calling again.

## Where it goes

A score lands in the gradebook column for **this student, at this location, in this course** — the launch already decided all three. One location is one column, which is why two graded activities need two locations.

The dashboard's **Grades** tab lists every attempt your tool has made, with the LMS's answer; in the Sandbox, the course's own Grades tab shows the same thing as a gradebook.

---

# Assets

> Your tool's own stylesheets, templates, and files, loaded for you and handed over as api.assets.

Source: https://myeducator-llc.github.io/voshi-docs/api/assets

Voshi loads your tool's stylesheets and templates before it constructs your element, and hands them over as `api.assets`. Your tool never fetches its own files.

```javascript
connectedCallback() {
    // styles.css is already applied to the shadow root; index.html is a template
    this.shadowRoot.replaceChildren(this.api.assets.template('index.html'))
    this.shadowRoot.querySelector('img.map').src = this.api.assets.url('map.png')
}
```

Which files count as stylesheets and templates is decided by [`manifest.json`](https://myeducator-llc.github.io/voshi-docs/building/files#manifestjson): `app.styles` and `app.templates`, or every `.css` and `.html` in the folder when those keys are absent.

<ResponseField name="api.assets.styles" type="CSSStyleSheet[]">
  The stylesheets, in manifest order. If your shadow root is **open** (`this.attachShadow({ mode: 'open' })`), they are already adopted into it when `connectedCallback` runs — do nothing. With a **closed** root, adopt them yourself: `root.adoptedStyleSheets = [...root.adoptedStyleSheets, ...this.api.assets.styles]`.
</ResponseField>

<ResponseField name="api.assets.template(name)" type="DocumentFragment">
  A fresh copy of a template's content, ready to put in the shadow root. Every call is a new copy, so a template can be stamped out many times — one per card, one per row.
</ResponseField>

<ResponseField name="api.assets.text(name)" type="string">
  A template's raw text, for a tool that does its own templating.
</ResponseField>

<ResponseField name="api.assets.url(name)" type="string">
  The URL of any of your tool's own files — an image, a font, a data file — for anything the browser must fetch. This is the only URL to one of your files your tool should ever use.
</ResponseField>

A name that is not one of the tool's files throws, naming the file.

## Why not fetch them yourself

Every upload and every published version of your tool is served from a different address, named by the content of the files. A URL you wrote into your code, or built from `import.meta.url` and cached, is the address of one particular upload. `api.assets.url()` is always the address of the files that are running. And `styles.css` and `index.html` have already been fetched once, by Voshi; fetching them again is a second round trip the learner waits on.

Importing another JavaScript module of your own with a relative `import './lib/cards.js'` is fine, and the normal way to split a tool into files — the browser resolves it against the running copy.

---

# Errors

> What the Voshi API throws, what each kind means, and what to tell the learner.

Source: https://myeducator-llc.github.io/voshi-docs/api/errors

Every method on `api` that reaches Voshi throws when something goes wrong. It never returns an error object, a `null`, or a status code — so a call that returns has succeeded, and `try`/`catch` is the whole of error handling.

```javascript
try {
    await this.api.storage.location.set(setup)
} catch (err) {
    if (err.name === 'VoshiPermissionError') {
        this.setStatus('Only the instructor can change the setup.')
    } else if (err.name === 'VoshiAuthenticationError') {
        this.setStatus('Your session has ended. Open the activity again from your course.')
    } else {
        console.error(err)
        this.setStatus('Something went wrong saving your work. Please try again.')
    }
}
```

<Note>
Every error's `name` is its class name, so `err.name === 'VoshiPermissionError'` is the test. The classes themselves live in the Voshi API module that Voshi loads, not in a file of yours, so there is nothing to import.
</Note>

## The kinds

All of them extend `VoshiApiError`, which carries `message`, `status` (the HTTP status, when there was a response), `method` and `url` (which request), and `details` (whatever the server said).

| Error | Status | Meaning | What to say |
| --- | --- | --- | --- |
| `VoshiNetworkError` | none | The request never got an answer: offline, or the request was aborted. | "Check your connection and try again." |
| `VoshiAuthenticationError` | 401 | The launch session has ended. Sessions last a long time, but not forever. | "Open the activity again from your course." |
| `VoshiPermissionError` | 403 | This role may not do that — a student writing `course` or `location`, say. | Hide the feature behind `api.isStaff` in the first place. |
| `VoshiNotFoundError` | 404 | No such file, location, or object. From `files.info()` or `files.get()` on a key that holds nothing. | Treat as "not there yet." |
| `VoshiValidationError` | 400 / 422 | The request was not acceptable: a non-object to `set()`, a bad file key, a `score` outside 0 to 1, a storage object over its size limit. Often thrown before anything is sent. | A bug in the tool; `err.message` says which argument. |
| `VoshiServerError` | 5xx | Voshi failed. | "Please try again in a moment." Retrying is reasonable. |
| `VoshiGradeUnavailableError` | none | `submitGrade()` with `canSubmitGrade` false. | Don't call it; check first. |
| `VoshiGradeRejectedError` | 200 | Voshi recorded the attempt, but the LMS refused the score. `err.passback.data.error` has the reason. | "Your score could not be reported," with `err.message`. The attempt is visible in the Grades tab. |

## Two rules

**Log the detail, show the learner a sentence.** `console.error(err)` keeps the status, URL, and server message for whoever is debugging. The learner gets plain language, and never a raw error string.

**Never claim success before the call resolves.** "Saving…" until the `await` returns, then "Saved" — or the catch block's message. This matters most for grades, where a learner who sees "reported" and closes the tab will not try again.

---

# Your own server

> When to self-host, what you build, and how to register a self-hosted tool.

Source: https://myeducator-llc.github.io/voshi-docs/advanced/overview

Most tools are hosted by Voshi: the builder writes browser code, and Voshi runs everything else. A **self-hosted** tool runs on **your own server** instead. Voshi still handles the LMS, the placement, the students, and the gradebook, but it hands each launch to your server over HTTPS, and your server does the rest.

This section is the contract for that: the endpoints you build, what arrives at them, how to verify it, and the REST APIs for storage and grades. If you are building a hosted tool, none of it applies to you — everything in it is done for you by the [Voshi API](https://myeducator-llc.github.io/voshi-docs/api/overview).

## When to self-host

Choose your own server when the tool needs something that cannot live in the browser:

- **A backend of your own** — an existing product, a database with its own schema, server-side logic.
- **Grading that must not be readable** off the tool's source, computed and published from your server.
- **A catalog of locations that changes dynamically** — locations generated per placement, or served from your own data.
- **Grading outside the launch** — a background job, an instructor's roster view, scoring work hours after the student left.

Everything else — identity, storage, files, grades during the launch — a hosted tool already has, with no server to run.

## Hosted or self-hosted

The choice is made at registration and **cannot be changed afterwards**. It decides whether your tool has endpoints of its own at all.

| | **Voshi Hosted** | **Self Hosted** |
| --- | --- | --- |
| Where your code runs | Voshi's CDN, in the learner's browser | Your own server |
| How you build it | AI Builder, or upload a folder | However you like |
| Locations | Declared in the dashboard or `manifest.json` | Served by your Locations URL on demand |
| Course setup | Automatic | Your Provision URL is called |
| Launches | Your element is constructed with the Voshi API | A signed `launch_data` JWT is posted to your Callback URL |
| Storage and grades | `api.storage`, `api.submitGrade()` | REST calls with the launch's token, or your API key |
| API key | None | One, shown once |

## The three endpoints you build

Voshi reaches your tool at three URLs. All three must be public HTTPS, and all three receive a form `POST` with a single signed `launch_data` field that you verify the same way.

| URL | Called when | Docs |
| --- | --- | --- |
| **Callback URL** | Someone opens your tool from a course. Arrives through their browser. | [Receiving launches](https://myeducator-llc.github.io/voshi-docs/advanced/launch/receiving-launches) |
| **Provision URL** | A course, or a location in it, needs setting up in your tool. Server to server. | [Receiving provision requests](https://myeducator-llc.github.io/voshi-docs/advanced/provisioning/receiving-provision-requests) |
| **Locations URL** | An instructor is placing your tool and Voshi needs your list of destinations. Server to server. | [Serving your locations](https://myeducator-llc.github.io/voshi-docs/advanced/locations-endpoint) |

Only the Callback URL is strictly required to receive a launch — but a tool without a Locations URL **can't be placed in a course**, and a tool without a Provision URL **can't finish course setup**, so a live tool needs all three.

```mermaid
sequenceDiagram
    autonumber
    participant LMS
    participant Voshi
    participant Browser as Student's browser
    participant Tool as Your server
    LMS->>Voshi: Instructor places content
    Voshi->>Tool: POST launch_data to your Locations URL
    Tool-->>Voshi: The destinations you offer
    Voshi->>Tool: POST launch_data to your Provision URL
    Tool-->>Voshi: 204, then PUT each level when it's ready
    LMS->>Voshi: Launch
    Voshi->>Browser: Hand off to your tool
    Browser->>Tool: POST launch_data (signed JWT) to your Callback URL
    Tool->>Tool: Verify JWT, start your own session
    Tool-->>Browser: Your tool's page
    Tool->>Voshi: POST the launch's grade URL (optional)
    Voshi->>LMS: Sync score to gradebook
```

## Register in the dashboard

<Steps>
  <Step title="Tools → New Tool">
    In the [dashboard](https://zen.voshi.com/app/ltiaas/s/), fill in the **Tool Name** and choose **Self Hosted** under Hosting. This cannot be changed later.
  </Step>
  <Step title="Save your API key">
    Registration shows your **API key exactly once** — copy it now and store it securely, like you would a password. Its one job is letting your server [publish grades](https://myeducator-llc.github.io/voshi-docs/advanced/grades/grade-passback#as-your-tools-server-with-your-api-key) with no launch session.
  </Step>
  <Step title="Register your three URLs">
    Open your tool's **Settings** tab and fill in **Callback URL**, **Provisioning URL**, and **Locations URL**. They're blank at registration on purpose — the server they point at usually doesn't exist yet when you register.
  </Step>
</Steps>

You can edit the name, all three URLs, the description, and the logo at any time on the **Settings** tab. Changes apply immediately — including to placements instructors have already made. See [Managing your tool](https://myeducator-llc.github.io/voshi-docs/advanced/managing-your-app).

### Endpoint URL rules

Each of the three URLs is validated when you set it and re-checked every time Voshi calls it:

- Must be an absolute **`https://`** URL (no `http://`, no relative paths).
- Must point at a **publicly-routable host** — URLs that resolve to private, loopback, or link-local addresses are rejected. Your local machine can't receive launches; use a tunnel with a public HTTPS hostname or a deployed environment during development.

## A minimal self-hosted tool

<Steps>
  <Step title="Build your launch receiver">
    When someone opens your tool, Voshi sends their browser to your Callback URL with a form `POST` containing a single field, `launch_data` — a signed JWT carrying everything about the launch. Verify it, start your own session, and render.

<Tabs groupId="lang">

    <TabItem value="python" label="Python (Flask)">

    ```python
    # pip install flask pyjwt cryptography
    from flask import Flask, request, session
    import jwt
    from jwt import PyJWKClient

    JWKS_URL = "https://api.link.voshi.com/lti13/v1/jwks"
    jwks = PyJWKClient(JWKS_URL)  # fetches and caches Voshi's public keys by kid

    app = Flask(__name__)
    app.secret_key = "replace-with-a-real-secret"

    @app.post("/launch_receiver")
    def launch():
        token = request.form["launch_data"]

        # Verify the signature and expiry — never trust the claims before this.
        signing_key = jwks.get_signing_key_from_jwt(token)
        data = jwt.decode(token, signing_key.key, algorithms=["RS256"])

        # Trade the one-time launch token for your own session.
        session["voshi_user_id"] = data["user"]["id"]
        session["voshi_member_id"] = data["user"]["member"]   # this person in this course
        session["groups"] = data["user"]["groups"]            # e.g. ["instructor"]
        session["course_id"] = data["context"]
        session["grade_url"] = data["grade"]["submit"]    # None if this placement can't be graded

        location = data["location"]
        if location["type"] == "assessment":
            return f"Quiz time! You launched: {location['label']}"
        return f"Welcome to {location['label']}"
    ```

    </TabItem>

    <TabItem value="javascript" label="Node (Express)">

    ```javascript
    // npm install express jose express-session
    import express from 'express'
    import session from 'express-session'
    import { createRemoteJWKSet, jwtVerify } from 'jose'

    const JWKS_URL = 'https://api.link.voshi.com/lti13/v1/jwks'
    const jwks = createRemoteJWKSet(new URL(JWKS_URL)) // caches keys by kid

    const app = express()
    app.use(express.urlencoded({ extended: false }))
    app.use(session({ secret: 'replace-with-a-real-secret', resave: false, saveUninitialized: false }))

    app.post('/launch_receiver', async (req, res) => {
      // Verify the signature and expiry — never trust the claims before this.
      const { payload: data } = await jwtVerify(req.body.launch_data, jwks, {
        algorithms: ['RS256'],
      })

      // Trade the one-time launch token for your own session.
      req.session.voshiUserId = data.user.id
      req.session.voshiMemberId = data.user.member   // this person in this course
      req.session.groups = data.user.groups          // e.g. ['instructor']
      req.session.courseId = data.context
      req.session.gradeUrl = data.grade.submit         // null if this placement can't be graded

      const location = data.location
      if (location.type === 'assessment') {
        res.send(`Quiz time! You launched: ${location.label}`)
      } else {
        res.send(`Welcome to ${location.label}`)
      }
    })

    app.listen(3000)
    ```

    </TabItem>

</Tabs>

    See [Verifying the launch JWT](https://myeducator-llc.github.io/voshi-docs/advanced/launch/verifying-the-jwt) for the full security checklist — every endpoint below verifies `launch_data` the same way.
  </Step>

  <Step title="Serve your locations">
    Instructors can only place destinations your tool tells Voshi about. When one is placing content, Voshi `POST`s a signed `launch_data` to your **Locations URL** and shows them what you return, keyed by an external ID of your own choosing:

<Tabs groupId="lang">

    <TabItem value="python" label="Python (Flask)">

    ```python
    @app.post("/voshi/locations")
    def voshi_locations():
        verify_launch_data(request.form["launch_data"])   # same verification as a launch

        return {"locations": {
            "ch3_quiz": {
                "type": "assessment",              # the only type that can be graded
                "label": "Chapter 3 Quiz",
                "description": "20 questions on normal distributions.",
                "points": 50,                      # gradebook column value
            },
            "syllabus": {"type": "content", "label": "Course Syllabus"},
        }}
    ```

    </TabItem>

    <TabItem value="javascript" label="Node (Express)">

    ```javascript
    app.post('/voshi/locations', async (req, res) => {
      await verifyLaunchData(req.body.launch_data)   // same verification as a launch

      res.json({ locations: {
        ch3_quiz: {
          type: 'assessment',            // the only type that can be graded
          label: 'Chapter 3 Quiz',
          description: '20 questions on normal distributions.',
          points: 50,                    // gradebook column value
        },
        syllabus: { type: 'content', label: 'Course Syllabus' },
      }})
    })
    ```

    </TabItem>

</Tabs>

    See [Serving your locations](https://myeducator-llc.github.io/voshi-docs/advanced/locations-endpoint).
  </Step>

  <Step title="Set courses up when Voshi asks">
    Before the first launch of a course reaches you, Voshi asks your tool to set that course up — and the same for each location placed in it. Answer `204` immediately, then call the URLs from the `provision` claim when you're done:

<Tabs groupId="lang">

    <TabItem value="python" label="Python (Flask)">

    ```python
    @app.post("/voshi/provision")
    def voshi_provision():
        data = verify_launch_data(request.form["launch_data"])
        queue_setup(data)          # do the work in the background
        return "", 204             # answer first

    def queue_setup(data):
        headers = {"Authorization": f"Bearer {data['api']['token']}"}
        # The course first — a location cannot be provisioned before its course.
        if "context" in data["provision"]:
            requests.put(data["provision"]["context"], headers=headers).raise_for_status()
        if "location" in data["provision"]:
            requests.put(data["provision"]["location"], headers=headers).raise_for_status()
    ```

    </TabItem>

    <TabItem value="javascript" label="Node (Express)">

    ```javascript
    app.post('/voshi/provision', async (req, res) => {
      const data = await verifyLaunchData(req.body.launch_data)
      res.status(204).end()        // answer first
      queueSetup(data)             // do the work in the background
    })

    async function queueSetup(data) {
      const headers = { Authorization: `Bearer ${data.api.token}` }
      // The course first — a location cannot be provisioned before its course.
      if (data.provision.context) {
        await fetch(data.provision.context, { method: 'PUT', headers })
      }
      if (data.provision.location) {
        await fetch(data.provision.location, { method: 'PUT', headers })
      }
    }
    ```

    </TabItem>

</Tabs>

    Until those calls land, launches for that course wait. See [How provisioning works](https://myeducator-llc.github.io/voshi-docs/advanced/provisioning/overview).
  </Step>

  <Step title="Send a grade back">
    Every launch carries a `grade.submit` URL — or `null`, when that placement has no gradebook column. `POST` the score there; your API key authorizes it with no launch session:

<Tabs groupId="lang">

    <TabItem value="python" label="Python">

    ```python
    import requests

    grade_url = session["grade_url"]
    if grade_url:                       # None when this placement can't be graded
        resp = requests.post(
            grade_url,
            headers={"Authorization": "Bearer ltiaas_mytoolid_mysecret"},
            json={
                "score": 0.85,          # a fraction from 0.0 to 1.0
                "comment": "Nice work!",
            },
        )
        resp.raise_for_status()
        attempt = resp.json()
        print(attempt["status"])        # "success" if it reached the gradebook
    ```

    </TabItem>

    <TabItem value="javascript" label="Node">

    ```javascript
    const gradeUrl = req.session.gradeUrl
    if (gradeUrl) {                     // null when this placement can't be graded
      const resp = await fetch(gradeUrl, {
        method: 'POST',
        headers: {
          Authorization: 'Bearer ltiaas_mytoolid_mysecret',
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          score: 0.85,          // a fraction from 0.0 to 1.0
          comment: 'Nice work!',
        }),
      })
      const attempt = await resp.json()
      console.log(attempt.status)       // "success" if it reached the gradebook
    }
    ```

    </TabItem>

</Tabs>

    A rejected score comes back `200` with `status: "failed"` and the reason in `data.error` — check it. See [Grade passback](https://myeducator-llc.github.io/voshi-docs/advanced/grades/grade-passback).
  </Step>
</Steps>

## Testing your tool

The dashboard's **Sandbox** tab launches your tool in a **trial course of its own**, before any LMS is involved and while your tool is still in draft status. These are real launches: Voshi plays the part of the LMS, your Locations URL is asked what you offer through the ordinary picker, your Provision URL is called and waited on, your Callback URL receives a properly signed `launch_data`, real storage rows are created, and the Sandbox has a gradebook of its own that your grade submissions land in.

- **New Link** opens your tool's content picker, served from your Locations URL, and what you pick becomes a test link.
- Launch any test link as a **student** or as an **instructor**. Each role is a separate person in the trial course with its own data.
- **Reset** on a test link throws away everything stored for that link, so the next launch provisions it from scratch — the way to re-test your Provision URL.
- The Sandbox's **Launches** and **Grades** tabs show what Voshi recorded.

<Note>
A trial launch signs you into the browser as the test student or instructor, not as yourself. Open launches in a new window, and expect to sign back into the dashboard afterwards.
</Note>

## Tool status

| Status | Meaning |
| --- | --- |
| `draft` | The initial status. The tool **cannot be placed in real courses or launched from an LMS** — it's invisible to instructors. You can still test it from the Sandbox. |
| `active` | Live: instructors can place it, launches are forwarded to your Callback URL. |
| `suspended` | Disabled by the platform team. Launches and API calls are rejected. |

Only the Voshi platform team can change your tool's status. The path to going live is:

1. Build your three endpoints and your grade flow against these docs.
2. Exercise them from the **Sandbox** tab.
3. **Contact the MyEducator team to activate your tool.**
4. Test from a real LMS course — place a location, launch as an instructor and as a student, and verify grades land in the gradebook.

## Your API key

Only a self-hosted tool has one. It has the form:

```
ltiaas_<tool-id>_<secret>
```

- It's shown **once**, at registration. Voshi stores only a hash of it and **cannot show or recover it** — the dashboard displays a hint (`ltiaas_…last4`) so you can tell which key is live.
- Keep it **server-side only**.
- Its one use is [publishing a grade from your own server](https://myeducator-llc.github.io/voshi-docs/advanced/grades/grade-passback#as-your-tools-server-with-your-api-key), long after the launch session is gone. It does not configure your tool, and it is not a general-purpose credential.
- It is **not** involved in launch verification — launches are verified against Voshi's [public keys](https://myeducator-llc.github.io/voshi-docs/advanced/launch/verifying-the-jwt). Nor is it what provisioning calls use; those authenticate with the request's own `api.token`.

### Rotating or replacing your API key

Rotate the key from the **Settings** tab in the dashboard. A new key is issued and shown once, exactly as at registration.

<Warning>
**The old key stops working immediately** — there is no overlap window. Every deployed instance of your tool still using it starts getting `401` the moment you rotate, so roll the new key out promptly, or accept a gap in server-side grading.
</Warning>

Rotation is also the only recovery for a lost key, and the right response to a leaked one.

## Where to next

<CardGroup cols={2}>
  <Card title="Launch Data reference" icon="list" href="/advanced/launch/launch-claims">
    Every field in the launch JWT, explained.
  </Card>
  <Card title="Storage API" icon="database" href="/advanced/app-data/overview">
    Persist state per course, placement, and student — no database required.
  </Card>
  <Card title="How provisioning works" icon="wrench" href="/advanced/provisioning/overview">
    Course setup, the two levels, and what students see until it's done.
  </Card>
  <Card title="Locations" icon="map-pin" href="/advanced/locations">
    The destinations instructors place, and how your tool declares them.
  </Card>
</CardGroup>

---

# How launches work

> The lifecycle of a launch, from a click in the LMS to a request at your tool.

Source: https://myeducator-llc.github.io/voshi-docs/advanced/launch/overview

A **launch** is what happens when someone opens your tool from inside an LMS course. Voshi sits between the LMS and your tool: it handles the LMS integration and hands the user to your tool with everything you need in a single signed token.

## The lifecycle

```mermaid
sequenceDiagram
    autonumber
    participant LMS
    participant Voshi
    participant Browser as User's browser
    participant Tool as Your tool
    LMS->>Voshi: Launch
    Voshi->>Browser: Hand off to your app
    Browser->>Tool: POST launch_data=<signed JWT> to your callback URL
    Tool->>Tool: Verify signature and expiry
    Tool-->>Browser: Your tool takes over
```

1. **Someone launches your tool.** An instructor or student clicks your tool's placement in a course. The LMS hands the launch to Voshi — your tool isn't involved yet.
2. **Voshi forwards the launch to you.** Voshi sends the user's browser to your tool's **callback URL** with a `POST` of a single field, `launch_data`: a signed JWT identifying the school, course, user, and which of your [locations](https://myeducator-llc.github.io/voshi-docs/advanced/locations) was launched.
3. **Your tool takes over.** You verify the JWT, create your own session, and render whatever the user should see. From here on, the user is simply navigating your tool.

Nothing precedes step 1 for *people*: Voshi doesn't announce a school, course, or student before they launch, so the launch is also where your tool first hears about them. See [what a launch tells you about](https://myeducator-llc.github.io/voshi-docs/advanced/launch/receiving-launches#what-a-launch-tells-you-about).

Courses are the exception. **The first time anyone — student, instructor, or admin — launches into a course, Voshi tells your tool to set that course up**, and holds the launch until your tool says it's ready. See [How provisioning works](https://myeducator-llc.github.io/voshi-docs/advanced/provisioning/overview). So any launch that does land on your callback URL names a course your tool has already prepared.

<Note>
The launch `POST` arrives **through the user's browser**, not from a Voshi server. That has two consequences: the JWT's signature is the only thing standing between you and a forged launch (so [verify it](https://myeducator-llc.github.io/voshi-docs/advanced/launch/verifying-the-jwt), always), and Voshi never sees your tool's response — errors on your side are between your tool and the user.
</Note>

## What arrives in the launch

The JWT identifies the user (a stable ID, their course membership, and their role groups), the course, the school, your launched location, where to publish a score if this placement can take one, and URLs for your four [storage](https://myeducator-llc.github.io/voshi-docs/advanced/app-data/overview) storage rows. See the [Launch Data reference](https://myeducator-llc.github.io/voshi-docs/advanced/launch/launch-claims) for every field.

Three properties worth knowing up front:

- **All IDs are Voshi's own IDs** — stable across launches, but never the LMS's internal IDs.
- **No PII on student launches.** Name and email arrive only when the launching user is course staff (`manager`, `instructor`, or `assistant`); on every other launch they are `null`. Recognize a returning user by `user.id`.
- **One token, one session.** Tokens expire after 2 hours, but you shouldn't rely on that — trade the token for your own session on first use and don't accept the same token twice.

## How placements happen (deep linking)

Instructors place your tool into their course through a content picker that **Voshi presents**. Your tool's only part in it is one server-to-server request: Voshi asks your **Locations URL** what you currently offer, and shows the instructor that list. They pick a destination, optionally rename the placement, and Voshi handles the rest (for `assessment` locations, a gradebook column is created as part of the placement).

Because the list is fetched at placement time, what instructors can place is always current. What arrives in a *launch*, though, is the copy Voshi captured when that placement was made — so drive your tool off `location.extid` and your own data rather than treating the launch claim as live configuration. See [Concepts](https://myeducator-llc.github.io/voshi-docs/concepts), [Locations](https://myeducator-llc.github.io/voshi-docs/advanced/locations), and [Serving your locations](https://myeducator-llc.github.io/voshi-docs/advanced/locations-endpoint).

## Next

<CardGroup cols={2}>
  <Card title="Receiving launches" icon="right-to-bracket" href="/advanced/launch/receiving-launches">
    Build the callback endpoint.
  </Card>
  <Card title="Verifying the JWT" icon="shield-check" href="/advanced/launch/verifying-the-jwt">
    The security checklist and code samples.
  </Card>
</CardGroup>

---

# Receiving launches

> The endpoint that receives launches, what Voshi sends to it, and what your tool should record.

Source: https://myeducator-llc.github.io/voshi-docs/advanced/launch/receiving-launches

The **launch receiver** is the HTTPS endpoint that receives people — the **Callback URL** you provide when [registering your tool](https://myeducator-llc.github.io/voshi-docs/advanced/overview). When a student (or instructor) opens your tool from the LMS, Voshi sends the user's browser to your endpoint with an HTTP `POST` describing the launch.

It's one of [three endpoints](https://myeducator-llc.github.io/voshi-docs/advanced/overview) you build. The other two — your Provision URL and your Locations URL — are called by Voshi's server, never by a person's browser, and neither of their requests arrives here.

## The request Voshi sends you

Your callback URL receives a form `POST` with a **single field**: a signed JWT carrying the data from this launch.

```http
POST /launch_receiver HTTP/1.1
Host: myapp.example.com
Content-Type: application/x-www-form-urlencoded

launch_data=eyJhbGciOiJSUzI1NiIsImtpZCI6...
```

**Verify its signature and decode it** to read the launch — see [Verifying the launch JWT](https://myeducator-llc.github.io/voshi-docs/advanced/launch/verifying-the-jwt).

<Warning>
Because the JWT arrives through the browser rather than from a Voshi server, its signature is the **only** thing standing between you and a forged launch. **Never trust the claims until you've verified the signature.**
</Warning>

## Requirements for your endpoint

- **Public HTTPS.** The callback URL must be an absolute `https://` URL on a publicly-routable host. Voshi validates this when you register and again at every launch — URLs pointing at private or loopback addresses are rejected.
- **Accept a form POST.** `Content-Type: application/x-www-form-urlencoded`, one field named `launch_data`.
- **Be fast.** The user is sitting in front of a blank-ish redirect page while your endpoint responds. Do the minimum — verify, set a session cookie, render or redirect.

## What happens after the POST

From this point, the user is simply navigating your tool, so show **whatever they should see**: render your page directly, or redirect them onward based on the [location](https://myeducator-llc.github.io/voshi-docs/advanced/locations) that was launched.

A typical receiver:

1. Verify the JWT (signature + expiry).
2. Create **your own session** for the user — the launch token is a one-time entry ticket, not a session credential. Don't accept the same token twice.
3. Store what you'll need later: `user.id`, `user.member`, the `storage` row URLs, `grade.submit` (the URL you'll [send a score](https://myeducator-llc.github.io/voshi-docs/advanced/grades/grade-passback) to, or `null`), and the `api` token if you plan to use the [Storage API](https://myeducator-llc.github.io/voshi-docs/advanced/app-data/overview).
4. **Record the school, course, person, and membership** if you haven't seen them before — see [What a launch tells you about](#what-a-launch-tells-you-about).
5. Switch on `location.extid` to decide which screen to render.

```python
@app.post("/launch_receiver")
def launch():
    data = verify_launch_jwt(request.form["launch_data"])   # see Verifying the JWT

    session["voshi_user_id"] = data["user"]["id"]
    session["voshi_member_id"] = data["user"]["member"]
    session["groups"] = data["user"]["groups"]
    session["grade_url"] = data["grade"]["submit"]   # None when this placement can't be graded
    session["storage"] = data["storage"]
    session["api"] = data["api"]

    record_launch(data)   # see What a launch tells you about

    return route_to_screen(data["location"])
```

<Note>
**Course setup requests don't arrive here.** When a course or a location needs setting up in your tool, Voshi's server calls your **Provision URL** instead, with a different set of claims. A request to your Callback URL is always a person opening your tool. See [How provisioning works](https://myeducator-llc.github.io/voshi-docs/advanced/provisioning/overview).
</Note>

## What a launch tells you about

Voshi never tells your tool about a school, course, or person ahead of time. There is no roster sync, no admin onboarding step, and no API that hands you a list of users to create. **A launch is the first and only notice you get that any of them exist** — and it arrives with the student already waiting.

So treat your receiver as a *record-and-refresh* step, not a lookup. Any of these can be new on any launch, in any combination:

| What may be new | Recognize it by | When it happens |
| --- | --- | --- |
| A school | an unseen `organization.deployment` | Someone at a new institution launches your tool for the first time. |
| A course | an unseen `context` | The first launch of any placement in that course. |
| A person | an unseen `user.id` | Someone who has never opened your tool at this school. |
| A membership | an unseen `user.member` | A person you already know, launching from a course you haven't seen them in. |
| A placement | an unseen `resource_link` | An instructor placed a [location](https://myeducator-llc.github.io/voshi-docs/concepts#location) you already support. |

<Note>
`user.id` is stable **per school**. The same human at two institutions arrives as two different `user.id`s, and nothing in the launch lets you connect them — there's no email or name to match on. Treat people as belonging to their `organization`.
</Note>

This is your tool's own bookkeeping, and it is not the same thing as [provisioning](https://myeducator-llc.github.io/voshi-docs/advanced/provisioning/overview) — that's a separate, explicit protocol for setting a *course* up, driven by Voshi calling your Provision URL. This bookkeeping runs on every launch; provisioning happens once per course and once per location.

<Warning>
**Whatever store you use, write these as upserts, not check-then-insert.** A student who double-clicks the course link, or opens your tool in two tabs, produces two simultaneous first launches — a read followed by a write races itself, and the loser surfaces to the student as a broken launch.
</Warning>

### Re-sync the fields that change

Recording on first launch isn't enough — some claims change after you've seen them, and the launch is your only chance to notice:

- **`course.name` and `course.label`** change when the institution renames or re-terms the course.
- **`location.label` and `location.type`** change when your [locations endpoint](https://myeducator-llc.github.io/voshi-docs/advanced/locations-endpoint) serves different values *and* someone places that destination again — Voshi captures the copy at placement time. Neither the old nor the new value is authoritative for you: treat these as display text and read real configuration from your own data, keyed on `location.extid`.
- **`user.groups`** changes when someone's role in the course changes — a student promoted to TA, for example.

A `find_or_create` that skips the update goes quietly stale. Write these on every launch.

### Groups belong to the membership

`user.groups` describes this person **in this course, on this launch** — not the person. The same `user.id` is legitimately a `student` in one course and an `instructor` in another, and either can change between launches. Store the groups against `user.member`, never against `user.id`, and refresh them every time. Deciding what to show from a role you cached at signup is the most common way tools end up showing instructor tools to a student.

Check membership rather than equality — `"instructor" in groups`, not `groups[0] == "instructor"` — since a person can hold several groups. See the [`groups` reference](https://myeducator-llc.github.io/voshi-docs/advanced/launch/launch-claims#claims) for the full list.

### Key your own data on `extid`

Your records for a location belong to `location.extid`, not to `resource_link` and not to `location.id`. An extid is the same "thing" in every course and every term, while `resource_link` identifies one instructor's one link — and a course can end up with more than one link to the same location without your tool being told. See [Placement](https://myeducator-llc.github.io/voshi-docs/concepts#placement).

### Nothing is ever torn down

Launches are the only event your tool receives about people. You will **never** be told that a student dropped the course, that an instructor deleted a link, or that a term ended — those things simply stop producing launches. Don't design anything that waits for a teardown signal.

If staleness matters to you — seat counts, active-course reporting, data retention — derive it from activity instead: stamp a `last_seen_at` on every launch and age records out on your own schedule.

### Keep the launch fast

Bookkeeping is the usual reason a receiver gets slow, and the user is watching a blank page while it runs. Keep it to the cheap writes above. Push welcome emails, analytics events, content generation, and calls to external services into a background job, and render as soon as the records the first screen needs exist. Course-level setup work belongs in your [provisioning](https://myeducator-llc.github.io/voshi-docs/advanced/provisioning/overview) handler, which runs before students arrive and isn't on anyone's critical path.

<Note>
**Using [Storage storage](https://myeducator-llc.github.io/voshi-docs/advanced/app-data/overview)?** Then most of this is already done for you: the `member` and `member_location` rows are open from the first launch, so there's nothing to create and no schema to keep in sync. The `context` and `location` rows additionally require that the course be [provisioned](https://myeducator-llc.github.io/voshi-docs/advanced/provisioning/overview).
</Note>

## Launches you might not expect

Plan for a few launch shapes beyond the happy path:

- **Instructor launches.** Instructors launch the same locations students do — check `user.groups` before showing student-only or instructor-only UI.
- **Repeat launches.** The same user launching the same placement again is normal (they clicked the course link again). Recognize them by `user.member` and resume where they left off — upserting on every launch keeps this on the same code path as their first one.
- **A location you stopped serving.** Links outlive your catalog. Dropping an `extid` from your locations list only hides it from the instructor's picker — every link already placed keeps launching, forever. **Keep serving your locations.** Retiring one breaks courses that are still using it, and you get no warning that it happened. If you truly must, keep handling the launch and render your own "no longer available" screen rather than erroring — see [Extid](https://myeducator-llc.github.io/voshi-docs/concepts#extid).
- **`grade.submit: null` on a graded location.** A location of type `assessment` can still launch with nowhere to post a score, if the LMS didn't create a gradebook column for the placement. Degrade gracefully — see [Grade passback](https://myeducator-llc.github.io/voshi-docs/advanced/grades/grade-passback#when-you-can-send-a-grade).

## Errors on Voshi's side

If a launch can't be forwarded — for example, the tool is still in draft status, or the callback URL fails validation — Voshi shows the user an error page with a report ID. Your endpoint is never called, so you don't need to handle these; they show up as instructor reports instead.

Two other failures also happen entirely outside your receiver:

- **The course isn't provisioned yet.** Voshi holds the launch and shows a "not set up yet" or "Provisioning" page instead of calling you. See [How provisioning works](https://myeducator-llc.github.io/voshi-docs/advanced/provisioning/overview).
- **Your locations endpoint failed** while an instructor was placing content. They see a deep-link error and place nothing. See [When this endpoint fails](https://myeducator-llc.github.io/voshi-docs/advanced/locations-endpoint#when-this-endpoint-fails).

---

# Verifying the launch JWT

> Fetch Voshi's public keys, verify the RS256 signature, and enforce expiry.

Source: https://myeducator-llc.github.io/voshi-docs/advanced/launch/verifying-the-jwt

The launch payload is a single `launch_data` field: a **signed JWT (JWS)** that carries the whole launch. It is signed with Voshi's system key, so you verify it against Voshi's **public keys**, published at the JWKS endpoint:

```
https://api.link.voshi.com/lti13/v1/jwks
```

(Also available at `https://api.link.voshi.com/.well-known/jwks`.)

Your API key is **not** involved in launch verification — its only use is [publishing a grade from your own server](https://myeducator-llc.github.io/voshi-docs/advanced/grades/grade-passback#as-your-tools-server-with-your-api-key).

## What to check

| Check | Details |
| --- | --- |
| **Algorithm** | `RS256` (RSA, 2048-bit). Pass an explicit algorithm allowlist to your JWT library. |
| **Signature** | Verify against the JWKS key whose `kid` matches the token's `kid` header (always present). |
| **Expiry** | `exp` and `iat` are in **seconds**. Treat an expired token as an invalid launch. Tokens are valid for 2 hours after `iat`. |
| **Replay** | The lifetime is bounded but not tight, so don't accept the same token twice — trade it for your own session on first use. |

<Warning>
Keys **rotate** (roughly monthly), and during rotation the JWKS contains more than one key. **Fetch the JWKS dynamically and cache by `kid`** — don't pin a single key. The JWKS clients below do this for you.
</Warning>

## Code

<Tabs groupId="lang">

<TabItem value="python" label="Python (PyJWT)">

```python
# pip install pyjwt cryptography
import jwt
from jwt import PyJWKClient

JWKS_URL = "https://api.link.voshi.com/lti13/v1/jwks"
jwks = PyJWKClient(JWKS_URL)   # create once — it fetches and caches keys by kid

def read_launch_data(token: str) -> dict:
    signing_key = jwks.get_signing_key_from_jwt(token)
    # decode() verifies the signature and raises on an expired `exp`.
    return jwt.decode(token, signing_key.key, algorithms=["RS256"])
```

</TabItem>

<TabItem value="javascript" label="Node (jose)">

```javascript
// npm install jose
import { createRemoteJWKSet, jwtVerify } from 'jose'

const JWKS_URL = 'https://api.link.voshi.com/lti13/v1/jwks'
const jwks = createRemoteJWKSet(new URL(JWKS_URL)) // create once — caches keys by kid

async function readLaunchData(token) {
  // jwtVerify checks the signature and throws on an expired `exp`.
  const { payload } = await jwtVerify(token, jwks, { algorithms: ['RS256'] })
  return payload
}
```

</TabItem>

</Tabs>

Both clients handle key rotation transparently: when a token arrives with a `kid` they haven't cached, they re-fetch the JWKS.

## Common pitfalls

- **Decoding without verifying.** Most JWT libraries have a "decode only" mode (`jwt.decode(..., options={"verify_signature": False})`, `jwt.decode` vs `jwtVerify`). Never use it on `launch_data` — an attacker can mint arbitrary claims in an unverified token.
- **Skipping the algorithm allowlist.** Always pass `algorithms=["RS256"]` explicitly so a manipulated header can't downgrade verification.
- **Pinning one key.** A hardcoded public key works until the next rotation, then every launch fails. Use a JWKS client.
- **Treating the token as a session.** The token is valid for 2 hours and could be replayed within that window by anyone who obtains it. Exchange it for your own session cookie immediately, and reject reuse.

Once the token verifies, every claim inside it is trustworthy. On to the [Launch Data reference](https://myeducator-llc.github.io/voshi-docs/advanced/launch/launch-claims).

---

# Launch Data reference

> Every field inside the launch_data JWT — the Launch Data your tool receives.

Source: https://myeducator-llc.github.io/voshi-docs/advanced/launch/launch-claims

After [verification](https://myeducator-llc.github.io/voshi-docs/advanced/launch/verifying-the-jwt), the `launch_data` JWT decodes to a flat set of claims:

```json
{
  "iat": 1751470000,
  "exp": 1751477200,
  "iss": "https://api.link.voshi.com",
  "api": {
    "domain": "api.link.voshi.com",
    "token": "8f14e45fceea167a5a36dedd4bea2543"
  },
  "launch_id": "I9gbX9ExUrt6",
  "time": "2026-07-27T18:03:00+00:00",
  "app": "I4ppXy",
  "user": {
    "id": "In4kDp7yZq",
    "member": "Im8mBr42",
    "groups": ["student"],
    "given_name": null,
    "family_name": null,
    "full_name": null,
    "email": null
  },
  "course": {
    "id": "IcT91mBxze",
    "name": "Intro to Computing",
    "label": "CS101"
  },
  "context": "IcT91mBxze",
  "organization": {
    "title": "Example University",
    "issuer": "I1ssU3r",
    "client": "Icl13nt",
    "deployment": "Id3pL0yMnt"
  },
  "resource_link": "Ir3sLnk42",
  "location": {
    "id": "Il0c8n",
    "extid": "quiz1",
    "type": "assessment",
    "label": "Quiz 1"
  },
  "grade": {
    "submit": "https://api.link.voshi.com/lti13/v1/contexts/IcT91mBxze/members/Im8mBr42/apps/I4ppXy/locations/ext:quiz1/grade"
  },
  "storage": {
    "context": "https://api.link.voshi.com/lti13/v1/contexts/IcT91mBxze/apps/I4ppXy/data",
    "location": "https://api.link.voshi.com/lti13/v1/contexts/IcT91mBxze/apps/I4ppXy/locations/ext:quiz1/data",
    "member": "https://api.link.voshi.com/lti13/v1/contexts/IcT91mBxze/members/Im8mBr42/apps/I4ppXy/data",
    "member_location": "https://api.link.voshi.com/lti13/v1/contexts/IcT91mBxze/members/Im8mBr42/apps/I4ppXy/locations/ext:quiz1/data"
  },
  "files": {
    "context": "https://api.link.voshi.com/lti13/v1/contexts/IcT91mBxze/apps/I4ppXy/files",
    "location": "https://api.link.voshi.com/lti13/v1/contexts/IcT91mBxze/apps/I4ppXy/locations/ext:quiz1/files",
    "member": "https://api.link.voshi.com/lti13/v1/contexts/IcT91mBxze/members/Im8mBr42/apps/I4ppXy/files",
    "member_location": "https://api.link.voshi.com/lti13/v1/contexts/IcT91mBxze/members/Im8mBr42/apps/I4ppXy/locations/ext:quiz1/files"
  }
}
```

<Note>
**All IDs are Voshi's own IDs** — stable across launches, but never the LMS's internal IDs. The raw LMS user identifier is not available to your tool. **Student launches carry no PII**: name and email are `null` unless the launching user is course staff. Recognize a returning user by `user.id`, not by anything else.
</Note>

## Claims

<ResponseField name="iat" type="integer">
  Standard JWT "issued at" — Unix epoch **seconds** (UTC) when the token was signed. Use the `time` claim, not `iat`, if you want a human-readable launch timestamp.
</ResponseField>

<ResponseField name="exp" type="integer">
  Standard JWT expiry — Unix epoch seconds. Currently `iat` + 2 hours. Your JWT library checks this during verification and rejects an expired token.
</ResponseField>

<ResponseField name="iss" type="string">
  **Voshi** — always the fixed string `https://api.link.voshi.com` (the `https://` form of `api.domain`). It is not the school's LMS; that's `organization.issuer`. Since Voshi signs every `launch_data`, you can configure your JWT library to require this exact issuer alongside the signature check.
</ResponseField>

<ResponseField name="api" type="object">
  The credential for calling the [Storage API](https://myeducator-llc.github.io/voshi-docs/advanced/app-data/api-reference) **as the launching user**.
  <Expandable title="api fields">
    <ResponseField name="domain" type="string">
      The API host to call, e.g. `api.link.voshi.com`.
    </ResponseField>
    <ResponseField name="token" type="string">
      A bearer token tied to the launching user's session: send it as `Authorization: Bearer <token>`. It expires with the session (about a week), so treat it as per-launch — get a fresh one from the next launch rather than storing it long-term. Keep it server-side; it acts as that user.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="launch_id" type="string">
  The ID of this launch — one person's one entry into your tool. Useful for correlating with Voshi's dashboard and logs, and worth recording with whatever the user does next. Nothing in the API is keyed on it.
</ResponseField>

<ResponseField name="time" type="string">
  When the launch happened, as an ISO 8601 timestamp.
</ResponseField>

<ResponseField name="app" type="string">
  Your tool's ID.
</ResponseField>

<ResponseField name="user" type="object">
  Who launched, and what they are in this course.
  <Expandable title="user fields">
    <ResponseField name="id" type="string">
      The person's stable Voshi ID — the same across every launch by them, in any course at the same school.
    </ResponseField>
    <ResponseField name="member" type="string">
      Their **membership** ID: this person *in this course*. It's the natural key for an enrollment record, and it's the same ID that appears in the `members/…` segment of the `storage` URLs below. A person in two courses arrives with one `user.id` and two `user.member`s.
    </ResponseField>
    <ResponseField name="groups" type="array">
      What they are in this course, as a **list** of role groups:

      | Group | Who |
      | --- | --- |
      | `manager` | Course or account manager, and institution/system administrators. |
      | `instructor` | The instructor of record, faculty, lecturer. |
      | `assistant` | Teaching assistant, content developer, course staff. |
      | `mentor` | Mentor or observer — someone watching a student's progress rather than doing the work. |
      | `student` | Learner. |

      Check membership, not equality (`"instructor" in groups`) — a person can hold more than one group, and the list can grow. Roles the LMS sends that Voshi doesn't recognize arrive as `["student"]`, so `student` is also the least-privilege default and `groups` is never empty.

      It is recalculated **on every launch** from the roles the LMS sent, and it is per-course: the same `user.id` is legitimately a `student` in one course and an `instructor` in another, and either can change between launches. Store it on the membership, never on the person, and refresh it every time.
    </ResponseField>
    <ResponseField name="given_name" type="string | null">
      **Course staff only.** The launching user's first name, or `null`.
    </ResponseField>
    <ResponseField name="family_name" type="string | null">
      **Course staff only.** Their last name, or `null`.
    </ResponseField>
    <ResponseField name="full_name" type="string | null">
      **Course staff only.** Their display name, or `null`.
    </ResponseField>
    <ResponseField name="email" type="string | null">
      **Course staff only.** Their email address, or `null`.

      <Warning>
      These four fields are populated **only** when `groups` contains `manager`, `instructor`, or `assistant` — so you can address an instructor by name and email them about their course. For everyone else, including `student` and `mentor` launches, all four are `null`. Never build a flow that needs a name or an email from a student launch, and never use them to identify a returning user — that is `user.id`'s job.
      </Warning>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="course" type="object">
  The course the launch came from.
  <Expandable title="course fields">
    <ResponseField name="id" type="string">
      The course's stable Voshi ID.
    </ResponseField>
    <ResponseField name="name" type="string">
      The course title, e.g. `Intro to Computing`.
    </ResponseField>
    <ResponseField name="label" type="string">
      The course's short label, e.g. `CS101`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="context" type="string">
  The same course, as the bare ID — it matches the `contexts/…` segment of the `storage` URLs and is the ID used by [provisioning](https://myeducator-llc.github.io/voshi-docs/advanced/provisioning/overview). `course` carries the display text; `context` is the identifier.
</ResponseField>

<ResponseField name="organization" type="object">
  The school.
  <Expandable title="organization fields">
    <ResponseField name="title" type="string">
      The school's display name, e.g. `Example University`.
    </ResponseField>
    <ResponseField name="issuer" type="string">
      Voshi's ID for the LMS platform (e.g. one Canvas cloud). Most tools can ignore this.
    </ResponseField>
    <ResponseField name="client" type="string">
      Voshi's ID for the LMS registration under that platform. Most tools can ignore this.
    </ResponseField>
    <ResponseField name="deployment" type="string">
      Voshi's ID for the school's deployment — the most specific of the three, and the one to treat as "which school is this". Use it as your school key.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="resource_link" type="string">
  Voshi's ID for the specific link in the course, or `""` if the link was never created through the content picker. **Don't use this to identify your resource** — use `location.extid`, which names the same "thing" in every course and every term. See [Placement](https://myeducator-llc.github.io/voshi-docs/concepts#placement).
</ResponseField>

<ResponseField name="location" type="object">
  Which of your [locations](https://myeducator-llc.github.io/voshi-docs/advanced/locations) was launched.
  <Expandable title="location fields">
    <ResponseField name="id" type="string">
      Voshi's ID for the location, minted the first time it saw your `extid`.
    </ResponseField>
    <ResponseField name="extid" type="string">
      **Your own** external ID for this destination — the key you served from your [locations endpoint](https://myeducator-llc.github.io/voshi-docs/advanced/locations-endpoint). **This is the one to switch on**, and the one to key your own data on. See [Extid](https://myeducator-llc.github.io/voshi-docs/concepts#extid).
    </ResponseField>
    <ResponseField name="type" type="string">
      One of `assessment`, `practice`, `content`, or `setup`. Only `assessment` locations can pass grades back.
    </ResponseField>
    <ResponseField name="label" type="string">
      The label you gave the location, e.g. `Quiz 1`. Display text only — it's the copy Voshi captured when the placement was made.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="grade" type="object">
  Where to publish a score for this launch — see [Grade passback](https://myeducator-llc.github.io/voshi-docs/advanced/grades/grade-passback).
  <Expandable title="grade fields">
    <ResponseField name="submit" type="string | null">
      The URL to `POST` a score to, or **`null` when this launch has no gradebook column to post to**. A URL is offered only when the location is of type `assessment` **and** the LMS created a column for the placement — so an `assessment` location placed without the content picker launches fine but arrives with `submit: null`. Branch on it rather than on the location type, and don't offer grading when it's `null`.

      Like the `storage` URLs, it is ready to call and **opaque**: use it exactly as given. The one exception is the member segment, which you may swap to [grade another student in the same course](https://myeducator-llc.github.io/voshi-docs/advanced/grades/grade-passback#grading-a-student-who-is-not-the-one-launching).

      Which form of the URL you get follows the launching user's own role: a student's launch carries an `/account/v1/users/…` URL that only their own `api.token` can call, and every other launch carries a `/lti13/v1/contexts/…` URL that also accepts your tool's API key. See [authentication](https://myeducator-llc.github.io/voshi-docs/advanced/grades/grade-passback#authentication).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="storage" type="object">
  URLs of your four storage rows for this launch — read and write them through the [Storage API](https://myeducator-llc.github.io/voshi-docs/advanced/app-data/overview). Each value is the row's full URL: **call it exactly as given, and treat it as opaque.** Don't parse it, and don't build these URLs yourself — the path shape is not part of the contract and the segments are not always what you'd guess. (The location segment is normally `ext:<your extid>`, but it falls back to Voshi's internal location ID for a location that has no extid; the `members/…` segment is `user.member`.)
  <Expandable title="storage fields">
    <ResponseField name="context" type="string">
      Data row for this **course**. Closed until the course is [provisioned](https://myeducator-llc.github.io/voshi-docs/advanced/provisioning/overview#the-course-and-location-rows-open-at-provisioning).
    </ResponseField>
    <ResponseField name="location" type="string">
      Data row for this **location in this course**. Closed until the location is provisioned. Note the scope: it belongs to the extid, so it is shared by every link in the course that points at this location — see [Placement](https://myeducator-llc.github.io/voshi-docs/concepts#placement).
    </ResponseField>
    <ResponseField name="member" type="string">
      Data row for this **user within the course**. Open from the first launch.
    </ResponseField>
    <ResponseField name="member_location" type="string">
      Data row for this **user on this location** — e.g. their submission state. Open from the first launch.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="files" type="object">
  URLs of the **files** kept beside each of the four storage rows, with the same four keys as `storage` and the same opacity rule. `GET` a URL to list the row's files; `<url>/<key>` is one file. Who may read and write them follows the row. See [Files](https://myeducator-llc.github.io/voshi-docs/advanced/app-data/api-reference#files).
</ResponseField>

## What is deliberately absent

- **Name and email on a student launch** — the four `user` PII fields are `null` for anyone who isn't `manager`, `instructor`, or `assistant`.
- **The LMS's user ID** — not available to your tool.
- **LTI custom parameters** from the LMS placement — not forwarded. Look the destination up in your own data, keyed on `location.extid`, for per-placement configuration.
- **`location.params`** — locations carry no static key-value pairs. Earlier docs described a `params` object on the location claim; it is not sent, and never was on this contract. Key your configuration on `location.extid` instead.
- **`user.role`** — replaced by `user.groups`, which says the same thing with more precision. If your tool reads `role`, switch it to a `groups` membership check.
- **`grade_passback`** — replaced by the `grade` object. The boolean said *whether* you could grade; `grade.submit` says *where*, and is `null` in exactly the cases the boolean was `false`. If your tool reads `grade_passback`, switch it to a null check on `grade.submit` and post there.

---

# Locations

> How a self-hosted tool declares the destinations instructors can place, and the extid rules behind them.

Source: https://myeducator-llc.github.io/voshi-docs/advanced/locations

**Locations** are the "things" your tool provides that an instructor can place in a course — a chapter quiz, a practice set, a reading, a setup screen. Your tool **owns** them: you identify each one with an **external ID** (`extid`) of your choosing, and Voshi asks your tool for the current list whenever an instructor is placing content.

Nothing about your catalog is stored in Voshi ahead of time. Add a chapter and it's placeable immediately; the list you serve is the list instructors see.

<Note>
If you haven't read [Concepts](https://myeducator-llc.github.io/voshi-docs/concepts) yet, start there — it defines locations, extids, and placements, and explains why the extid you choose is the most consequential decision in your integration.
</Note>

## How instructors place your locations

<Steps>
  <Step title="The instructor adds your tool to a course">
    From inside their LMS. Voshi handles the LMS side of this.
  </Step>
  <Step title="Voshi asks your tool what it offers">
    A server-to-server `POST` to your **Locations URL**, which answers with your destinations keyed by extid. See [Serving your locations](https://myeducator-llc.github.io/voshi-docs/advanced/locations-endpoint).
  </Step>
  <Step title="The instructor picks one">
    They see your `label` and `description`, choose a destination, and confirm. For `assessment` locations, a gradebook column is created at the same time.
  </Step>
  <Step title="Voshi provisions the placement">
    Voshi calls your Provision URL for the course and the location so your tool can set them up before any student arrives — see [How provisioning works](https://myeducator-llc.github.io/voshi-docs/advanced/provisioning/overview).
  </Step>
</Steps>

Every launch of that placement then carries the location's configuration to your [launch receiver](https://myeducator-llc.github.io/voshi-docs/advanced/launch/receiving-launches):

```json
"location": {
  "id": "Il0c8n",
  "extid": "chapter3_quiz",
  "type": "assessment",
  "label": "Chapter 3 Quiz"
}
```

Voshi keeps its own copy of each destination's `type`, `label`, `description`, and `points`, taken from your list at the moment someone places it. That copy — one per extid, shared by every placement of it — is what a launch carries. (`description` and `points` are used by Voshi and the LMS; the launch claim carries `type` and `label`.)

<Warning>
So your served list is **not** a live configuration channel for content that's already placed. Change a `label` and existing placements keep launching with the value captured when they were made, until that destination is placed again by anyone. Switch on `location.extid` and read the current configuration from your own data instead of relying on the claim to be current.
</Warning>

## The two IDs

Every location has both, and both arrive in the launch:

| Field | Whose it is | Use it for |
| --- | --- | --- |
| `location.extid` | **yours**, from the list you serve | Looking the destination up in your own data. This is the one to switch on. |
| `location.id` | Voshi's, minted the first time it sees your extid | Correlating with Voshi's dashboard logs. Starts with `I` and is unique across every tool, school, and course in the Voshi ecosystem. |

The pairing is permanent, which is what lets an instructor's placement keep working across terms.

### What makes a good extid

An extid names a **resource**, not an occasion on which someone used it. That single rule produces the rest:

- **The same across courses, terms, and schools.** If the Persian architecture quiz is `quiz1` in one course, it is `quiz1` in every other course, in every semester, at every institution. That's what lets a course copied into next term keep working, and what lets your tool find the student's history for a resource.
- **No course-specific identifiers.** Don't build a context id, semester code, section number, term, or instructor id into an extid. `quiz1` — not `fall2026_cs101_quiz1`. Course, term, and person already arrive separately in the launch; folding them into the extid multiplies your catalog and breaks it on the first course copy.
- **Letters, digits, dashes, and underscores only.** No other special characters. Don't make one *entirely* of digits: browsers reorder all-numeric keys, so `1`, `2`, `10` will not reach the instructor in the [order you served them](https://myeducator-llc.github.io/voshi-docs/advanced/locations-endpoint#ordering). `q1`, `unit-1`, or any non-digit character avoids it.
- **Short and concise.** There's no hard length limit, but the extid appears in your own data, in storage scoping, and in gradebook routing — keep it readable.
- **Permanent.** Once an extid has been linked into a course, it can never be changed or reused for other content.

<Warning>
**Plan your extid scheme before you ship.** Because extids are permanent once linked, changing your mind later means stranding every link instructors have already placed. Work through resource identity, provisioning in your own database, course duplication across semesters, grade passback and gradebook line items, and data-storage scoping *first*. See [Extid](https://myeducator-llc.github.io/voshi-docs/concepts#extid) for worked examples of static and dynamic extid strategies.
</Warning>

## Types

Each location declares what it's for:

| Type | Meaning |
| --- | --- |
| `assessment` | Graded work. **The only type that can pass a grade back.** Placing it creates a gradebook column, worth the `points` you declared (100 by default), and enables the [grades API](https://myeducator-llc.github.io/voshi-docs/advanced/grades/api-reference) for its launches. |
| `practice` | Student practice; no grade attached. |
| `content` | Reading or reference material, no submission. |
| `setup` | A configuration screen, not a student-facing activity. |

## There are no per-location params

A location carries **no static key-value pairs**. Everything a launch tells you about the destination is its `extid`, `id`, `type`, and `label` — there is no `params` object on the location, in the launch claim or in your locations response.

<Warning>
If you built against an earlier version of these docs that described `location.params`, that object was never sent. Reading `location["params"]` raises; reading it defensively always yields nothing. **Encode the configuration in the extid, or look it up in your own database.**
</Warning>

So per-destination configuration lives in one of two places:

- **In the extid itself**, when the variants are few and stable — `ch1_quiz`, `ch2_quiz`, `ch3_quiz`.
- **In your own data**, keyed on the extid — the general answer, and the only one that lets you change configuration without re-placing anything.

## Choosing a location strategy

Two workable patterns:

- **One extid per destination** (`ch1_quiz`, `ch2_quiz`, …) — the instructor's picker lists everything explicitly; your tool switches on `location.extid`.
- **A generated extid per placement** — for tools where each link is its own distinct thing, like a per-lecture discussion. Generate a fresh extid (a `uuid4` works) each time a link is placed, so the tool accumulates many dynamic locations rather than a fixed catalog.

Either way your tool switches on `location.extid` and reads the rest from its own records. See the [examples in Concepts](https://myeducator-llc.github.io/voshi-docs/concepts#examples-of-extid-strategies).

### One location per thing

Whichever pattern you pick, the sizing rule is the same: **one location for each thing you want graded, and one location for each non-graded thing you want to show.** If it needs its own gradebook column, it's its own location.

Don't plan on placing the same location twice in a course to get two of anything — both links resolve to the same resource, share the same storage rows, and feed the same gradebook column. Duplicate links do happen anyway (course copies, module edits), and your tool needs no special handling for them. See [Placement](https://myeducator-llc.github.io/voshi-docs/concepts#placement).

<Warning>
**Keep serving your locations.** Dropping an extid from the list you serve removes it from the instructor's picker, but every link already placed keeps launching — potentially for years, in courses copied forward term after term. Retiring a location breaks those courses, and nothing tells you it happened. Plan to serve a location for as long as anyone might still be linking to it. If you genuinely must stop offering one, keep handling its launches and render your own "no longer available" screen rather than erroring.
</Warning>

## The dashboard's Locations tab

For a self-hosted tool, the **Locations** tab is a read-only record: it lists the locations Voshi has seen, meaning the ones instructors have actually placed. A location shows up there the first time someone places it — not when you start offering it — so an empty tab on a new tool is normal, and the tab is never the list instructors choose from.

There is nothing to define there and nothing to keep in sync. The list you serve from your [Locations URL](https://myeducator-llc.github.io/voshi-docs/advanced/locations-endpoint) is what an instructor sees.

<Note>
Locations *are* defined in the dashboard for **hosted** tools, which have no server of their own to ask — see [Locations](https://myeducator-llc.github.io/voshi-docs/building/locations) in the hosted section. If you were told to create locations there and you run your own server, you're reading a stale instruction — build the endpoint instead.
</Note>

---

# Serving your locations

> The endpoint Voshi calls to ask your tool which destinations an instructor can place.

Source: https://myeducator-llc.github.io/voshi-docs/advanced/locations-endpoint

The **locations endpoint** is the third HTTPS endpoint you build — the **Locations URL** you give when [registering your tool](https://myeducator-llc.github.io/voshi-docs/advanced/overview). When an instructor places your tool in a course, Voshi asks this endpoint what your tool currently offers and shows them the answer.

That makes your catalog **live**: you can add a chapter, retire a quiz, or tailor what a particular school sees without touching anything in Voshi. You choose how it is presented too — a flat list, or [groups](#grouped_locations--arranging-a-large-catalog) the instructor opens as needed — and you can send them a [message](#message--explaining-what-they-are-looking-at) alongside it, which is the only way to explain an empty picker.

<Note>
A tool with no Locations URL **cannot be placed in a course**. The instructor gets a deep-link error instead of a picker, so this endpoint is required before your tool goes live.
</Note>

## The request Voshi sends you

```http
POST /voshi/locations HTTP/1.1
Host: myapp.example.com
Content-Type: application/x-www-form-urlencoded

launch_data=eyJhbGciOiJSUzI1NiIsImtpZCI6...
```

The same single `launch_data` field, from Voshi's server, signed the same way. **Verify the signature** exactly as you verify a launch — see [Verifying the launch JWT](https://myeducator-llc.github.io/voshi-docs/advanced/launch/verifying-the-jwt). It's the only credential on the request, so an unverified `launch_data` is an unauthenticated caller asking for your catalog.

### Claims

```json
{
  "iat": 1751470000,
  "exp": 1751477200,
  "iss": "https://api.link.voshi.com",
  "api": {
    "domain": "api.link.voshi.com",
    "token": null
  },
  "app": "I4ppXy",
  "context": "IcT91mBxze",
  "organization": {
    "title": "Example University",
    "issuer": "I1ssU3r",
    "client": "Icl13nt",
    "deployment": "Id3pL0yMnt"
  },
  "user": {
    "id": "In4kDp7yZq",
    "member": "Im8mBr42",
    "groups": ["instructor"],
    "given_name": "Ada",
    "family_name": "Lovelace",
    "full_name": "Ada Lovelace",
    "email": "ada@example.edu"
  }
}
```

`app`, `context`, `organization`, and `user` mean what they mean [in a launch](https://myeducator-llc.github.io/voshi-docs/advanced/launch/launch-claims#claims) — use `context` and `organization` if you tailor the list per course or per school.

Because only course staff place content, `user.email` and the name fields are normally populated here (they follow the same [course-staff-only rule](https://myeducator-llc.github.io/voshi-docs/advanced/launch/launch-claims#claims) as a launch). That makes `user.email` the practical claim to branch on if some instructors should see destinations others don't.

<Warning>
**`api.token` is `null` here**, and there is no `launch_id`, `location`, `course`, `resource_link`, `storage`, or `provision` claim: this request isn't a launch, so there's nothing to read or write and no per-user credential. Every `user` field can also be `null` depending on how the instructor reached the picker — treat the whole object as optional and default to your full catalog when it's empty.
</Warning>

<Note>
**Requests from the dashboard's [Sandbox](https://myeducator-llc.github.io/voshi-docs/advanced/overview#testing-your-tool)** are ordinary requests — the trial course places content through the same picker an instructor uses, so your endpoint is called exactly as it will be in production and there is no test flag to branch on. Answer normally; that's the point of the exercise.
</Note>

## The response

Answer `200` with a JSON object. It has three keys, all optional: **`locations`** (what you offer), **`grouped_locations`** (the same, arranged into collapsible sections), and **`message`** (a sentence for the instructor to read). The simplest useful answer is `locations` alone:

```json
{
  "locations": {
    "chapter3_quiz": {
      "type": "assessment",
      "label": "Chapter 3 Quiz",
      "description": "20 questions on normal distributions. Auto-graded.",
      "points": 50
    },
    "chapter3_practice": {
      "type": "practice",
      "label": "Chapter 3 Practice",
      "description": "Untimed drill on the same material."
    },
    "syllabus": {
      "type": "content",
      "label": "Course Syllabus"
    }
  }
}
```

Anything else at the top level is ignored. Return the full current list on every call — Voshi asks each time an instructor opens the picker — and in the order you want it read, since [nothing is re-sorted](#ordering) on the way to the instructor.

An answer naming **none** of `locations`, `grouped_locations`, or `message` is rejected as an invalid structure: it means we reached something other than your locations endpoint. To say "nothing right now", send a [`message`](#message--explaining-what-they-are-looking-at).

What you serve decides what instructors can place *now*. When one of them places a destination, Voshi stores a copy of that entry and every launch of that placement carries the copy — see [the warning on Locations](https://myeducator-llc.github.io/voshi-docs/advanced/locations#how-instructors-place-your-locations).

### Per-location fields

<ParamField body="type" type="string" required>
  What the location is for: `assessment`, `practice`, `content`, or `setup`. Only `assessment` can pass a grade back. See [Locations](https://myeducator-llc.github.io/voshi-docs/advanced/locations#types).
</ParamField>

<ParamField body="label" type="string" required>
  The name the instructor sees in the picker, and the default name of the placement in their course.
</ParamField>

<ParamField body="description" type="string">
  A longer explanation shown next to the label while they choose. Optional.
</ParamField>

<ParamField body="points" type="number" default="100">
  For `assessment` locations, the points the gradebook column is worth. Ignored for other types — and dropped if a location stops calling itself an assessment. Your [grade submissions](https://myeducator-llc.github.io/voshi-docs/advanced/grades/grade-passback) are fractions from 0 to 1, which the LMS scales to this number.
</ParamField>

### `message` — explaining what they are looking at

Send `message` to put a line of text above the picker. It exists mainly for the answer with **nothing in it**: an empty picker tells the instructor only that something is wrong, while you are the one who knows why — their email matches no account, their institution has adopted nothing, their trial expired.

```json
{
  "message": "We couldn't match your LMS email address to an account, so there's nothing here to place yet. Ask your administrator to add it, then reopen this picker.",
  "locations": {}
}
```

<ParamField body="message" type="string">
  Text shown to the instructor above the picker. Optional, and valid on its own — an answer with a `message` and no locations is a complete answer.
</ParamField>

Two things to know about how it is treated:

- **It is displayed as plain text.** Any markup is stripped before it is shown, so a link, a bold word, or an `<a>` tag is pointless — write the sentence you want them to read. Line breaks survive.
- **It is truncated at 2000 characters.** This is a sentence or two, not a page.

<Note>
A `message` is shown whether or not you also send locations, so you can use it for a heads-up beside a full catalog ("only your pilot units are listed this term"). Don't send one on every ordinary call — a note that is always there is one nobody reads.
</Note>

### `grouped_locations` — arranging a large catalog

If you offer more than a screenful, group it with `grouped_locations`. Each group is a **collapsible section**: the instructor sees the labels first, opens what interests them, and ticks individual locations or takes a whole group at once — from as many groups as they like in a single placement.

```json
{
  "locations": {
    "syllabus": {
      "type": "content",
      "label": "Course Syllabus"
    }
  },
  "grouped_locations": [
    {
      "label": "Unit 1 — Descriptive Statistics",
      "description": "Chapters 1-3",
      "locations": {
        "u1_quiz": {
          "type": "assessment",
          "label": "Unit 1 Quiz",
          "points": 50
        }
      },
      "grouped_locations": [
        {
          "label": "Extra credit",
          "locations": {
            "u1_bonus": {
              "type": "practice",
              "label": "Bonus drill"
            }
          }
        }
      ]
    },
    {
      "label": "Unit 2 — Probability",
      "locations": {
        "u2_quiz": {
          "type": "assessment",
          "label": "Unit 2 Quiz",
          "points": 50
        }
      }
    }
  ]
}
```

Every group starts **collapsed**, at every level, and shows a count of what the instructor has ticked inside it while it is shut. Its checkbox takes or releases the whole subtree — the group's own locations and all of its subgroups' — so a unit can be placed in one click.

Top-level `locations` are shown **above** the groups and are not collapsed, so put there the handful of things everyone places — a location inside a collapsed group is a location fewer instructors click. A group with nothing in it still renders, as a row that opens onto nothing, so drop your empty groups rather than sending them.

#### Group fields

<ParamField body="label" type="string" required>
  The group's name. Until the instructor opens it, this is the only thing they see of what is inside — so make it say what is in there. Treated like `message`: reduced to plain text, and truncated at 200 characters.

  It must still say something once that is done. An empty label, or one that is nothing but whitespace or markup, is refused as an invalid structure rather than drawn as a blank row nobody can identify.
</ParamField>

<ParamField body="description" type="string">
  A line under the label, shown whether or not the group is open. Optional, and treated the same way — plain text, truncated at 200 characters.
</ParamField>

<ParamField body="locations" type="object">
  The locations in this group, keyed by external ID exactly as the top-level `locations` object is. Same required fields, same extid rules.
</ParamField>

<ParamField body="grouped_locations" type="array">
  Subgroups, the same shape all the way down — a group holds locations exactly the way the response itself does, which is why it is the same key. Nesting is capped at **5 levels**; a deeper answer is refused as an invalid structure.
</ParamField>

<Warning>
**Grouping is presentation only.** A location's group is not part of its external ID, is not stored on the location, and never appears in a launch. That is what makes regrouping safe — you can reorganize your catalog freely, and content instructors have already placed keeps working. It also means the group cannot be used to distinguish two locations: two entries with the same extid in different groups are one location, shown twice.
</Warning>

### Ordering

**The order you send is the order they see.** Nothing is sorted, alphabetized, or rearranged — the picker draws your answer in the order your JSON puts it, so the sequence is a presentation decision you make, not one Voshi makes for you. Send your units in teaching order and they read in teaching order.

Three rules cover the whole response:

- **Groups appear in array order.** `grouped_locations` is a list, and it is walked front to back, at every level of nesting.
- **Locations appear in the order the keys are written** in their `locations` object — the first key is the first card. This holds for the top-level object and for each group's.
- **Locations come before groups**, at the top level and inside every group: a group's own locations are drawn first, then its subgroups. So a group that mixes the two always shows its own items above its nested sections.

<Warning>
**Don't use purely numeric extids if order matters.** Browsers reorder JSON object keys that are entirely digits — they move ahead of every other key and sort ascending, whatever order you wrote them in. `{"10": …, "2": …}` reaches the instructor as `2` then `10`, and `{"20": …, "syllabus": …}` shows `20` first. That's a rule of the language, not something Voshi applies, so it happens before we could preserve anything.

Adding any non-digit character is enough to opt out — `u2_quiz`, `quiz-2`, `q2`. Prefixing your identifiers is worth doing anyway, for [all the other reasons](https://myeducator-llc.github.io/voshi-docs/advanced/locations#what-makes-a-good-extid) a bare number makes a poor extid.
</Warning>

Reordering is always safe to do later: a location's position is presentation only, exactly like its group, and placements instructors have already made are unaffected.

### External IDs are yours, and permanent

The key of each entry is the **external ID** (`extid`) — your own identifier for that destination. Use letters, digits, underscores, and dashes.

The first time Voshi sees an extid it creates its own location record for it, and from then on the two are bound: every link to that destination, in every course, at every school, points at that pairing. Both IDs arrive in the launch, as `location.extid` and `location.id`.

Serve the **same extid for the same resource everywhere** — every course, every school, every semester. That consistency is what makes a course copied into next term keep working. Don't put a context id, semester code, or instructor id in an extid. See [What makes a good extid](https://myeducator-llc.github.io/voshi-docs/advanced/locations#what-makes-a-good-extid).

<Warning>
**Never reuse an extid for different content.** Reassigning `quiz1` from Chapter 1's quiz to Chapter 2's silently retargets every placement instructors have already made — students clicking last term's link get the new content, and you won't get an error. Retire an extid by dropping it from the list and issuing a new one.
</Warning>

Dropping an extid from your response only hides it from the picker — links that already exist keep launching indefinitely. **The safe default is to keep serving every extid you have ever served.** If you must stop offering one, keep handling its launches and render a "this is no longer available" screen of your own rather than erroring.

## Examples

<Tabs groupId="lang">

<TabItem value="python" label="Python (Flask)">

```python
@app.post("/voshi/locations")
def voshi_locations():
    claims = verify_launch_jwt(request.form["launch_data"])   # see Verifying the JWT

    email = (claims.get("user") or {}).get("email")
    instructor = Instructor.query.filter_by(email=email).first() if email else None
    if email and instructor is None:
        # Nothing to offer, and we're the only ones who know why.
        return {"message": "We couldn't match your LMS email address to an account. "
                           "Ask your administrator to add it, then reopen this picker."}

    grouped = []
    for unit in Unit.query.all():
        grouped.append({
            "label": f"Unit {unit.number} — {unit.title}",
            "locations": {
                f"u{unit.number}_quiz": {
                    "type": "assessment",
                    "label": f"Unit {unit.number} Quiz",
                    "description": unit.quiz_blurb,
                    "points": unit.quiz_points,
                },
            },
        })

    return {
        "locations": {"syllabus": {"type": "content", "label": "Course Syllabus"}},
        "grouped_locations": grouped,
    }
```

</TabItem>

<TabItem value="javascript" label="Node (Express)">

```javascript
app.post('/voshi/locations', async (req, res) => {
  const claims = await verifyLaunchJwt(req.body.launch_data)   // see Verifying the JWT

  const email = claims.user?.email
  if (email && !(await findInstructor(email))) {
    // Nothing to offer, and we're the only ones who know why.
    return res.json({
      message: "We couldn't match your LMS email address to an account. " +
               'Ask your administrator to add it, then reopen this picker.',
    })
  }

  const grouped = (await listUnits()).map(unit => ({
    label: `Unit ${unit.number} — ${unit.title}`,
    locations: {
      [`u${unit.number}_quiz`]: {
        type: 'assessment',
        label: `Unit ${unit.number} Quiz`,
        description: unit.quizBlurb,
        points: unit.quizPoints,
      },
    },
  }))

  res.json({
    locations: { syllabus: { type: 'content', label: 'Course Syllabus' } },
    grouped_locations: grouped,
  })
})
```

</TabItem>

</Tabs>

## When this endpoint fails

An instructor is waiting on your response, so Voshi gives up after **30 seconds**. These all end the same way — the instructor sees a deep-link error and places nothing:

| What happened | What the instructor sees |
| --- | --- |
| No response within 30s | `Deep linking error: app connection timeout.` |
| Connection refused, DNS failure, bad TLS | `Deep linking error: app connection failure.` |
| Any non-2xx status | `Deep linking error: app failed to provide the available locations (status=…)` |
| A `3xx` redirect (Voshi does not follow it) | `Deep linking error: the app redirected the locations request; locations_url must name the endpoint itself.` |
| Body isn't JSON | `Deep linking error: the app returned invalid JSON.` |
| JSON doesn't match the shape above | `Deep linking error: the app returned an invalid locations structure: …` |
| Groups nested more than 5 deep | `Deep linking error: the app nested location groups more than 5 levels deep.` |
| A group whose `label` is empty, or is only whitespace or markup | `Deep linking error: the app returned a location group with an empty label.` |
| No Locations URL registered | `Deep linking error: App … does not have a locations_url configured.` |

Your tool is never told that any of this happened — there's no retry callback and nothing in your logs but the request you failed to answer. Because these reach instructors rather than you, keep the handler cheap and independent of anything slow.

<Note>
Placing a location also **starts [provisioning](https://myeducator-llc.github.io/voshi-docs/advanced/provisioning/overview)** for it: Voshi calls your Provision URL for the course and the location as soon as the instructor confirms, without waiting for the first student.
</Note>

---

# How provisioning works

> Course setup: how Voshi asks your tool to prepare a course, and a location within it, before students arrive.

Source: https://myeducator-llc.github.io/voshi-docs/advanced/provisioning/overview

A course has to be **set up in your tool** before students can work in it there — content copied in, an assignment record created, whatever your tool needs to exist before the first student clicks. Voshi drives that setup through a second endpoint you register: the **Provision URL**.

Provisioning has two levels, and each happens **once**:

| Level | Claim | Fires when |
| --- | --- | --- |
| **Your tool in the course** | `provision.context` | The first time anyone opens your tool anywhere in that course. |
| **A location in the course** | `provision.location` | The first time anyone opens that particular [location](https://myeducator-llc.github.io/voshi-docs/concepts#location) in that course. |

Both can be asked for in the same request — the usual case being an instructor placing your tool in a brand-new course.

## The lifecycle

```mermaid
sequenceDiagram
    autonumber
    participant Instructor
    participant Voshi
    participant Tool as Your tool
    Instructor->>Voshi: Opens your tool in a course for the first time
    Voshi->>Tool: POST launch_data=<signed JWT> to your Provision URL
    Tool-->>Voshi: 204 No Content
    Tool->>Tool: Set the course up (background)
    Tool->>Voshi: PUT the provision URL for each level
    Instructor->>Voshi: Launches again
    Voshi->>Tool: POST launch_data to your Callback URL — a normal launch
```

1. **Voshi asks you to set up.** The request arrives at your Provision URL as a `POST` from Voshi's server, carrying the same single `launch_data` field a launch carries. The `provision` claim says which levels to set up. **Voshi asks once per level** — see [You are asked exactly once](https://myeducator-llc.github.io/voshi-docs/advanced/provisioning/receiving-provision-requests#you-are-asked-exactly-once).
2. **You answer `204` immediately** and do the work in the background. See [Receiving provision requests](https://myeducator-llc.github.io/voshi-docs/advanced/provisioning/receiving-provision-requests).
3. **You `PUT` each provision URL** as that level finishes. That is what marks the level ready.
4. **Launches flow normally from then on.** The next launch of that course, or that location, arrives at your Callback URL like any other.

## Until a level is provisioned, launches don't reach you

Voshi holds those launches itself rather than forwarding them. Whoever launches sees a **"Provisioning"** page — "Setting up resources for this location. Please try again in a few minutes." — and once your calls land, a relaunch gets them into your tool. The page doesn't refresh itself; the next launch is what moves them along.

A class never lands in a half-configured course, and your receiver never sees a launch for a course you haven't finished setting up.

### Who triggers it, and who can finish it

Normally the **instructor placing your tool** triggers setup: Voshi calls your Provision URL as soon as they confirm the placement, before any student can click it. That's the path to design for.

Any launch of a not-yet-provisioned level can start setup, though — and finishing it requires the launching person to be **course staff**. The `PUT` that marks a level ready authenticates with the launch's own `api.token`, and that token must belong to an `instructor`, `manager`, `assistant`, or `mentor` in the course. A `student`'s token is rejected with `403`.

<Warning>
So if the very first launch of a location is a student's, your finish call can't succeed with that token — and Voshi won't re-ask you, because setup is already marked as started. That course stays on the "Provisioning" page. Have someone on the MyEducator team reset it if you hit this, and place content through the instructor's content picker so the normal path is the one that runs.
</Warning>

## The course and location rows open at provisioning

The `context` and `location` [storage](https://myeducator-llc.github.io/voshi-docs/advanced/app-data/overview) rows stay closed until the matching level is provisioned; the `member` and `member_location` rows are open from the first launch.

Useful side effect: the finish call takes an optional body. `PUT`ting `{"weeks": 14, "term": "fall"}` to a provision URL both marks the level ready and writes that JSON as the level's opening storage row, in one call.

## Next

<CardGroup cols={2}>
  <Card title="Receiving provision requests" href="/advanced/provisioning/receiving-provision-requests">
    The claims, the `204`, and the finish call.
  </Card>
  <Card title="Serving your locations" href="/advanced/locations-endpoint">
    The other endpoint Voshi calls: your list of destinations.
  </Card>
</CardGroup>

---

# Receiving provision requests

> The provisioning endpoint you build, the claims it receives, and the call that marks a level ready.

Source: https://myeducator-llc.github.io/voshi-docs/advanced/provisioning/receiving-provision-requests

The **provisioning receiver** is the second HTTPS endpoint you build — the **Provision URL** you give when [registering your tool](https://myeducator-llc.github.io/voshi-docs/advanced/overview). Voshi calls it when a course, or a location in a course, needs to be set up in your tool. See [How provisioning works](https://myeducator-llc.github.io/voshi-docs/advanced/provisioning/overview) for when that happens.

## The request Voshi sends you

```http
POST /provision HTTP/1.1
Host: myapp.example.com
Content-Type: application/x-www-form-urlencoded

launch_data=eyJhbGciOiJSUzI1NiIsImtpZCI6...
```

The same single `launch_data` field a launch carries, signed the same way. **Verify the signature exactly as you verify a launch** — see [Verifying the launch JWT](https://myeducator-llc.github.io/voshi-docs/advanced/launch/verifying-the-jwt).

<Note>
Unlike a launch, this `POST` comes **from Voshi's server**, not through anyone's browser. Nothing is rendered from your response — the person who triggered setup is watching Voshi's "Provisioning" page, not your tool.
</Note>

## Requirements for your endpoint

- **Public HTTPS.** An absolute `https://` URL on a publicly-routable host, validated when you register it and re-checked every time Voshi calls it.
- **Accept a form POST.** `Content-Type: application/x-www-form-urlencoded`, one field named `launch_data`.
- **Answer `204 No Content` promptly** — within a few seconds. Voshi gives up after 60 seconds, and an instructor is waiting on the other end. Do the setup work *after* you respond.
- **You don't need to de-duplicate.** Voshi sends your tool **exactly one** provisioning request per level — see [You are asked exactly once](#you-are-asked-exactly-once).

## You are asked exactly once

**Voshi will only ever send your tool one provisioning request for a given level.** Concurrency on the way in — two instructors opening a brand-new course at the same moment, a student and an instructor clicking at once — is resolved by Voshi before it reaches you. Your tool does not have to de-duplicate provisioning requests or guard against a second one arriving for the same course or location.

The flip side is that there is no retry: if your tool drops the request or your setup job dies, Voshi does not ask again, and the course stays on the "Provisioning" page until you call the provision URL. See [Who triggers it, and who can finish it](https://myeducator-llc.github.io/voshi-docs/advanced/provisioning/overview#who-triggers-it-and-who-can-finish-it).

## Which request is which

**A request is identified by where it arrives.** A `POST` to your Callback URL is always a person opening your tool. A `POST` to your Provision URL is course setup, with a smaller set of claims — no user is doing coursework yet.

## Claims

```json
{
  "iat": 1751470000,
  "exp": 1751477200,
  "iss": "https://api.link.voshi.com",
  "api": {
    "domain": "api.link.voshi.com",
    "token": "8f2c1a..."
  },
  "app": "I4ppXy",
  "context": "IcT91mBxze",
  "organization": {
    "title": "Example University",
    "issuer": "I1ssU3r",
    "client": "Icl13nt",
    "deployment": "Id3pL0yMnt"
  },
  "user": {
    "id": "In4kDp7yZq",
    "member": "Im8mBr42",
    "groups": ["instructor"],
    "given_name": "Ada",
    "family_name": "Lovelace",
    "full_name": "Ada Lovelace",
    "email": "ada@example.edu"
  },
  "course": {
    "id": "IcT91mBxze",
    "name": "Intro to Computing",
    "label": "CS101"
  },
  "location": {
    "id": "Il0c8n",
    "extid": "quiz1",
    "type": "assessment",
    "label": "Quiz 1"
  },
  "resource_link": "Ir3sLnk42",
  "provision": {
    "context": "https://api.link.voshi.com/lti13/v1/contexts/IcT91mBxze/apps/I4ppXy/provision",
    "location": "https://api.link.voshi.com/lti13/v1/contexts/IcT91mBxze/apps/I4ppXy/locations/ext:quiz1/provision"
  },
  "parent_context": "Ic0pI3dFr0m",
  "storage": {
    "context": "https://api.link.voshi.com/lti13/v1/contexts/IcT91mBxze/apps/I4ppXy/data",
    "location": "https://api.link.voshi.com/lti13/v1/contexts/IcT91mBxze/apps/I4ppXy/locations/ext:quiz1/data",
    "parent_context": "https://api.link.voshi.com/lti13/v1/contexts/Ic0pI3dFr0m/apps/I4ppXy/data",
    "parent_location": "https://api.link.voshi.com/lti13/v1/contexts/Ic0pI3dFr0m/apps/I4ppXy/locations/ext:quiz1/data"
  }
}
```

<ResponseField name="provision" type="object">
  **What needs setting up.** Only the levels being asked for are present — `context`, `location`, or both. Each value is the URL you call when that level is done. Treat the URLs as opaque and use them as given.
  <Expandable title="provision fields">
    <ResponseField name="context" type="string">
      Present when **your tool in this course** needs setting up.
    </ResponseField>
    <ResponseField name="location" type="string">
      Present when **this location in this course** needs setting up.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="context" type="string">
  The course being set up — the same ID that appears in the `contexts/…` segment of the storage URLs.
</ResponseField>

<ResponseField name="location" type="object">
  The location the triggering launch targeted, in the same shape as the [Launch Data claim](https://myeducator-llc.github.io/voshi-docs/advanced/launch/launch-claims#claims): `id`, `extid`, `type`, `label`. **`null`** when the launch targeted no location — in which case `provision.location`, `storage.location`, and `storage.parent_location` are absent or null too.
</ResponseField>

<ResponseField name="parent_context" type="string">
  Set when this course was **copied from another course** — the ID of the course it came from. `null` for an original course. See [Copied courses](#copied-courses).
</ResponseField>

<ResponseField name="storage" type="object">
  The [storage](https://myeducator-llc.github.io/voshi-docs/advanced/app-data/overview) rows this setup opens, plus the matching rows of the course this one was copied from.
  <Expandable title="storage fields">
    <ResponseField name="context" type="string">
      The course row you are provisioning.
    </ResponseField>
    <ResponseField name="location" type="string">
      The location row you are provisioning.
    </ResponseField>
    <ResponseField name="parent_context" type="string">
      The same row in the course this one was copied from — `null` for an original course.
    </ResponseField>
    <ResponseField name="parent_location" type="string">
      The same location's row in the course this one was copied from — `null` for an original course.
    </ResponseField>
  </Expandable>
</ResponseField>

The remaining claims — `iat`, `exp`, `iss`, `api`, `app`, `course`, `organization`, `user`, `resource_link` — mean exactly what they mean [in Launch Data](https://myeducator-llc.github.io/voshi-docs/advanced/launch/launch-claims#claims). `user` is the person whose launch triggered setup; in the normal flow that is the instructor placing your tool, so their `groups` reflect course staff and the `user` name and email fields are populated (they follow the same [course-staff-only rule](https://myeducator-llc.github.io/voshi-docs/advanced/launch/launch-claims#claims) as a launch).

### What a provision request does not carry

No **`launch_id`**, **`time`**, or **`grade`**. Nobody is doing coursework yet and there is nobody to grade, so there is no score to publish.

## What your tool must do

<Steps>
  <Step title="Verify and answer 204">
    Verify the JWT, note what the `provision` claim is asking for, and return `204 No Content` right away. Don't hold the response while you work.
  </Step>
  <Step title="Set the levels up">
    In the background, do whatever "this course exists in my app" and "this assignment exists in my app" mean for you.
  </Step>
  <Step title="PUT each provision URL">
    Call the URL for each level as that level finishes. This is what opens the level up — until it lands, launches keep waiting.
  </Step>
</Steps>

```python
@app.post("/provision")
def provision_receiver():
    data = verify_launch_jwt(request.form["launch_data"])   # see Verifying the JWT

    queue_setup(data)          # background — see below
    return "", 204             # answer first, work later
```

## Marking a level ready

`PUT` the URL from the `provision` claim, authenticated with the request's own `api.token`:

<Tabs groupId="lang">

<TabItem value="curl" label="curl">

```bash
curl -X PUT "https://api.link.voshi.com/lti13/v1/contexts/IcT91mBxze/apps/I4ppXy/provision" \
    -H "Authorization: Bearer 8f2c1a..." \
    -H "Content-Type: application/json" \
    -d '{"weeks": 14, "term": "fall"}'
```

</TabItem>

<TabItem value="python" label="Python">

```python
import requests

def finish_setup(data):
    token = data["api"]["token"]
    headers = {"Authorization": f"Bearer {token}"}

    # The course first — a location cannot be provisioned before its course.
    if "context" in data["provision"]:
        requests.put(
            data["provision"]["context"],
            headers=headers,
            json={"weeks": 14, "term": "fall"},   # optional: seeds the course storage row
        ).raise_for_status()

    if "location" in data["provision"]:
        requests.put(
            data["provision"]["location"],
            headers=headers,
        ).raise_for_status()
```

</TabItem>

<TabItem value="javascript" label="Node">

```javascript
async function finishSetup(data) {
  const headers = {
    Authorization: `Bearer ${data.api.token}`,
    'Content-Type': 'application/json',
  }

  // The course first — a location cannot be provisioned before its course.
  if (data.provision.context) {
    await fetch(data.provision.context, {
      method: 'PUT',
      headers,
      // optional: seeds the course storage row
      body: JSON.stringify({ weeks: 14, term: 'fall' }),
    })
  }

  if (data.provision.location) {
    await fetch(data.provision.location, { method: 'PUT', headers })
  }
}
```

</TabItem>

</Tabs>

Both calls answer **`204 No Content`**.

The token has to belong to **course staff** — an `instructor`, `manager`, `assistant`, or `mentor`. Provisioning triggered by an instructor placing your tool always satisfies that; a `403` here means the launch that triggered setup came from a `student`, who can't complete it, which needs a platform-side reset. See [Who triggers it, and who can finish it](https://myeducator-llc.github.io/voshi-docs/advanced/provisioning/overview#who-triggers-it-and-who-can-finish-it).

<ParamField body="body" type="object">
  **Optional.** Whatever JSON you send becomes the initial contents of that level's [storage row](https://myeducator-llc.github.io/voshi-docs/advanced/app-data/overview) — the same object a later `GET` on `storage.context` or `storage.location` returns. Send no body to leave the row as it is.
</ParamField>

### Order matters

**A location cannot be provisioned before its course.** `PUT`ting a `provision.location` URL while the course's `provision.context` is still unfinished is rejected with `App … must be provisioned before its locations are provisioned`. If you want to set up all of your locations at once, call `provision.context` first, then loop over the location URLs.

### It doesn't have to be synchronous

You may call a provision URL **any time** — from a background job, or long after the request that prompted it. You may also provision locations Voshi hasn't asked about yet, which is how you set a whole course up in one pass.

<Warning>
Launches for a level wait until its provision call lands, so don't leave it for later. The instructor watching the "Provisioning" page has no way to retry from the browser — if your setup job dies, their course stays stuck until you call the URL.
</Warning>

## Copied courses

When an instructor copies a course — a new term from last term's shell — the new course provisions **from scratch**. But the request tells you where it came from:

- **`parent_context`** — the ID of the course this one was copied from.
- **`storage.parent_context`** / **`storage.parent_location`** — the previous course's data rows.

Read those rows to carry the instructor's earlier configuration forward, then write it into the new course as you provision. Voshi does not copy storage between courses; this claim is how you do it yourself, and it is the only point at which you're handed the previous course's rows.

```python
def carry_forward(data):
    parent = data["storage"]["parent_context"]
    if not parent:
        return {}                      # an original course — start from defaults
    resp = requests.get(parent, headers={"Authorization": f"Bearer {data['api']['token']}"})
    if resp.status_code in (403, 422):
        return {}                      # nothing to copy — fall back to defaults
    resp.raise_for_status()
    return resp.json()
```

All three are `null` for an original course. Reading them uses the launching user's token, so it only succeeds if that earlier course was itself provisioned and the user still has a role in it — treat `403` and `422` as **"nothing to copy"** rather than an error.

---

# Grade passback

> Push scores from your tool to the LMS gradebook.

Source: https://myeducator-llc.github.io/voshi-docs/advanced/grades/grade-passback

When a student finishes graded work in your tool, publish their score to Voshi and Voshi puts it in the LMS gradebook. One `POST`, no gradebook plumbing on your side.

The launch tells you where to send it. Every launch carries a `grade` claim holding a ready-made URL:

```json
"grade": {
  "submit": "https://api.link.voshi.com/lti13/v1/contexts/IcT91mBxze/members/Im8mBr42/apps/I4ppXy/locations/ext:quiz1/grade"
}
```

`POST` a score to that URL and it lands in the gradebook column for that student, that location, that course.

```mermaid
sequenceDiagram
    participant Tool as Your tool
    participant Voshi
    participant LMS
    Tool->>Voshi: POST grade.submit {score: 0.85}
    Voshi->>LMS: Publish score to the gradebook
    LMS-->>Voshi: OK / error
    Voshi-->>Tool: 200 + the attempt (status: success | failed)
```

## When you can send a grade

**`grade.submit` is `null` when this launch has nowhere to post a score.** That is the whole check — if it holds a URL you can grade, and if it is `null` you cannot. Store it at launch time and branch on it.

It is `null` unless **both** are true:

1. The launched [location](https://myeducator-llc.github.io/voshi-docs/advanced/locations) is of type **`assessment`**, and
2. The LMS created a **gradebook column** for the placement (which happens when an instructor places an assessment location through the content picker).

An `assessment` location placed some other way — a plain link the instructor pasted in, rather than one made with the picker — launches perfectly well but arrives with `grade.submit: null`. Degrade gracefully: run the activity, skip the grading UI.

<Note>
Treat the URL as **opaque** and call it exactly as it arrives. The one part you may change is the member segment — see [grading someone other than the launching user](#grading-a-student-who-is-not-the-one-launching).
</Note>

## Scores

`score` is a **fraction from 0.0 to 1.0** — a percentage, not points. The LMS scales it to the points the gradebook column is worth: on a 100-point column, `0.85` shows as 85 points.

That column is created when the instructor places the location, worth the `points` your [locations endpoint](https://myeducator-llc.github.io/voshi-docs/advanced/locations-endpoint#per-location-fields) declared for it (100 if you declared none). From then on it belongs to the instructor, who can change it in the LMS — so keep sending the fraction and don't assume the value you declared is still in force.

If your tool needs the column to be worth a particular number — an activity whose point value is decided at grading time rather than at placement — send the optional [`max_score`](https://myeducator-llc.github.io/voshi-docs/advanced/grades/api-reference#request-body) alongside the score. It rewrites the gradebook column's points possible before publishing, so `0.85` with `max_score: 50` lands as 42.5/50. It requires the school's LMS key to grant the AGS line-item scope, and an attempt that carries it fails visibly (`status: "failed"`) where that scope is missing, so only send it when you actually need to move the column.

## Every submission is an attempt, and nothing is overwritten

A grade submission is a **transaction, not a stored score.** Every `POST` publishes to the LMS there and then and records one attempt — whatever the LMS answered. Attempts are never updated and never replaced:

- A score the LMS **accepted** is a `success` attempt.
- A score it **rejected** is a `failed` attempt, and the response says why.
- Sending again — to regrade, to correct, or to retry a failure — is another `POST`, another call to the LMS, and another attempt.

So there is no sync status to poll, no retry endpoint, and no "current grade" object to keep in step. **The LMS gradebook is the record of what the student earned**; Voshi's attempts are the record of what the LMS was told. If the last attempt succeeded, the gradebook has that score.

<Note>
Repeat submissions are safe and expected. Each attempt carries a later timestamp than the one before, which is what makes an LMS accept it as the newer score — so regrading is just sending again.
</Note>

## One location, one gradebook column

**Define one [location](https://myeducator-llc.github.io/voshi-docs/concepts#location) for each thing you want graded.** A location's grades always land in a single gradebook column, so if you need two graded activities, you need two locations with two extids.

That holds even when a course ends up with several links to the same location — the instructor duplicated one, the LMS copied the course forward, or a link was deleted and re-added in another module. Each graded link brings its own gradebook line item, but **grade passback always goes to the first line item** for that location in that course. A student's score therefore always lands in the same place, no matter which link they launched from, and the extra links never give you extra columns to write to. See [Placement](https://myeducator-llc.github.io/voshi-docs/concepts#placement).

One consequence is worth planning for: if the *first* link placed in a course was not deep-linked, that course's location has no column and never gains one from a later link. Every launch there arrives with `grade.submit: null`.

## Grade any time — not just during the launch

Nothing about a grade is tied to the moment of the launch. The URL stays valid for as long as the placement exists, so grading can happen whenever it suits your tool:

- **Immediately**, when the student finishes the activity.
- **Later, asynchronously** — from a background job after manual or delayed grading.
- **From an instructor-facing page in your tool** — an instructor reviewing a submission and posting or correcting a score.

What *does* change with time is the credential. The two ways to authenticate are below: the launching user's token is short-lived and belongs to their session, while your tool's API key is yours and does not expire. **If you grade outside the launch session, use the API key.**

Store the `grade.submit` URL alongside the student's work at launch time so it's available whenever you're ready.

## Authentication

There are two ways to authorize a submission, and which URLs each one works on differs.

### As the launching user, with `api.token`

The same credential the [Storage API](https://myeducator-llc.github.io/voshi-docs/advanced/app-data/overview#authenticating-the-api-claim) uses — the `api.token` from the same launch:

```
Authorization: Bearer <api.token>
```

This works on whichever URL the launch handed you, and it acts as that person. It's the natural choice when the student's own session is still open — they just finished the quiz and your server is posting the score.

It is tied to that user's session and expires with it, so it is not the credential for grading hours or days later.

### As your tool's server, with your API key

A **self-hosted** tool can present its own API key instead, with no session at all:

```
Authorization: Bearer ltiaas_<app-id>_<secret>
```

This is the credential for background grading, instructor tooling, and anything else that runs long after the launch. It has three limits:

- **Only self-hosted tools have a key.** A hosted tool has no server of its own and no key — it grades with [`api.submitGrade()`](https://myeducator-llc.github.io/voshi-docs/api/grades), which uses the launch's own session.
- **It only works on `/contexts/…` URLs.** A student's launch hands you a `/account/v1/users/…` URL, which is defined as "the path user is the caller" and refuses a key with `401`. Every other launch — `instructor`, `assistant`, `manager`, `mentor` — hands you the `/contexts/…` form, which accepts either credential. Keep one of those URLs if you intend to grade by key — see [below](#grading-a-student-who-is-not-the-one-launching).
- **It reaches only courses your tool is actually placed in.** A key presented for a course where your tool has never launched is refused with `403`.

If a request carries both a session and a key, the session wins and the attempt is recorded as that person's.

<Warning>
Keep the API key server-side. It is shown once, at registration, and Voshi stores only a hash of it — a lost key can be [rotated](https://myeducator-llc.github.io/voshi-docs/advanced/overview#rotating-or-replacing-your-api-key) but never recovered.
</Warning>

## Grading a student who is not the one launching

An instructor grading a roster, or a background job scoring work that was submitted hours ago, needs to publish a score for a student whose launch isn't the one in hand.

A `/contexts/…` grade URL names the student in its `members/…` segment, and that segment is the one part of the URL you may change:

```
https://api.link.voshi.com/lti13/v1/contexts/{context}/members/{member}/apps/{app}/locations/ext:quiz1/grade
                                                        ^^^^^^^^ swap this for another student's user.member
```

Substitute any other member of the **same course** — their `user.member` from their own launch — and post the score there. Everything else stays byte-for-byte as it arrived.

You can do this with either credential, subject to the rules above: a non-student session may grade anyone in their course, and your API key may grade anyone in a course your tool is placed in. A student's own token may only ever grade that student.

<Note>
A score can be published for a student who has **never opened the activity** — an instructor grading offline work, or your tool scoring a whole roster. The student needs to be a member of the course; they do not need to have launched.
</Note>

## Progress fields

Two optional fields describe the submission state that the LMS shows alongside the score. The defaults fit the common case — grade when the student is done:

- `activity_progress`: `Completed` (default) or `Submitted` — has the student finished the activity?
- `grading_progress`: `FullyGraded` (default) or `Pending` — is this score final?

Send `Submitted` + `Pending` if you post provisional scores before final grading, then send again with the defaults when grading is complete.

## Seeing what happened

The response to each `POST` is the attempt itself, so the immediate outcome is always in hand — `status`, and `data.error` when it failed. See the [API reference](https://myeducator-llc.github.io/voshi-docs/advanced/grades/api-reference#response--200).

There is no API for reading attempts back later; your tool's history is whatever you logged from those responses. The dashboard shows a tool's full passback history (**Tools → your tool → Grades**), and instructors can see their own course's.

Ready for the details? See the [Grades API reference](https://myeducator-llc.github.io/voshi-docs/advanced/grades/api-reference).

---

# Grades API reference

> Publish a score: POST to the grade.submit URL from a launch.

Source: https://myeducator-llc.github.io/voshi-docs/advanced/grades/api-reference

There is one grade endpoint, and you never build its URL: it arrives in every launch as the **`grade.submit`** claim.

```
POST <grade.submit>
Content-Type: application/json
```

Call the URL exactly as it arrives and treat it as opaque — the only segment you may change is the member, to [grade another student in the same course](https://myeducator-llc.github.io/voshi-docs/advanced/grades/grade-passback#grading-a-student-who-is-not-the-one-launching).

`grade.submit` is `null` when the launch has no gradebook column to post to. There is nothing to call in that case; see [when you can send a grade](https://myeducator-llc.github.io/voshi-docs/advanced/grades/grade-passback#when-you-can-send-a-grade).

## Authentication

Either credential, on whichever URLs it is valid for ([details](https://myeducator-llc.github.io/voshi-docs/advanced/grades/grade-passback#authentication)):

```
Authorization: Bearer <api.token>                 # as the launching user; any grade.submit URL
Authorization: Bearer ltiaas_<app-id>_<secret>    # as your tool’s server; /contexts/… URLs only
```

## Publish a score

Every call publishes to the LMS and records one attempt. Nothing is updated in place — sending again is a new attempt and a new call to the LMS. See [every submission is an attempt](https://myeducator-llc.github.io/voshi-docs/advanced/grades/grade-passback#every-submission-is-an-attempt-and-nothing-is-overwritten).

### Request body

<ParamField body="score" type="number" required>
  The score as a **fraction from 0.0 to 1.0**. Outside that range it's a `422`.
</ParamField>

<ParamField body="max_score" type="number">
  **Optional.** The points the gradebook column should be worth. Sending it **updates the LMS gradebook column** to this value before the score is published, so `0.85` renders as `42.5` out of a `max_score` of `50`. Must be greater than 0. Omit it to leave the column at whatever the instructor (or your `points` declaration) set.

  <Warning>
  Sending `max_score` requires the school's LMS developer key to grant the AGS **line item** scope on top of the score scope. On a deployment that only grants score, the attempt comes back `status: "failed"` with the reason in `data.error` — loudly, rather than silently mis-scaling. If you don't need to change the column's value, don't send the field.
  </Warning>
</ParamField>

<ParamField body="comment" type="string" default="">
  A comment published to the LMS alongside the score.
</ParamField>

<ParamField body="activity_progress" type="string" default="Completed">
  `Completed` or `Submitted` — whether the student has finished the activity.
</ParamField>

<ParamField body="grading_progress" type="string" default="FullyGraded">
  `FullyGraded` or `Pending` — whether this score is final.
</ParamField>

### Example

<Tabs groupId="lang">

<TabItem value="bash" label="curl">

```bash
# $SUBMIT_URL is grade.submit from the launch
curl -X POST "$SUBMIT_URL" \
    -H "Authorization: Bearer ltiaas_myappid_mysecret" \
    -H "Content-Type: application/json" \
    -d '{
          "score": 0.85,
          "comment": "Nice work!"
        }'
```

</TabItem>

<TabItem value="python" label="Python">

```python
import requests

submit_url = launch["grade"]["submit"]
if submit_url:                      # null when this placement can't take a score
    resp = requests.post(
        submit_url,
        headers={"Authorization": "Bearer ltiaas_myappid_mysecret"},
        json={
            "score": 0.85,
            "comment": "Nice work!",
        },
    )
    resp.raise_for_status()
    attempt = resp.json()
    if attempt["status"] != "success":
        log.warning("gradebook rejected the score: %s", attempt["data"]["error"])
```

</TabItem>

<TabItem value="javascript" label="Node">

```javascript
const submitUrl = launch.grade.submit
if (submitUrl) {                    // null when this placement can't take a score
  const resp = await fetch(submitUrl, {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ltiaas_myappid_mysecret',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      score: 0.85,
      comment: 'Nice work!',
    }),
  })
  const attempt = await resp.json()
  if (attempt.status !== 'success') {
    console.warn('gradebook rejected the score:', attempt.data.error)
  }
}
```

</TabItem>

</Tabs>

### Response — `200`

The attempt that was just recorded.

```json
{
  "id": "Igp8dEx",
  "status": "success",
  "score": 0.85,
  "max_score": null,
  "activity_progress": "Completed",
  "grading_progress": "FullyGraded",
  "submitted": "2026-09-21T18:10:00+00:00",
  "member": "Im8mBr42",
  "location": "Il0c8n",
  "app": "I4ppXy",
  "context": "IcT91mBxze",
  "data": {
    "comment": "Nice work!",
    "response": {
      "status": 200,
      "body": ""
    },
    "error": "",
    "source_type": "api_key",
    "source_id": ""
  }
}
```

<ResponseField name="id" type="string">
  The attempt's ID. Useful in a support request; there is no endpoint that reads it back.
</ResponseField>

<ResponseField name="status" type="string">
  `success` or `failed` — **check this on every call.** A rejected score still returns `200`; the failure is reported here, not as an HTTP error.
</ResponseField>

<ResponseField name="score" type="number">
  The fraction you sent (0.0–1.0).
</ResponseField>

<ResponseField name="max_score" type="number | null">
  The `max_score` you sent, or `null` if you sent none.
</ResponseField>

<ResponseField name="submitted" type="string">
  The instant this score was published, which is also the timestamp the LMS was given. Each attempt carries a later one, which is what lets a regrade supersede an earlier score.
</ResponseField>

<ResponseField name="member" type="string">
  The student this score is for — matches `user.member` from their launch.
</ResponseField>

<ResponseField name="location" type="string">
  Voshi's ID for the location the score is for — matches `location.id` from the launch.
</ResponseField>

<ResponseField name="app" type="string">
  Your tool's ID.
</ResponseField>

<ResponseField name="context" type="string">
  The course, matching the launch's `context`.
</ResponseField>

<ResponseField name="data" type="object">
  What happened on the way to the gradebook.
  <Expandable title="data fields">
    <ResponseField name="comment" type="string">
      The comment you sent.
    </ResponseField>
    <ResponseField name="response" type="object | null">
      The LMS's own answer as `{status, body}`, or `null` if the attempt never reached it.
    </ResponseField>
    <ResponseField name="error" type="string">
      Why a `failed` attempt failed. Empty on success.
    </ResponseField>
    <ResponseField name="source_type" type="string">
      How this score was authorized: `session` (a launch session — the student's own or course staff's) or `api_key` (your tool's server).
    </ResponseField>
    <ResponseField name="source_id" type="string">
      For a `session`, the Voshi user ID of the person whose session it was. Empty for an `api_key` attempt, which is your tool itself.
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
The score payload Voshi sent the LMS is deliberately withheld from this response: it carries the student's LMS identifier, which is never handed to a tool.
</Note>

### Failed attempts vs. errors

The two are different, and the split is deliberate:

- **An LMS refusal is a `200` with `status: "failed"`.** The call was valid, it was made, the gradebook said no. `data.error` says why, and `data.response` carries the LMS's own words. The commonest case is a placement with no gradebook column — publish to a location that was never deep-linked in that course and you get a failed attempt reading `location has no line item`.
- **A bad request is an HTTP error** and nothing is published or recorded.

### Errors

| Status | Message | Cause |
| --- | --- | --- |
| `422` | `score must be between 0 and 1` | `score` outside 0.0–1.0. |
| `422` | `max_score must be greater than 0` | `max_score` sent as zero or negative. |
| `422` | `activity_progress must be one of [...]` | Value not `Submitted` or `Completed`. |
| `422` | `grading_progress must be one of [...]` | Value not `FullyGraded` or `Pending`. |
| `422` | `grade passback is only allowed for assessment locations` | The location isn't type `assessment`. A launch of one never offers a `grade.submit` URL in the first place. |
| `401` | `Missing Bearer API key` / `Invalid API key` / … | No credential, an unknown or rotated API key, a suspended tool, or an API key on a `/account/v1/users/…` URL — see [Errors](https://myeducator-llc.github.io/voshi-docs/reference/errors). |
| `403` | `API key is for tool …, not tool …` | The key belongs to a different tool than the URL names. |
| `403` | `tool … has no placement of location … in context …` | An API key used for a course your tool isn't placed in. |
| `403` | — | A session that isn't allowed to grade this member: a student's token aimed at anyone but themselves. |

## Reading attempts back

There is no endpoint for it. The response to each `POST` is the record, so log what you need from it.

A tool's full passback history is visible in the dashboard under **Tools → your tool → Grades**, and instructors can see their own course's.

---

# Storage

> Per-course, per-placement, and per-student JSON storage, built into every launch.

Source: https://myeducator-llc.github.io/voshi-docs/advanced/app-data/overview

Voshi gives your tool four JSON storage rows for every launch — scoped to the course, the placement, the student, and the student-on-placement. Many tools can use them as their entire persistence layer: no database, no user table, no schema migrations.

Each row holds one JSON object that is entirely yours. Voshi never reads or interprets it.

## The four scopes

Every launch JWT carries a `storage` claim with the URLs of the four rows relevant to that launch:

```json
"storage": {
  "context": "https://api.link.voshi.com/lti13/v1/contexts/IcT91mBxze/apps/I4ppXy/data",
  "location": "https://api.link.voshi.com/lti13/v1/contexts/IcT91mBxze/apps/I4ppXy/locations/ext:quiz1/data",
  "member": "https://api.link.voshi.com/lti13/v1/contexts/IcT91mBxze/members/Im8mBr42/apps/I4ppXy/data",
  "member_location": "https://api.link.voshi.com/lti13/v1/contexts/IcT91mBxze/members/Im8mBr42/apps/I4ppXy/locations/ext:quiz1/data"
}
```

Each value is the row's full URL — read and write the row by calling that URL directly with `GET`, `PUT`, or `PATCH`. Use it exactly as given and treat it as opaque: don't parse it or construct these URLs yourself.

| Scope | One row per... | Typical use |
| --- | --- | --- |
| `context` | course | Course-wide settings: term dates, module visibility, instructor preferences |
| `location` | placement (location × course) | Per-assignment configuration: due date overrides, question pool selection |
| `member` | user × course | The student's course-wide state: profile choices, cumulative progress |
| `member_location` | user × placement | The student's work on one assignment: answers, attempts, submission state |

## The course rows open at provisioning

The `member` and `member_location` rows are **open from the first launch** — nothing to create, nothing to wait for.

The `context` and `location` rows are different: they open when you [provision](https://myeducator-llc.github.io/voshi-docs/advanced/provisioning/overview) that course and that location. Until then every call against them answers `422`:

```json
{
  "error": "ValidationError",
  "message": "App I4ppXy has not been provisioned for Context IcT91mBxze"
}
```

In practice a launch never reaches your callback URL before its course is provisioned, so a row URL from a launch claim is already open. The gate matters while you're *doing* the provisioning — and there, the finish call itself takes an optional JSON body that becomes the row's opening contents, so you rarely need a separate write. See [Marking a level ready](https://myeducator-llc.github.io/voshi-docs/advanced/provisioning/receiving-provision-requests#marking-a-level-ready).

## Authenticating: the `api` claim

The Storage API authenticates **as the launching user**, not as your tool. The launch JWT's `api` claim gives you the credential:

```json
"api": {
  "domain": "api.link.voshi.com",
  "token": "8f14e45fceea167a5a36dedd4bea2543"
}
```

Send the token as a Bearer header on every call:

```
Authorization: Bearer <api.token>
```

<Note>
The token is tied to the launching user's Voshi session (which lasts about a week). Treat it as **per-launch**: capture it at launch time, use it server-side during the user's visit, and take a fresh one from their next launch. Don't embed it in client-side code — it acts as that user.
</Note>

## Who can access what

Access is enforced per row, based on the groups the token's user holds **in that course**:

| Row | `student` | `instructor` / `manager` / `assistant` / `mentor` |
| --- | --- | --- |
| `context` | read | read + write |
| `location` | read | read + write |
| `member` | read + write, **their own only** | read + write, **for any member of the course** |
| `member_location` | read + write, **their own only** | read + write, **for any member of the course** |

Two consequences worth designing around:

- **Students cannot write the shared rows.** A `PUT` or `PATCH` on `context` or `location` with a student's token returns `403`. Course-wide state that students need to change has to live somewhere else — their own `member` row, or your own database.
- **Course staff can read and write any student's rows.** That is what makes an instructor-facing view in your tool possible (reviewing a student's answers, resetting an attempt), and it means a student's `member_location` row is not private to that student. Don't store anything there you wouldn't show their instructor.

A student's own rows are reached at a different URL from the one staff use for the same row — which is why the `storage` claim hands you ready-to-call URLs chosen for the launching user, and why you must call them as given rather than building them yourself.

<Note>
**Your tool's builders get no automatic access.** Being a member of the tool in the dashboard does not grant access to any data row. To read rows for debugging, a builder has to be enrolled in the course as an instructor or a student like anyone else.
</Note>

Requests for rows outside these rules return `403`; a row URL that doesn't exist or doesn't belong to your tool returns `404`.

## Semantics worth knowing

- **Reads return your object exactly as you last wrote it.** A never-written row returns `{}`.
- **Writes are atomic per row.** Concurrent writers serialize — no torn writes. For read-modify-write flows, prefer [`PATCH`](https://myeducator-llc.github.io/voshi-docs/advanced/app-data/api-reference#patch-apply-a-json-patch) so you only touch the keys you mean to change.
- **Carrying a course forward is yours to do.** When a school starts a new term by copying an old course, the new course provisions from scratch — and the provision request hands you the *previous* course's `context` and `location` row URLs so you can read them and write what matters into the new ones. Voshi doesn't copy anything on its own. See [Copied courses](https://myeducator-llc.github.io/voshi-docs/advanced/provisioning/receiving-provision-requests#copied-courses).
- **The JSON object has a size limit**: **512 KB** on the `member` and `member_location` rows, **1 MB** on `context` and `location`, measured as compact JSON. A write over the limit is refused with `422`. This is configuration-and-state storage; anything larger belongs in the row's **files**.
- **Every row keeps files too.** The launch's `files` claim carries a URL per row, beside `storage`, for data too large for the object or not JSON at all — up to 25 MB per file and 100 files per row. See [Files](https://myeducator-llc.github.io/voshi-docs/advanced/app-data/api-reference#files).

## Example: saving a student's progress

```python
import requests

def save_progress(launch, question, answer):
    requests.patch(
        launch["storage"]["member_location"],
        headers={"Authorization": f"Bearer {launch['api']['token']}"},
        json={"patch": [
            {"op": "add", "path": f"/answers/{question}", "value": answer},
        ]},
    ).raise_for_status()
```

Full endpoint details: [Storage API reference](https://myeducator-llc.github.io/voshi-docs/advanced/app-data/api-reference).

---

# Storage API reference

> Read, replace, and patch your tool's storage rows.

Source: https://myeducator-llc.github.io/voshi-docs/advanced/app-data/api-reference

Every storage row is addressed by its **URL from the launch's `storage` claim** — there are no paths to construct. Call the URL exactly as it arrives in the claim, and treat it as opaque.

All storage requests authenticate with the **`api.token` from a launch** (not your API key):

```
Authorization: Bearer <api.token>
```

See [authenticating](https://myeducator-llc.github.io/voshi-docs/advanced/app-data/overview#authenticating-the-api-claim) for how the token works and [who can access what](https://myeducator-llc.github.io/voshi-docs/advanced/app-data/overview#who-can-access-what) for the permission rules.

## Operations

All four rows — `context`, `location`, `member`, and `member_location` — support the same three operations on their `storage` URL (and the [file operations](#files) on their `files` URL):

| Method | Effect |
| --- | --- |
| `GET` | Read the row's JSON object. |
| `PUT` | Replace the row's contents wholesale. |
| `PATCH` | Apply an RFC 6902 JSON Patch to the row. |

The examples below use the row URL captured at launch time, e.g. `row_url = launch["storage"]["member_location"]`.

## GET: read a row

```
GET <row URL>
```

Returns **`200`** with your JSON object, exactly as last written — no envelope. A never-written row returns `{}`.

<Tabs groupId="lang">

<TabItem value="bash" label="curl">

```bash
# $ROW_URL is storage.member_location from the launch
curl "$ROW_URL" \
    -H "Authorization: Bearer $API_TOKEN"
```

</TabItem>

<TabItem value="python" label="Python">

```python
import requests

resp = requests.get(
    launch["storage"]["member_location"],
    headers={"Authorization": f"Bearer {api_token}"},
)
resp.raise_for_status()
data = resp.json()   # e.g. {"answers": {"q1": "B"}, "attempts": 1}
```

</TabItem>

<TabItem value="javascript" label="Node">

```javascript
const resp = await fetch(
  launch.storage.member_location,
  { headers: { Authorization: `Bearer ${apiToken}` } }
)
const data = await resp.json()   // e.g. {"answers": {"q1": "B"}, "attempts": 1}
```

</TabItem>

</Tabs>

## PUT: replace a row

```
PUT <row URL>
Content-Type: application/json
```

The body is your **raw JSON object** (no wrapper). It replaces the row's contents wholesale. Returns **`204 No Content`**.

<Tabs groupId="lang">

<TabItem value="bash" label="curl">

```bash
# $ROW_URL is storage.context from the launch
curl -X PUT "$ROW_URL" \
    -H "Authorization: Bearer $API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"weeks": 14, "modules_open": ["intro", "loops"]}'
```

</TabItem>

<TabItem value="python" label="Python">

```python
requests.put(
    launch["storage"]["context"],
    headers={"Authorization": f"Bearer {api_token}"},
    json={"weeks": 14, "modules_open": ["intro", "loops"]},
).raise_for_status()
```

</TabItem>

<TabItem value="javascript" label="Node">

```javascript
await fetch(
  launch.storage.context,
  {
    method: 'PUT',
    headers: {
      Authorization: `Bearer ${apiToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ weeks: 14, modules_open: ['intro', 'loops'] }),
  }
)
```

</TabItem>

</Tabs>

<Warning>
`PUT` overwrites everything in the row. If two parts of your tool store different keys in the same row, use `PATCH` so one write can't clobber the other's keys.
</Warning>

## PATCH: apply a JSON Patch

```
PATCH <row URL>
Content-Type: application/json
```

The body wraps an [RFC 6902 JSON Patch](https://datatracker.ietf.org/doc/html/rfc6902) in a `patch` key. Paths are relative to your object's root (`/answers/q2`, with no extra prefix). Returns **`204 No Content`**.

```json
{
  "patch": [
    { "op": "add",     "path": "/answers/q2", "value": "C" },
    { "op": "replace", "path": "/attempts",   "value": 2 },
    { "op": "remove",  "path": "/draft" }
  ]
}
```

<Tabs groupId="lang">

<TabItem value="bash" label="curl">

```bash
# $ROW_URL is storage.member_location from the launch
curl -X PATCH "$ROW_URL" \
    -H "Authorization: Bearer $API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"patch": [{"op": "add", "path": "/answers/q2", "value": "C"}]}'
```

</TabItem>

<TabItem value="python" label="Python">

```python
requests.patch(
    launch["storage"]["member_location"],
    headers={"Authorization": f"Bearer {api_token}"},
    json={"patch": [{"op": "add", "path": "/answers/q2", "value": "C"}]},
).raise_for_status()
```

</TabItem>

<TabItem value="javascript" label="Node">

```javascript
await fetch(
  launch.storage.member_location,
  {
    method: 'PATCH',
    headers: {
      Authorization: `Bearer ${apiToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      patch: [{ op: 'add', path: '/answers/q2', value: 'C' }],
    }),
  }
)
```

</TabItem>

</Tabs>

The patch engine is **tolerant of missing intermediate paths**: an `add` to `/answers/q2` works even if `answers` doesn't exist yet — the intermediate object is created for you. Patches apply atomically under a row lock, so concurrent patches to different keys both land.

## Files

Each row also keeps **files** — data too large for the JSON object, or not JSON at all: a submitted PDF, a photo, a recording. The launch's `files` claim carries one URL per row, beside `storage`, with the same four keys and the same rule: call it as given. Who may read and write a row's files is the same as for its data.

A file has a **key** your tool chooses: 1 to 128 characters, letters, digits, `.`, `_`, and `-`, starting with a letter or digit. Writing to a key that holds a file replaces it.

| Method | URL | Effect |
| --- | --- | --- |
| `GET` | `<files URL>` | List the row's files: `[{ key, size, modified }]`, `modified` in milliseconds since the epoch. |
| `GET` | `<files URL>/<key>` | One file: `{ key, size, modified, content_type, url, expires }`. `url` downloads it until `expires` (milliseconds since the epoch, a few minutes away). `404` when no file has the key. |
| `PUT` | `<files URL>/<key>` | Ask to store a file. The body describes it, and the response is a signed upload form, below. |
| `DELETE` | `<files URL>/<key>` | Remove the file. `204`, also when there was none. |

### Uploading a file

The bytes never pass through the Voshi API. A `PUT` declares the file and answers with a signed form; your tool then posts the file straight to storage.

<ParamField body="size" type="integer" required>
  The file's size in bytes, at most **25 MB**. Storage refuses an upload that does not match.
</ParamField>
<ParamField body="mimetype" type="string">
  The file's type. Guessed from `filename` (or the key) when empty.
</ParamField>
<ParamField body="filename" type="string">
  The name a download is saved as. The key when empty.
</ParamField>
<ParamField body="attachment" type="boolean" default="false">
  Make downloads save the file rather than show it in the browser.
</ParamField>

The response is `{ url, fields }`. `POST` a `multipart/form-data` request to `url` carrying every entry of `fields` **first** and the file **last**, in a field named `file`:

<Tabs groupId="lang">

<TabItem value="python" label="Python">

```python
import requests

files_url = launch["files"]["member_location"]
signed = requests.put(
    f"{files_url}/essay.pdf",
    headers={"Authorization": f"Bearer {api_token}"},
    json={"size": len(pdf_bytes), "mimetype": "application/pdf", "filename": "essay.pdf"},
)
signed.raise_for_status()
form = signed.json()
requests.post(form["url"], data=form["fields"], files={"file": pdf_bytes}).raise_for_status()
```

</TabItem>

<TabItem value="javascript" label="Node">

```javascript
const filesUrl = launch.files.member_location
const signed = await fetch(`${filesUrl}/essay.pdf`, {
  method: 'PUT',
  headers: { Authorization: `Bearer ${apiToken}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ size: pdf.size, mimetype: 'application/pdf', filename: 'essay.pdf' }),
})
const form = await signed.json()
const body = new FormData()
for (const [name, value] of Object.entries(form.fields)) body.append(name, value)
body.append('file', pdf)                       // the file last
await fetch(form.url, { method: 'POST', body })
```

</TabItem>

</Tabs>

The `PUT` checks the row's quota before signing: **100 files and 100 MB per row**. A `PUT` that would exceed either is refused with `422`.

## Errors

| Status | Cause |
| --- | --- |
| `401` | Missing or expired bearer token — take a fresh `api.token` from a new launch. |
| `403` | The token's user isn't allowed on this row — e.g. a student writing the shared `context` or `location` row, one student's token used on another student's `member` row, or a user who isn't a member of the row's course. |
| `404` | The row URL doesn't exist, or the row doesn't belong to your tool. |
| `422` | Malformed body — e.g. a `PATCH` without the `patch` wrapper, or an invalid patch operation. Also how a `context` or `location` row answers while its level is still [unprovisioned](https://myeducator-llc.github.io/voshi-docs/advanced/app-data/overview#the-course-rows-open-at-provisioning). |

Error responses use the standard [error envelope](https://myeducator-llc.github.io/voshi-docs/reference/errors).

---

# Managing your tool

> Where your tool's configuration lives, and what your API key can and cannot do.

Source: https://myeducator-llc.github.io/voshi-docs/advanced/managing-your-app

Your tool's configuration — its name, its three URLs, its description and logo — lives in the dashboard, on your tool's **Settings** tab. That is the only place to change it.

<Warning>
**There is no longer a management API.** `GET`/`PATCH /ltiaas/v1/apps/me`, the `apps/me/locations` endpoints, and `POST /apps/me/rotate-key` have all been removed, along with the API key's power to call them. Automation pointed at those paths gets a `404`. See the [changelog](https://myeducator-llc.github.io/voshi-docs/reference/changelog).
</Warning>

## What your API key does

One thing: it lets your **server** [publish a grade](https://myeducator-llc.github.io/voshi-docs/advanced/grades/grade-passback#as-your-tools-server-with-your-api-key) when no launch session is available.

It is the tool's runtime credential, not the builder's, and it is deliberately confined to that. It cannot read your tool, change your tool, add or remove locations, rotate itself, or reach anything else — so a leaked key exposes grade submission in courses your tool is already placed in, and nothing more.

Everything else is done as **you**, signed into the dashboard.

## Changing your configuration

| What | Where |
| --- | --- |
| Name, description, logo | **Settings** tab |
| Callback, Provisioning, and Locations URLs | **Settings** tab |
| Rotating your API key | **Settings** tab — see [rotating your key](https://myeducator-llc.github.io/voshi-docs/advanced/overview#rotating-or-replacing-your-api-key) |
| Tool status (`draft` → `active`) | Platform team only — see [tool status](https://myeducator-llc.github.io/voshi-docs/advanced/overview#tool-status) |
| Team members | Platform team only — see [team members](https://myeducator-llc.github.io/voshi-docs/building/dashboard#team-members) |

Changes take effect immediately, including for placements instructors have already made.

<Note>
**Deployment automation.** Repointing your callback URL as part of a release used to be a `PATCH` away. It isn't now — change it on the **Settings** tab. If that's a real obstacle to how you ship, tell the MyEducator team; the need is worth hearing about.
</Note>

## Locations are not configured here

Voshi asks your tool for its destinations at placement time, so your catalog lives in your tool and there is nothing to keep in sync. Build a [locations endpoint](https://myeducator-llc.github.io/voshi-docs/advanced/locations-endpoint).

For a self-hosted tool the dashboard's **Locations** tab is **read-only**: it lists the locations Voshi has recorded so far, which is the ones instructors have actually placed. A location appears there the first time someone places it, not when you start offering it. It's a record of what has been seen, not the list instructors choose from.

---

# Errors

> The error envelope and status codes used across the Voshi APIs.

Source: https://myeducator-llc.github.io/voshi-docs/reference/errors

<Note>
**Building a hosted tool?** The Voshi API client turns every one of these into a thrown error with a name that says what happened — see [Errors](https://myeducator-llc.github.io/voshi-docs/api/errors) in the API section. This page is the HTTP contract behind it, for self-hosted tools calling the REST APIs directly.
</Note>

All Voshi API errors share one JSON envelope:

```json
{
  "id": "Ie4rR0r1d",
  "api": "api",
  "time": "2026-07-27T18:10:00+00:00",
  "error": "ValidationError",
  "message": "score must be between 0 and 1",
  "details": {}
}
```

<ResponseField name="id" type="string">
  A unique ID for this error occurrence. Include it when contacting support — it lets the Voshi team find the corresponding server-side report.
</ResponseField>

<ResponseField name="error" type="string">
  The error class, matching the status code below.
</ResponseField>

<ResponseField name="message" type="string">
  A human-readable description of what went wrong.
</ResponseField>

<ResponseField name="details" type="object">
  Structured extras, when the error has them.
</ResponseField>

<Note>
The response format is content-negotiated on the `Accept` header: API clients sending `Accept: application/json` (or no preference) get the JSON envelope; a browser gets an HTML error page carrying the same report ID.
</Note>

## Status codes

| Status | Error | When |
| --- | --- | --- |
| `401` | `AuthenticationError` | Missing, malformed, invalid, or expired credentials — a bad or rotated API key, a suspended tool, an API key on a route that only takes a user's own token, or a stale `api.token`. |
| `403` | `NotAuthorized` | Authenticated, but not allowed — e.g. an [storage](https://myeducator-llc.github.io/voshi-docs/advanced/app-data/overview#who-can-access-what) token used on another user's row, or an [API key](https://myeducator-llc.github.io/voshi-docs/advanced/grades/grade-passback#as-your-tools-server-with-your-api-key) used for another tool or for a course your tool isn't placed in. |
| `404` | `Http404` | The resource doesn't exist — **or belongs to another tool**. Voshi deliberately doesn't distinguish these, so other tools' data can't be probed. |
| `422` | `ValidationError` | The request was understood but a value is invalid. The `message` says which — see the per-endpoint error tables. Also how an [unprovisioned](https://myeducator-llc.github.io/voshi-docs/advanced/provisioning/overview#the-course-and-location-rows-open-at-provisioning) course or location row answers. |
| `500` | `ApiException` | Something failed on Voshi's side. Retry, and report the error `id` if it persists. |

<Warning>
Validation failures return **`422`**, not `400`. If your HTTP client only treats `400` as a validation error, widen the check.
</Warning>

## Provisioning errors

Two `422`s come from the [provisioning](https://myeducator-llc.github.io/voshi-docs/advanced/provisioning/overview) flow:

| Message | Cause |
| --- | --- |
| `App … has not been provisioned for Context …` | A `GET`/`PUT`/`PATCH` on a `context` or `location` [storage row](https://myeducator-llc.github.io/voshi-docs/advanced/app-data/overview#the-course-rows-open-at-provisioning) whose level isn't provisioned yet. |
| `App … must be provisioned before its locations are provisioned` | A `PUT` to a `provision.location` URL while that course's `provision.context` is still unfinished. Call the course URL first. |

## Errors that don't reach your code

Launch-time failures (draft tool, broken callback URL, a course that isn't provisioned yet) happen before your endpoint is called: the user sees a Voshi page with a report ID, and your tool never hears about the launch. See [errors on Voshi's side](https://myeducator-llc.github.io/voshi-docs/advanced/launch/receiving-launches#errors-on-voshis-side).

Deep-link failures work the same way, in the other direction: if your [locations endpoint](https://myeducator-llc.github.io/voshi-docs/advanced/locations-endpoint#when-this-endpoint-fails) times out, refuses the request, or returns something Voshi can't read, the instructor sees the error and your tool is told nothing.

## A rejected grade is not an HTTP error

A score the LMS refuses still returns **`200`**: the call was valid and was made, and the refusal is reported in the attempt itself as `status: "failed"`, with the reason in `data.error`. **Check `status` on every submission** — a tool that only checks the HTTP code will think a rejected score reached the gradebook. To retry, post again; each submission is its own attempt. See [failed attempts vs. errors](https://myeducator-llc.github.io/voshi-docs/advanced/grades/api-reference#failed-attempts-vs-errors).

---

# Changelog

> Contract changes, what you have to do about them, and where the previous docs live.

Source: https://myeducator-llc.github.io/voshi-docs/reference/changelog

Changes to what Voshi sends your tool or expects from it, newest first. Each entry says what you have to change to keep working.

The docs as they stood before each change stay published — pick the date from the version dropdown at the top of any page, or follow the links below.

## 2026-10-05 — Hosted tools are the main path, and rows keep files

**No action required for a self-hosted tool.** Nothing it receives or must send has changed, and one claim was added. No snapshot was cut.

### The docs are organized around hosted tools

Most tools are built in the dashboard's AI Builder, or uploaded as a folder of browser code, and run on Voshi's hosting. These docs now describe that path first: [how a hosted tool works](https://myeducator-llc.github.io/voshi-docs/building/how-it-works), the [dashboard](https://myeducator-llc.github.io/voshi-docs/building/dashboard), a tool's [files](https://myeducator-llc.github.io/voshi-docs/building/files) and `manifest.json`, [locations](https://myeducator-llc.github.io/voshi-docs/building/locations), the [Sandbox](https://myeducator-llc.github.io/voshi-docs/building/sandbox), [versions](https://myeducator-llc.github.io/voshi-docs/building/versions), and the [Voshi API](https://myeducator-llc.github.io/voshi-docs/api/overview) a hosted tool is handed — launch details, [storage](https://myeducator-llc.github.io/voshi-docs/api/storage), [files](https://myeducator-llc.github.io/voshi-docs/api/files), [grades](https://myeducator-llc.github.io/voshi-docs/api/grades), [assets](https://myeducator-llc.github.io/voshi-docs/api/assets), and [errors](https://myeducator-llc.github.io/voshi-docs/api/errors).

Everything about running your own server — the three endpoints, the signed `launch_data` JWT, provisioning, the locations endpoint, and the REST APIs for storage and grades — is unchanged and now lives under [Advanced: your own server](https://myeducator-llc.github.io/voshi-docs/advanced/overview). Every page moved, so update any bookmarks; the content is the same.

The docs also now say **tool** where they used to say *app*. The API is unchanged: the `app` claim, the `/apps/…` URL segments, and the `app` section of `manifest.json` keep their names.

### New claim: `files`

Every launch (and provision request) now carries a `files` object beside `storage`, with the same four keys. Each is the URL of the **files** kept beside that storage row — for data too large for the row's JSON object or not JSON at all. `GET` it to list the row's files; `<url>/<key>` reads, stores, or removes one. Who may read and write a row's files follows the row's own rules.

- See the [`files` claim](https://myeducator-llc.github.io/voshi-docs/advanced/launch/launch-claims#claims) and the [file operations](https://myeducator-llc.github.io/voshi-docs/advanced/app-data/api-reference#files) in the Storage API reference.
- A hosted tool reaches the same files as `api.storage.<scope>.files` — see [Files](https://myeducator-llc.github.io/voshi-docs/api/files).

### Storage rows have a documented size limit

The JSON object of a `member` or `member_location` row is limited to **512 KB**, and of a `context` or `location` row to **1 MB**, as compact JSON; a larger write is refused with `422`. Earlier pages said no fixed limit was enforced. Nothing changed on the server; the limit is now stated. Larger data belongs in the row's files.

### The Sandbox has a gradebook

The dashboard's **Test** tab is now the **Sandbox**, and its trial course has a gradebook of its own: an `assessment` placed there through the picker arrives with a `grade.submit` URL, and scores you publish show on the Sandbox's **Grades** tab. Earlier pages said grade passback could not be tested there. The **Launch Logs** and **Grade Logs** tabs are now **Launches** and **Grades**.

## 2026-09-21 — Grade passback, and the end of the management API

**Action required.** Grade passback is a different call now, one launch claim was replaced, and every `/apps/me` endpoint is gone. The contract before this change is archived at [2026-08-25](/2026-08-25).

### Grades: post to the URL the launch gives you

`POST /ltiaas/v1/grades` **has been removed.** Grades are no longer keyed on a launch at all — they are keyed on the student and the location, which is what a gradebook column actually belongs to.

- Every launch now carries a **`grade.submit`** URL. `POST` your score there. It's ready to call, like the `storage` URLs, and it already names the course, the student, and the location — the body is just the score.
- The body loses `launch_id`; `score`, `max_score`, `comment`, `activity_progress`, and `grading_progress` are unchanged.
- **Every submission is an attempt, and nothing is overwritten.** There is no longer one grade per launch that resubmission updates: each `POST` publishes to the LMS and records a new attempt. To regrade or retry, post again.
- The response is that attempt. `sync_status` / `sync_error` / `synced_at` / `grade_id` / `launch_id` are gone; check **`status`** (`success` or `failed`) and read `data.error` when it failed. A refused score is still `200`.
- `GET /ltiaas/v1/grades/{grade_id}` is removed with no replacement. The response to each `POST` is the record — log what you need. Your tool's history is in the dashboard under **Grade Logs**.
- **Grading someone other than the launching user** is now first-class: swap the member segment of a `/contexts/…` grade URL for another student's `user.member`. An instructor grading a roster, or a job scoring work offline, no longer needs a launch for each student — and a score can be published for a student who never opened the activity.

See [Grade passback](https://myeducator-llc.github.io/voshi-docs/advanced/grades/grade-passback) and the [API reference](https://myeducator-llc.github.io/voshi-docs/advanced/grades/api-reference).

### Changed claim

| Before | Now | What to do |
| --- | --- | --- |
| `grade_passback` (boolean) | `grade.submit` (URL or `null`) | Replace the boolean check with a null check, and post the score to the URL. `null` in exactly the cases the boolean was `false`. |

`launch_id` is still sent, but nothing in the API is keyed on it any more. You no longer need to store it to grade later — store `grade.submit` instead.

### The management API is gone

`GET`/`PATCH /ltiaas/v1/apps/me`, the four `apps/me/locations` endpoints, and `POST /apps/me/rotate-key` have all been **removed**, and your API key no longer authorizes anything but grade submission. Requests to those paths now `404`.

Change your tool's name, URLs, description, and logo on the dashboard's **Settings** tab, and rotate your key there too. If deployment automation depended on `PATCH /apps/me`, it needs changing — and the MyEducator team would like to hear about it. See [Managing your tool](https://myeducator-llc.github.io/voshi-docs/advanced/managing-your-app).

### Registration asks where your tool runs

New tools choose **Voshi Hosted** or **Self Hosted** at registration, and the choice is permanent. Self-hosted is what these docs describe: your own server, your three URLs, your API key. A hosted tool is built in the dashboard and gets no API key, since it has no server to keep one on. `callback_url` is no longer accepted in the registration call itself — set it on the **Settings** tab afterwards, like the other two URLs.

### The Test tab now runs real launches

The dashboard's **Test** tab used to send fabricated claims carrying `test: true` and record nothing. It now launches your tool for real, in a private trial course of its own: your locations endpoint is asked through the ordinary content picker, your provisioning endpoint is called and waited on, real storage rows are created, and your callback URL gets a properly signed launch.

- **If your code branches on a `test` claim, that branch is now dead** — nothing sends one.
- Trial launches have no gradebook, so they arrive with `grade.submit: null`. Grade passback is tested from a real course.
- A test link can be **Reset**, which discards everything your tool stored at it so the next launch provisions again.

See [Testing your tool](https://myeducator-llc.github.io/voshi-docs/advanced/overview#testing-your-tool).

### Migration checklist

1. Store `grade.submit` from each launch; stop storing `launch_id` for grading.
2. Replace `grade_passback` boolean checks with a null check on `grade.submit`.
3. Repoint grade submissions from `POST /ltiaas/v1/grades` to that URL, and drop `launch_id` from the body.
4. Check **`status`** on the response instead of `sync_status`; drop any polling of `GET /grades/{grade_id}`.
5. Replace resubmit-to-update logic with plain resubmission — it is a new attempt, and that is correct.
6. Remove any calls to `/apps/me` endpoints; do that configuration in the dashboard.
7. Delete any `test: true` branch in your locations or launch handling.

## 2026-09-04 — Messages and grouped locations

**No action required.** Both additions are optional, and a tool that answers the locations request exactly as it does today keeps working unchanged. No snapshot was cut: nothing about the old contract stopped being true.

### Your locations response can carry a message

Send a `message` alongside (or instead of) your locations and Voshi shows it to the instructor above the picker. It is the answer to the empty picker: when you offer nothing, you are the only party who knows why — an email that matches no account, an institution that has adopted nothing — and until now there was no way to say so.

- Shown as **plain text**; markup is stripped, and it is truncated at 2000 characters.
- Valid on its own: `{"message": "…"}` with no locations is a complete answer.
- See [`message`](https://myeducator-llc.github.io/voshi-docs/advanced/locations-endpoint#message--explaining-what-they-are-looking-at).

### Your locations can be grouped

A new `grouped_locations` key arranges locations into named, collapsible sections, nested up to **5 levels**. Instructors see them collapsed, open what they want, and can take a whole group at once or pick from several groups in one placement.

- A group needs a `label`, and it has to be a real one: an empty label, or one that is only whitespace or markup, is refused. It may also carry `description`, `locations`, and its own `grouped_locations` — the same key again, since a group holds locations the way the response itself does.
- Grouping is **presentation only** — it is not part of an extid, is not stored on the location, and never appears in a launch, so you can reorganize freely without disturbing content that is already placed.
- Locations sent at the top level are shown above the groups, uncollapsed.
- See [`grouped_locations`](https://myeducator-llc.github.io/voshi-docs/advanced/locations-endpoint#grouped_locations--arranging-a-large-catalog).

### One thing that is now refused

A locations response naming **none** of `locations`, `grouped_locations`, or `message` is rejected as an invalid structure. Previously `locations` was required, so a response without it was already refused; this only changes the wording of the error. To answer "nothing right now", send a `message`, an empty `locations` object, or both.

## 2026-09-02 — Documentation corrections

**No contract change.** Nothing about what Voshi sends or accepts changed on this date; these are places where the docs described the platform wrongly. No snapshot was cut, because there is no earlier contract to strand anyone on. Check each item against your integration.

### Claims

- **`location.params` does not exist and never did on this contract.** Earlier pages showed a `params` object on the launch and provision `location` claim, documented it as a per-location field on your locations response, and suggested a "few parameterized destinations" strategy built on it. Voshi sends no such object and stores no such field. If you wrote code reading `location["params"]`, it has been failing or silently reading nothing — move that configuration into the extid or your own database. See [There are no per-location params](https://myeducator-llc.github.io/voshi-docs/advanced/locations#there-are-no-per-location-params).
- **Launches to course staff carry name and email.** `user.given_name`, `user.family_name`, `user.full_name`, and `user.email` are populated when `groups` contains `manager`, `instructor`, or `assistant`, and are `null` otherwise. Earlier pages said flatly that no PII is forwarded. Student launches are unchanged — still no PII. See [`user`](https://myeducator-llc.github.io/voshi-docs/advanced/launch/launch-claims#claims).
- **A provision request does carry `course`.** It was listed among the claims a provision request does not have. It has always been sent, in the same shape as a launch's.

### Tool data permissions

The [who-can-access-what](https://myeducator-llc.github.io/voshi-docs/advanced/app-data/overview#who-can-access-what) rules were wrong in both directions:

- **Students cannot write the shared `context` and `location` rows** — they have read access only, and a write returns `403`. Earlier pages warned that students *could* overwrite them.
- **Course staff can read and write any member's `member` and `member_location` rows** in their course. Earlier pages said only the user themself could reach their own rows.
- **Tool builders get no automatic access to any row.** Being a member of the tool in the dashboard grants nothing; a builder has to be enrolled in the course to read data there.

### APIs

- **`POST /grades` accepts `max_score`**, which rewrites the gradebook column's points possible before publishing the score, and returns it on the grade object. Undocumented until now — see [the request body](https://myeducator-llc.github.io/voshi-docs/advanced/grades/api-reference#request-body).
- **`provision_url` and `locations_url` are readable and writable** through `GET`/`PATCH /apps/me`, and settable in the dashboard. *(The `/apps/me` endpoints were removed on 2026-09-21; the dashboard tab is now called **Settings**.)*
- **`POST /apps/me/rotate-key`** issues a new API key and invalidates the old one. *(Removed on 2026-09-21 — rotate from the dashboard instead; see [rotating your key](https://myeducator-llc.github.io/voshi-docs/advanced/overview#rotating-or-replacing-your-api-key).)*
- **The legacy location object** is `{id, extid, type, label}`, and `extid` is required when creating one. Earlier pages showed `is_default`, `order`, and `params` instead.

### Dashboard

The tool detail tabs are **Overview, Profile, Locations, Test, Launches, Grade Logs**. Pages referring to a **Settings** tab meant Profile, and there is no **Members** tab — ask the MyEducator team to change who manages a tool. *(Renamed since: the tabs are now **Overview, Settings, Locations, Pricing, Test, Launch Logs, Grade Logs**.)*

## 2026-08-25 — Provisioning and app-served locations

**Action required.** Your tool now builds **three** endpoints instead of one, and one claim was replaced. The contract before this change is archived at [2026-08-19](/2026-08-19).

### New: your tool serves its own locations

Locations are no longer defined in the dashboard. Voshi asks your tool for its destinations whenever an instructor is placing content, and you identify each one with an external ID of your choosing.

- Register a **Locations URL** and answer it with `{"locations": {"<extid>": {…}}}` — see [Serving your locations](https://myeducator-llc.github.io/voshi-docs/advanced/locations-endpoint).
- **A tool with no Locations URL cannot be placed in a course.** This is the change most likely to stop a working integration.
- Launches now carry both `location.extid` (yours) and `location.id` (Voshi's). Switch on `extid`.
- The dashboard's Locations editor and the `apps/me/locations` API still exist but no longer drive what instructors see.

### New: provisioning

Before the first launch of a course reaches you, Voshi asks your tool to set that course up.

- Register a **Provision URL**, answer `204` promptly, then `PUT` each URL in the `provision` claim when that level is ready — see [How provisioning works](https://myeducator-llc.github.io/voshi-docs/advanced/provisioning/overview).
- The `context` and `location` [storage rows](https://myeducator-llc.github.io/voshi-docs/advanced/app-data/overview#the-course-rows-open-at-provisioning) now answer `422 … has not been provisioned` until you finish. `member` and `member_location` are unaffected.
- **Voshi no longer copies course data into a copied course.** A provision request for a copied course hands you the previous course's row URLs (`storage.parent_context`, `storage.parent_location`) and you carry forward what matters — see [Copied courses](https://myeducator-llc.github.io/voshi-docs/advanced/provisioning/receiving-provision-requests#copied-courses).

### Changed claims

| Before | Now | What to do |
| --- | --- | --- |
| `user.role` (`student` / `instructor` / `admin`) | `user.groups` (a list) and `user.member` | Replace role comparisons with membership checks (`"instructor" in groups`). Key enrollment records on `user.member`. See [`user`](https://myeducator-llc.github.io/voshi-docs/advanced/launch/launch-claims#claims). |
| `resource_link_id` | `resource_link` | Rename. Same meaning. |
| `organization.id` | `organization.deployment` | Rename — `deployment` always held the same value. |
| — | `context` | New: the course ID on its own, matching the storage URLs and used by provisioning. `course` still carries the display text. |
| — | `location.extid` | New: your own ID for the launched destination. |

### Corrections to these docs

Behavior that didn't change, but that earlier pages described wrongly:

- **`iss` is always Voshi** (`https://api.link.voshi.com`), not the school's LMS. If you configured your JWT library to expect the LMS issuer, it was never matching what we send.
- **Storage URLs** are on `api.link.voshi.com`. Examples showed `link.voshi.com`.
- **A launch's `location` values are the copy Voshi captured when the placement was made**, not your current list. Earlier pages said edits applied immediately to existing placements. Drive your tool off `location.extid` and your own data.

### Migration checklist

1. Replace `user.role` reads with `user.groups` membership checks; store groups against `user.member`.
2. Rename `resource_link_id` → `resource_link` and `organization.id` → `organization.deployment`.
3. Build and register your **Locations URL** — without it your tool can't be placed.
4. Build and register your **Provision URL**, and call the provision URLs when setup finishes.
5. If you relied on Voshi copying course data across terms, move that into your provisioning handler.
6. If you pinned `iss` to the LMS issuer, pin it to `https://api.link.voshi.com` instead.