Personal
Fields marked * are required. Updates keep every field they are not given. An AI app can ask vritto_describe for the same details, filtered to what its connection may use.
Personal Profileprofile
The user's own identity, vitals, preferences, and favorites.
personal_findFindthrough vritto_findRead the user's profile and life history: with nothing named, the full profile (identity, narrative, vitals, preferences, favorites, skills, languages, principles, social links) and the dated timeline of work, education, homes, credentials and projects with their entry IDs; view 'timeline' with domains for one part; collection and id for one complete entry.
Note: With nothing named it returns the profile and the dated timeline; collection and id read one entry complete.
| Field | Type | Description |
|---|---|---|
| view | one of profile, timeline | 'profile' the profile alone; 'timeline' the dated history alone. |
| domains | list of one of | Only these parts of the timeline. |
| collection | one of experiences, education, residences, credentials, projects, relationships | With id: the entry's sourceCollection, as the timeline gives it. |
| id | string | With collection: one entry, complete. |
Example input
{}personal_changeUpdatethrough vritto_updateChange the user's profile: favorites (one value per slot, merged; an empty value clears one), identity (name, pronouns, date of birth, birthplace, nationalities, gender, home base, name history), narrative, vitals, preferences, principles, skills, languages, or social links. Arrays and narrative REPLACE the stored value: read personal_find first and send the full merged set.
Note: Arrays and narrative replace the stored value; read the profile first and send the full merged set. Favorites merge one slot at a time.
| Field | Type | Description |
|---|---|---|
| favorites | list of object | Favorites to record, one entry per slot. Common slots: movie, show, book, music, artist, food, cuisine, drink, place, city, color, sport, team, hobby, game, quote, season. |
| identity | object | |
| identity.fullName | string | The user's name as Vritto shows it everywhere, including their account. |
| identity.preferredName | string | |
| identity.legalName | string | |
| identity.pronouns | string | |
| identity.gender | string | |
| identity.dateOfBirth | string | A date the user gives: "2022", "2022-06", "2022-06-15", or free text like "summer 2020". Year is enough. |
| identity.birthPlace | object | A light place reference; label is enough. |
| identity.nationalities | list of string | Full replacement list of nationalities. |
| identity.homeBase | object | Where the user lives now. Saved to Where I've Lived as their current home; use personal_add with type residence instead to record a move with dates. |
| identity.nameHistory | list of object | Full replacement list of prior/other names. |
| narrative | object | Replaces the whole narrative, include all three fields you want kept. |
| narrative.headline | string | |
| narrative.about | string | |
| narrative.currentFocus | string | |
| vitals | object | |
| vitals.height | string | Free text, e.g. "5'11\"" or '180 cm'. |
| vitals.weight | string | |
| vitals.bloodType | one of A+, A-, B+, B-, AB+, AB-, O+, O-, unknown | |
| vitals.starSign | one of aries, taurus, gemini, cancer, leo, virgo, libra, scorpio, sagittarius, capricorn, aquarius, pisces | |
| vitals.handedness | one of right, left, ambidextrous | |
| vitals.eyeColor | string | |
| preferences | object | |
| preferences.dietary | list of string | Full replacement list, e.g. ['vegetarian', 'no pork']. |
| preferences.allergies | list of string | Full replacement list of allergies. |
| preferences.notes | string | |
| principles | list of object | Full replacement list of the user's values/principles. |
| skills | list of object | Full replacement list of skills. |
| languages | list of object | Full replacement list of languages. |
| socialLinks | list of object | Full replacement list of social links. |
Example input
{
"favorites": [
{
"slot": "cuisine",
"value": "Thai"
}
]
}Life Historylife_history
The user's dated history: jobs, education, homes, credentials, personal projects and relationship chapters (type picks which).
personal_addCreate or Updatethrough vritto_create or vritto_updateAdd a dated history entry the user mentions: type experience (a job), education, residence (Where I've Lived; current true on a home is a move), credential, project, or relationship (a partner, family or close chapter). Add only what is new: an entry already on file (the same job, school or home) is changed by sending its id from personal_find, and sent fields merge.
| Field | Type | Description |
|---|---|---|
| type | one of experience, education, residence, credential, project, relationship | Which history: 'experience' (default when org is sent), 'education', 'residence', 'credential', 'project', 'relationship'. |
| record* | object | The entry; the required field is its type's (org, institution, place or name). |
| record.id | string | Existing entry ID to update (from personal_find); omit to add. Fields you leave out keep their stored value. |
| record.org | string | Type 'experience': employer or organization. Required for it. |
| record.title | string | Type 'experience': job title. |
| record.employmentType | one of full_time, part_time, self_employed, freelance, contract, internship, apprenticeship, seasonal, volunteer | Type 'experience'. |
| record.location | object | Type 'experience': where the job was. |
| record.institution | string | Type 'education': the school. Required for it. |
| record.degree | string | Type 'education'. |
| record.field | string | Type 'education': field of study. |
| record.grade | string | Type 'education': GPA or grade, e.g. '3.8' or 'First Class'. |
| record.activities | string | Type 'education': clubs, societies, sports. |
| record.courses | list of string | Type 'education': notable courses taken. |
| record.academicsTermId | string | Type 'education': link to an Academics module term. |
| record.place | object | Type 'residence': where they lived. Required for it. |
| record.kind | one of home, hometown, study, work, second_home, partner, spouse, engaged, ex_partner, situationship, family, friend, mentor, other | Type 'residence' (default home): home, study and work are places they lived; hometown is where they belong without living there; second_home is lived in part-time. Type 'relationship': partner, spouse, engaged, ex_partner, situationship, family, friend, mentor or other. |
| record.name | string | Type 'credential' (e.g. 'AWS Solutions Architect'), 'project', or 'relationship' (the person's name). Required for those. |
| record.issuer | string | Type 'credential'. |
| record.issued | string | Type 'credential'. |
| record.expires | string | Type 'credential'. |
| record.credentialId | string | Type 'credential': the issuer's credential or license number. |
| record.url | string | Type 'credential' (verification or badge URL) or 'project'. |
| record.description | string | Type 'project'. |
| record.role | string | Type 'project': their role, e.g. 'founder', 'designer'. |
| record.guideId | string | Type 'project': link to a Guides module guide. |
| record.start | string | A date the user gives: "2022", "2022-06", "2022-06-15", or free text like "summer 2020". Year is enough. |
| record.end | string | A date the user gives: "2022", "2022-06", "2022-06-15", or free text like "summer 2020". Year is enough. |
| record.current | boolean | true when it is ongoing: they still work, study or live there, or the relationship goes on. |
| record.summary | string | Type 'experience' or 'education'. |
| record.highlights | list of string | Type 'experience' or 'project': notable achievements or outcomes, one per entry. |
| record.note | string | Type 'residence' or 'relationship'. |
| record.personId | string | Type 'relationship': the People record for this person (resolve with people_find), set whenever the person exists there. |
| record.personIds | list of string | People-module person IDs tied to this entry (resolve with people_find) so it links into their graph. |
| record.visibility | one of private, ai | Who can see this. private = only the user; ai = also SahAI. |
Example input
{
"type": "experience",
"record": {
"org": "Vritto, Inc.",
"title": "Founder",
"employmentType": "self_employed",
"start": "2026-01",
"current": true
}
}