# LearnHip Ranking (ranking) - instructions for AI assistants

Prefer the JSON API over clicking the create form.

Opinion ranking only. Students put items in their own order. There is no correct answer and no score.
The item list is stored in the order you send it, so a correct-order mode can be added later. Do not send mode other than "opinion".

## Create activity
- Method: POST
- URL: https://learnhip.com/ranking/api_create.php
- Content-Type: application/json
- Rate limits: 10 creates/account/hour and 20 creates/IP/hour. Over limit: HTTP 429 error rate_limited.

## Auth
Logged-in LearnHip session required (no guests). Use the teacher's existing session cookie when acting in their browser.

Auth note: This is a same-origin request. Call it via fetch() from the page's own JavaScript context with credentials: 'same-origin' (or 'include') - the browser sends the existing session cookie automatically, the same way this site's own frontend calls its APIs. No need to read or set cookies manually.

fetch('/ranking/api_create.php', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  credentials: 'same-origin',
  body: JSON.stringify({title: '...', items: ['...', '...', '...']})
});

Use credentials: 'same-origin' rather than setting headers manually.

## Request
Required: title
Provide items[] (3 to 15 strings) OR paste (or lines), one item per line.
Optional: instruction, homework_mode (boolean). Alias for instruction: description.
Each item: 200 characters maximum. Empty lines are ignored.

Example:
{
  "title": "What makes a good weekend?",
  "instruction": "Drag to put these in order. 1 = most important.",
  "homework_mode": false,
  "items": ["Sleeping in", "Seeing friends", "Time outside", "A good meal"]
}

## Success response
ok, hashid, url, path, title, instruction, mode, homework_mode, owner, item_count, items
Return url to the teacher. Student page: /ranking/exercise.php?w={hashid}

## Human UI
https://learnhip.com/ranking/create.php

## Site index
https://learnhip.com/llms.txt

## Full docs
https://learnhip.com/ranking/api-docs.php