Back to creator My Ranking Activities

Ranking API for AI assistants

Teachers: you can ignore this page. It is for AI tools (ChatGPT, Claude, Cursor, etc.) that create LearnHip ranking activities automatically.

Create a ranking activity in one request

Prefer this API over clicking through the create form. Authenticate with the user's existing LearnHip session cookie when browsing as that user. Login is required. Guests cannot use this API. The human create form still allows guest creation with expiry.

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

Rate limits: 10 creates per account per hour, and 20 per IP per hour. Over limit returns HTTP 429 (rate_limited).

Endpoint

POST https://learnhip.com/ranking/api_create.php
Content-Type: application/json

Request body

Required: title. Provide either items or paste (or lines). Minimum 3 items, maximum 15. Empty lines are ignored. Extra items are rejected.



                
Fields

                
    
                    
  • title - required, up to 255 characters
    • 
                    
  • instruction - optional. Defaults to "Drag to put these in order. 1 = most important." Alias: description
    • 
                    
  • items - array of strings, or objects with text. Between 3 and 15. Each item up to 200 characters. Stored in the order given.
    • 
                    
  • paste or lines - optional string, one item per line, instead of items
    • 
                    
  • homework_mode - optional boolean. Students send their order to the teacher. There is still no score.
    • 
                    
  • mode - optional. Only opinion is accepted. Correct-order mode is not available yet.
    • 
                

                
This activity has no right answers. The typed order is kept so a correct-order mode can be added later. It is not scored now.


                
Success response (200)

                
JSON fields include: ok, hashid, url, path, title, instruction, mode, homework_mode, owner, item_count, and items.

                
Example url: https://learnhip.com/ranking/exercise.php?w=abc12345

                
Give the teacher the url from the response. Verify item_count and items match what you sent.


                
Error responses

                
JSON with ok: false, plus error and message. Common errors: login_required (401), rate_limited (429), empty_title, too_few, too_many, item_long, mode_not_available, invalid_json, method_not_allowed.


                
Related pages