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 yet, start there. It defines locations, extids, and placements, and explains why the extid you choose is the most consequential decision you make.

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.
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. The shape is the same one a self-hosted tool serves, so one definition of a location serves both:

{
  "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. 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.

Handling locations in your code

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

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.

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.