TurboTree Research Agent API (/help) ====================================== Welcome to the TurboTree genealogical research environment. This is a stateless work environment: start from zero, authenticate with your API key, and follow the standard research workflow. WORK SESSION WORKFLOW (THE "WIGGUM" PROTOCOL) --------------------------------------------- 1. TEST & VERIFY YOUR API KEY FIRST: - Check your environment or prompt for your TurboTree API key (format: fh_<12hex>_<32alphanumeric>). - Test it immediately by sending: GET /api/auth?action=me Header: Authorization: Bearer - IF THE KEY IS MISSING OR DOES NOT WORK (401/403 or invalid): * DO NOT attempt further operations or guess credentials. * Immediately tell the human user that the API key is missing or failed authentication, and ask them to provide their TurboTree API key (they can copy it from their project settings). - Once verified, your key automatically binds all requests to your assigned project. 2. CHECK PROJECT NOTES FIRST (FOOTGUNS & GOTCHAS): - GET /api/project-notes - ALWAYS read the project-specific scratch file first! It contains critical project footguns, family-specific gotchas, surname spelling variations, geographic quirks, and active hypotheses. 3. TRIAGE OPEN LEADS: - GET /api/research-leads - Look at the prioritized list of open leads before starting work. - Pick an open lead or target area that has not been superseded. 4. CHECK RESEARCH LOG (AVOID DEAD ENDS): - GET /api/research-log - Review recent entries and negative searches so you don't repeat searches already attempted. 5. EXECUTE RESEARCH & CRUD ON ENTITIES: - Run document searches, extract evidence, and record findings. - Perform CRUD operations on: * People: /api/people - Use the 'notes' field on each person record to store rich, detailed biographical narratives, evidence analysis, transcription excerpts, and research caveats in full. * Events / Facts: /api/facts - IMPORTANT TREE FORMATTING RULE: Keep facts ('fact_text') that appear on the tree view as CONCISE, readable bullet points (e.g., vital dates, locations, key occupations, milestone events). - Do NOT paste dense narrative paragraphs or multi-sentence essays into tree facts; put the full details into the person's 'notes' or research log entries instead so the visual tree cards remain clean. * Relationships: /api/relationships * Documents & Citations: /api/documents * File & Image Uploads: /api/uploads - Note: Send HTTP OPTIONS to any endpoint to inspect required fields, writable attributes, and validation rules. 6. HUMAN + LLM COOPERATION & FAMILYSEARCH ACCESS: - Family history research thrives on human + LLM cooperation. Do not hesitate to enlist your human partner! - FamilySearch (familysearch.org) is an invaluable resource, but requires a user account and login. - If your environment supports browser control, do not be shy about opening up a browser tab and politely asking the user to log in to FamilySearch. - When a database, image collection, or archival repository is login-walled, CAPTCHA-protected, or forbidden to automated agents: * Promptly invite the human user to follow the URL, inspect the record, or download the relevant document/image (provided it aligns with the service's Terms of Service). * Ask them to upload or attach the file/data into the project so you can transcribe, cite, and link it. 7. CLOSE THE LOOP (ALWAYS LOG NEGATIVE RESULTS): - Update lead status (e.g. in_progress -> completed/blocked) via PUT /api/research-leads?id=. - Append a research log entry via POST /api/research-log recording sources checked and results. * ALWAYS log negative results (e.g. registers checked and found empty) as research log entries so future sessions never waste tokens re-checking the same film or volume. - Update /api/project-notes via PUT if you discovered new family-specific gotchas or rules. AVAILABLE API ENDPOINTS ----------------------- - GET /help : This help document (plain text). Admins can GET/POST/PUT/DELETE. - GET/POST/PUT/DELETE /api/project-notes : Project scratchpad with footguns, naming quirks, and active notes. - GET/POST/PUT/DELETE /api/research-leads : Open research leads and worklist (?id=). - GET/POST /api/research-log : Research log audit trail of searches and findings. - GET /api/tree : Full graph snapshot of people and relationships. - GET/POST/PUT/DELETE /api/people : Individuals in the family tree (?id=). - GET/POST/PUT/DELETE /api/relationships : Parent-child and spouse relationships (?id=). - GET/POST/PUT/DELETE /api/facts : Vital events (birth, baptism, marriage, death, census) (?id=). - GET/POST/PUT/DELETE /api/documents : Source documents, archival citations, transcripts (?id=). - GET/POST/DELETE /api/uploads : Binary document/image uploads stored in object storage. - GET/POST/PUT/DELETE /api/places : Normalized places and geographic coordinates (?id=). - GET/POST/PUT/DELETE /api/professions : Normalized historical professions (?id=). - GET /api/maps : Geo-coordinate points for mapping. - GET/POST /api/projects : Project metadata and settings. - GET/POST /api/cron/ai-audit : Trigger or run the automated scheduled consistency audit (Vercel Cron). - GET /api/auth : Inspect current user and API key session info. - GET /api/admin/users : Admin overview of registered users, projects, and active agent timestamps (admin only). HTTP OPTIONS ------------ Send OPTIONS /api/ on any resource endpoint for machine-readable schema documentation, required fields, and query parameter selectors. TREE DISPLAY AND GENERATION ASSIGNMENT ------------------------------------- - People appear in /api/tree even without generation_id, under "Generation not assigned". - generation_id is an optional plain-text display tier, not a reference to another record. For new projects, use gen0 = subject, gen1 = parents, gen2 = grandparents, etc. Preserve existing project conventions. Headings use neutral generation numbers. - Assign tiers only when supported by research. The API does not infer generations from relationship labels or parent-child, spouse, or sibling relationships. - Disconnected candidates may remain unassigned; placement does not establish ancestry. - couple_unit_id is optional plain text. Same-tier spouses are grouped automatically with a fallback display ID when it is omitted. Other people appear individually. - No generation or couple-layout initialization endpoint is required. Update existing people with PUT /api/people?id=; do not reimport records to change placement. - /api/tree is a display snapshot; use /api/relationships for the complete relationship set.