{"$schema":"https://json-schema.org/draft/2020-12/schema","name":"Scavenge AI Hunt Creation API","version":"1.1.0","purpose":"Create an immediately playable, unlisted scavenger hunt when a user asks an AI assistant to make one.","humanInstructions":"https://scavenge.rs/ai","openApiSpec":"https://scavenge.rs/.well-known/scavenge-ai-hunt.openapi.json","chatgptPluginManifest":"https://scavenge.rs/.well-known/ai-plugin.json","getCreateEndpoint":"https://scavenge.rs/api/ai/hunts/create?payload=<url-encoded JSON>","endpoint":"https://scavenge.rs/api/ai/hunts","documentation":"https://scavenge.rs/.well-known/scavenge-ai-hunt.json","method":"POST","successStatus":201,"contentType":"application/json","authentication":{"required":false,"pluginRequired":false,"chatgptCustomGptRequired":false,"explanation":"No plugin, OAuth, API key, or user login is required to create a hunt. This POST is the create-hunt action. ChatGPT can import the OpenAPI spec with authentication None."},"rateLimit":{"production":{"requests":10,"windowMinutes":15,"key":"source IP address"},"retryBehavior":"If the API returns HTTP 429, do not retry immediately. Tell the user to wait and preserve the request body."},"instructionsForAI":"You do not need a ChatGPT plugin, Custom GPT, OAuth, API key, or user login. If you can POST JSON, POST to the endpoint. If you can only GET, URL-encode one requestSchema JSON object and GET getCreateEndpoint. ChatGPT should use GET. Use this API only after the user asks you to create a scavenger hunt. Gather missing audience, setting, theme, and location details; generate safe clues; then submit one JSON object matching requestSchema. Do not invent success. After a successful response, give hunt.playUrl as the primary player link and tell them they must create a free Scavenge account. Give hunt.claimUrl privately to the requester. Never share claimUrl with other players. If validation fails, correct only the fields listed in errors and retry once. Never send payment or booking data.","authoringGuidance":["Prefer 5 to 10 clues for a complete hunt; the hard range is 2 to 20.","Use guided hunts unless the user explicitly asks for points or a leaderboard.","Keep every real-world stop in a public, lawful, and safely accessible place.","Never require trespassing, unsafe road crossings, purchases, interaction with strangers, or entry into a private home.","For location-based hunts, provide a specific location and coordinates for each stop when known.","Use stable facts. Avoid changing quantities, current prices, temporary tenants, opening hours, and facts you cannot verify.","Make clue orders consecutive starting at 1 and do not repeat an order.","For multiple choice clues, correct_answers must contain option IDs exactly as written.","Use informational clues sparingly for navigation or safety context; they require no player submission.","Do not put secrets, personal data, access codes, or private addresses in hunt content."],"defaults":{"huntType":"guided","isPublic":false,"showInUserProfile":false,"requirePayment":false,"bookingEnabled":false,"allowAnonymousPlay":false,"autoApproveSubmissions":true,"currency":"USD","clueAutoApproval":"Answer and photo submissions default to automatic approval for AI-created hunts."},"challengeTypes":{"text":{"description":"The player submits a short factual answer.","useWhen":"There is one stable answer that can be checked case-insensitively.","requiredFields":["text","answer"],"optionalFields":["hint","location","latitude","longitude","points"],"example":{"order":1,"text":"What year is carved above the main entrance?","answer":"1929","challenge_type":"text","hint":"Look above the center doorway."}},"photo":{"description":"The player submits a photo as proof of completing the challenge.","useWhen":"The task is visual, creative, or has no single written answer.","requiredFields":["text"],"optionalFields":["hint","location","latitude","longitude","points"],"example":{"order":2,"text":"Take a team photo beside the fountain.","challenge_type":"photo","location":"Central Plaza Fountain"}},"both":{"description":"The player must submit both a factual text answer and a photo.","useWhen":"A location-specific fact and visual proof are both useful.","requiredFields":["text","answer"],"optionalFields":["hint","location","latitude","longitude","points"],"example":{"order":3,"text":"Name the animal on the statue and photograph your team copying its pose.","answer":"Lion","challenge_type":"both"}},"opinion_text":{"description":"The player submits an open-ended written response with no wrong answer.","useWhen":"The prompt asks for a preference, observation, or creative response.","requiredFields":["text"],"optionalFields":["hint","location","latitude","longitude","points"],"example":{"order":4,"text":"Which detail here is your favorite, and why?","challenge_type":"opinion_text"}},"opinion_text_photo":{"description":"The player submits an open-ended response and a related photo.","useWhen":"The prompt combines reflection or creativity with visual proof.","requiredFields":["text"],"optionalFields":["hint","location","latitude","longitude","points"],"example":{"order":5,"text":"Photograph the most interesting pattern and explain what it reminds you of.","challenge_type":"opinion_text_photo"}},"multiple_choice_text":{"description":"The player selects one or more answers from a fixed list.","useWhen":"A factual answer is best presented with plausible choices.","requiredFields":["text","multiple_choice_options","correct_answers"],"optionalFields":["hint","location","latitude","longitude","allow_multiple_selections","points"],"example":{"order":6,"text":"Which material is the monument primarily made from?","challenge_type":"multiple_choice_text","multiple_choice_options":[{"id":"a","text":"Granite"},{"id":"b","text":"Wood"},{"id":"c","text":"Glass"}],"correct_answers":["a"],"allow_multiple_selections":false}},"multiple_choice_text_photo":{"description":"The player chooses from fixed answers and also submits a photo.","useWhen":"The answer should be structured and the visit should have visual proof.","requiredFields":["text","multiple_choice_options","correct_answers"],"optionalFields":["hint","location","latitude","longitude","allow_multiple_selections","points"],"example":{"order":7,"text":"Select the visible architectural style and take a photo of its best example.","challenge_type":"multiple_choice_text_photo","multiple_choice_options":[{"id":"a","text":"Art Deco"},{"id":"b","text":"Gothic"}],"correct_answers":["a"],"allow_multiple_selections":false}},"informational":{"description":"A story, direction, safety note, or transition that requires no submission.","useWhen":"Players need context or navigation between interactive clues.","requiredFields":["text"],"optionalFields":["location","latitude","longitude"],"example":{"order":8,"text":"Continue east along the public path to the rose garden.","challenge_type":"informational","location":"Rose Garden Path"}},"poll":{"description":"The player selects from choices with no correct or incorrect answer.","useWhen":"The group is voting on preferences or observations.","requiredFields":["text","multiple_choice_options"],"optionalFields":["location","latitude","longitude","allow_multiple_selections","points"],"example":{"order":9,"text":"Which nearby attraction should the group visit next?","challenge_type":"poll","multiple_choice_options":[{"id":"a","text":"The garden"},{"id":"b","text":"The gallery"}],"allow_multiple_selections":false}},"poll_photo":{"description":"The player votes in a poll and submits a related photo.","useWhen":"A preference vote should be paired with a visual keepsake.","requiredFields":["text","multiple_choice_options"],"optionalFields":["location","latitude","longitude","allow_multiple_selections","points"],"example":{"order":10,"text":"Vote for the best mural and photograph your choice.","challenge_type":"poll_photo","multiple_choice_options":[{"id":"a","text":"North wall mural"},{"id":"b","text":"Market alley mural"}],"allow_multiple_selections":false}}},"requestSchema":{"type":"object","additionalProperties":false,"required":["title","description","location","clues"],"properties":{"title":{"type":"string","minLength":3,"maxLength":100,"description":"A clear, inviting name for the hunt."},"description":{"type":"string","minLength":10,"maxLength":5000,"description":"Player-facing introduction with audience, approximate duration, and relevant safety or accessibility guidance."},"location":{"type":"string","minLength":2,"maxLength":200,"description":"General hunt area. Use Play Anywhere for hunts that do not depend on a real place."},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"startDate":{"type":"string","format":"date-time","description":"Optional ISO 8601 start time."},"endDate":{"type":"string","format":"date-time","description":"Optional ISO 8601 end time later than startDate."},"maxParticipants":{"type":"integer","minimum":1,"maximum":10000},"huntType":{"type":"string","enum":["guided","point_based"],"default":"guided"},"autoApproveSubmissions":{"type":"boolean","const":true,"default":true},"isPublic":{"type":"boolean","const":false,"default":false},"showInUserProfile":{"type":"boolean","const":false,"default":false},"requirePayment":{"type":"boolean","const":false,"default":false},"bookingEnabled":{"type":"boolean","const":false,"default":false},"pricePerPerson":{"type":"number","const":0,"default":0},"attribution":{"type":"string","minLength":1,"maxLength":100,"description":"Optional short AI service name, such as ChatGPT or Claude. Do not put the end user name here."},"clues":{"type":"array","minItems":2,"maxItems":20,"items":{"type":"object","additionalProperties":false,"required":["order","text","challenge_type"],"properties":{"order":{"type":"integer","minimum":1,"maximum":20,"description":"One-based display order. Use every integer exactly once."},"text":{"type":"string","minLength":3,"maxLength":2000,"description":"Player-facing question, task, direction, or information."},"hint":{"type":"string","minLength":1,"maxLength":1000,"description":"Optional help that does not reveal the answer outright."},"location":{"type":"string","minLength":1,"maxLength":200,"description":"Specific public landmark or area for this clue."},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"answer":{"type":"string","minLength":1,"maxLength":1000,"description":"Stable expected answer for text and both challenges."},"challenge_type":{"type":"string","enum":["text","photo","both","opinion_text","opinion_text_photo","multiple_choice_text","multiple_choice_text_photo","informational","poll","poll_photo"]},"auto_approve_answer":{"type":"boolean","description":"Defaults to true for answer-based AI-created clues."},"auto_approve_photo":{"type":"boolean","description":"Defaults to true for photo-based AI-created clues."},"multiple_choice_options":{"type":"array","minItems":2,"maxItems":10,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"required":["id","text"],"properties":{"id":{"type":"string","minLength":1,"maxLength":50},"text":{"type":"string","minLength":1,"maxLength":300}}}},"correct_answers":{"type":"array","minItems":1,"maxItems":10,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":50},"description":"Option IDs, not option text."},"allow_multiple_selections":{"type":"boolean","default":false},"points":{"type":"integer","minimum":1,"maximum":10000,"description":"Required on every clue when huntType is point_based."}},"allOf":[{"if":{"properties":{"challenge_type":{"enum":["text","both"]}}},"then":{"required":["answer"]}},{"if":{"properties":{"challenge_type":{"enum":["multiple_choice_text","multiple_choice_text_photo"]}}},"then":{"required":["multiple_choice_options","correct_answers"]}},{"if":{"properties":{"challenge_type":{"enum":["poll","poll_photo"]}}},"then":{"required":["multiple_choice_options"]}}]}}},"allOf":[{"if":{"properties":{"huntType":{"const":"point_based"}}},"then":{"properties":{"clues":{"items":{"allOf":[{"type":"object","additionalProperties":false,"required":["order","text","challenge_type"],"properties":{"order":{"type":"integer","minimum":1,"maximum":20,"description":"One-based display order. Use every integer exactly once."},"text":{"type":"string","minLength":3,"maxLength":2000,"description":"Player-facing question, task, direction, or information."},"hint":{"type":"string","minLength":1,"maxLength":1000,"description":"Optional help that does not reveal the answer outright."},"location":{"type":"string","minLength":1,"maxLength":200,"description":"Specific public landmark or area for this clue."},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"answer":{"type":"string","minLength":1,"maxLength":1000,"description":"Stable expected answer for text and both challenges."},"challenge_type":{"type":"string","enum":["text","photo","both","opinion_text","opinion_text_photo","multiple_choice_text","multiple_choice_text_photo","informational","poll","poll_photo"]},"auto_approve_answer":{"type":"boolean","description":"Defaults to true for answer-based AI-created clues."},"auto_approve_photo":{"type":"boolean","description":"Defaults to true for photo-based AI-created clues."},"multiple_choice_options":{"type":"array","minItems":2,"maxItems":10,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"required":["id","text"],"properties":{"id":{"type":"string","minLength":1,"maxLength":50},"text":{"type":"string","minLength":1,"maxLength":300}}}},"correct_answers":{"type":"array","minItems":1,"maxItems":10,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":50},"description":"Option IDs, not option text."},"allow_multiple_selections":{"type":"boolean","default":false},"points":{"type":"integer","minimum":1,"maximum":10000,"description":"Required on every clue when huntType is point_based."}},"allOf":[{"if":{"properties":{"challenge_type":{"enum":["text","both"]}}},"then":{"required":["answer"]}},{"if":{"properties":{"challenge_type":{"enum":["multiple_choice_text","multiple_choice_text_photo"]}}},"then":{"required":["multiple_choice_options","correct_answers"]}},{"if":{"properties":{"challenge_type":{"enum":["poll","poll_photo"]}}},"then":{"required":["multiple_choice_options"]}}]},{"required":["points"]}]}}}}}]},"responseSchema":{"type":"object","additionalProperties":false,"required":["success","message","hunt"],"properties":{"success":{"type":"boolean","const":true},"message":{"type":"string"},"hunt":{"type":"object","additionalProperties":false,"required":["id","title","joinCode","playUrl","detailsUrl","joinUrl","claimUrl","claimExpiresAt"],"properties":{"id":{"type":"integer"},"title":{"type":"string"},"joinCode":{"type":"string"},"playUrl":{"type":"string","format":"uri"},"detailsUrl":{"type":"string","format":"uri"},"joinUrl":{"type":"string","format":"uri"},"claimUrl":{"type":"string","format":"uri","description":"One-time link for the requester to become the hunt creator. The secret is in the URL fragment. Do not share this with players."},"claimExpiresAt":{"type":"string","format":"date-time","description":"ISO 8601 expiry for claimUrl. Typically seven days."}}}}},"errorSchema":{"type":"object","required":["success","message"],"properties":{"success":{"type":"boolean","const":false},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"object","required":["field","message"],"properties":{"field":{"type":"string"},"message":{"type":"string"}}}}},"statuses":{"400":"Request validation failed.","401":"Claim requires a signed-in Scavenge account.","409":"The hunt was already claimed or is no longer owned by the AI creator.","410":"The claim link has expired.","429":"The source IP exceeded the creation or claim limit.","500":"The validated hunt could not be created.","503":"AI hunt creation is currently disabled."}},"examples":[{"name":"Minimal three-clue guided hunt","request":{"title":"Backyard Nature Dash","description":"A 20-minute family hunt for a private backyard or local green space. Stay on safe paths and skip anything inaccessible.","location":"Play Anywhere","huntType":"guided","attribution":"Example AI","clues":[{"order":1,"text":"Find something naturally shaped like a circle and photograph it.","challenge_type":"photo"},{"order":2,"text":"Name one sound you can hear that is not made by a person.","challenge_type":"opinion_text"},{"order":3,"text":"Take a team photo beside the tallest plant you can safely reach.","challenge_type":"photo"}]}},{"name":"City walking hunt with coordinates","request":{"title":"Austin Downtown Art Walk","description":"A 60-minute walking hunt for adults in downtown Austin. Use public sidewalks, cross only at marked crossings, and skip any closed or inaccessible stop.","location":"Downtown Austin, Texas","latitude":30.2672,"longitude":-97.7431,"huntType":"guided","clues":[{"order":1,"text":"Photograph a public artwork that uses more than three colors.","challenge_type":"photo","location":"Downtown Austin public art","latitude":30.2672,"longitude":-97.7431},{"order":2,"text":"What material is most visible on the nearest historic facade?","challenge_type":"multiple_choice_text","multiple_choice_options":[{"id":"brick","text":"Brick"},{"id":"stone","text":"Stone"},{"id":"glass","text":"Glass"}],"correct_answers":["brick"],"allow_multiple_selections":false},{"order":3,"text":"End with a creative team photo that captures the city skyline.","challenge_type":"photo"}]}},{"name":"Play-anywhere point hunt","request":{"title":"Office Team Sprint","description":"A 30-minute indoor team-building hunt. Respect working areas, avoid private documents, and ask before photographing anyone.","location":"Play Anywhere","huntType":"point_based","clues":[{"order":1,"text":"Build the tallest free-standing structure from safe desk supplies.","challenge_type":"photo","points":20},{"order":2,"text":"Invent a five-word team motto.","challenge_type":"opinion_text","points":10},{"order":3,"text":"Photograph three objects that match your team color.","challenge_type":"photo","points":15}]}}],"curlExample":"curl -X POST https://scavenge.rs/api/ai/hunts \\\n+  -H \"Content-Type: application/json\" \\\n+  -d '{\"title\":\"Backyard Nature Dash\",\"description\":\"A safe 20-minute family hunt. Skip anything inaccessible.\",\"location\":\"Play Anywhere\",\"clues\":[{\"order\":1,\"text\":\"Photograph something naturally round.\",\"challenge_type\":\"photo\"},{\"order\":2,\"text\":\"Name a sound made by nature.\",\"challenge_type\":\"opinion_text\"}]}'"}