Agent metadata is inconsistent across endpoints — needs one clean, documented schema

[mamigot]

Summary

Agent ("mentor") metadata is represented inconsistently across the platform API, and the per-agent metadata blob duplicates first-class fields with no documented source of truth. The result: a client cannot reliably read a value and write it back, the iblai-* skills can only type these fields as "string", and at least one category record is malformed. The platform needs one clean, documented metadata schema — please treat that as the goal of this issue.

All evidence below was reproduced live against api.iblai.app on org nycuniversity, agent agentAI (unique_id 742212a0-b32d-4f6f-8d79-d3acd557e211). It is not skill-doc speculation — these are real API responses.

1. "Category" has 4+ incompatible shapes across endpoints

Endpoint	Shape of category
GET …/mentor/categories/	array of objects {id, name, description, category_group, audience, audiences}
PUT …/mentors/{id}/settings/ (write)	categories: number[] — IDs only
GET …/mentors/{id}/settings/ (read)	categories: [{full object}]
GET …/search/orgs/{org}/users/{u}/mentors/ (list)	categories: ["Learning"] (name strings) and a separate category: null
agent metadata blob (see §2)	category: "Learning" (single string)

A client literally cannot round-trip: you read names / objects but must write numeric IDs, and the same concept is exposed under both category (singular, often null) and categories (plural). There is no single canonical representation.

2. The metadata blob duplicates first-class fields (drift risk)

GET …/settings/ returns a free-form metadata object:

"metadata": {
  "admin": true, "default": true, "student": true,
  "category": "Learning",
  "featured": false,
  "promotion": ["mentorAI_mymentors"],
  "mentorAI_app": {"community": false, "my_mentors": true},
  "primary_color": "#2467eb", "secondary_color": "#000",
  "safety_disclaimer": false,
  "allow_to_use_as_template": true
}

These duplicate first-class settings fields and can silently disagree:

• metadata.category ⇄ categories[]
• metadata.featured ⇄ top-level is_featured
• metadata.safety_disclaimer ⇄ enable_disclaimer / disclaimer

Which one wins? Which is authoritative on write? Undocumented. The keys inside metadata are also entirely undocumented.

3. audience (singular) vs audiences (plural) on category objects

Each category carries both an audience (sometimes null, sometimes a single object) and audiences (an array). Redundant and ambiguous — consumers don't know which to trust.

4. Malformed category record

Category id: 112 "Assessment" is inconsistent with every sibling record:

{"id":112,"name":"Assessment","description":"{'Assessment'}","category_group":null,"audience":null,"audiences":[]}

description is a stringified Python set literal ("{'Assessment'}"), category_group is null, and audiences is empty — whereas e.g. Advising/Learning have clean descriptions, real group ids, and populated audiences. Looks like bad data on ingestion.

5. mentor_visibility is an undocumented enum

It is typed only as "string" in the skills. The one observed live value is viewable_by_tenant_students. There is no published allowed-values list anywhere, so clients can't validate it or offer choices.

6. Write contract documents ~14 fields; read returns 109

GET …/settings/ returns 109 fields; the iblai-agent-settings skill documents ~14. The undocumented surface includes overlapping flags with no stated relationship — e.g. three different voice toggles: enable_voice_call, show_voice_call, embed_show_voice_call. Without a schema/enum, "clean metadata" can't even be validated.

Why this matters / the ask

The intent is clean, canonical metadata. Concretely, please:

1. One canonical shape per concept, especially category — pick a single representation (ids+names) and use it consistently on read and write; drop the redundant singular category and the name-string variant, or document them as deliberate read projections.
2. Deduplicate the metadata blob vs first-class fields, or document exactly which is authoritative and how they sync.
3. Enumerate mentor_visibility (and the boolean-flag set) in the API docs.
4. Normalize audience vs audiences on category objects.
5. Fix the malformed Assessment (id 112) record and add a validation/lint so a stringified set literal can't land in description again.
6. Publish the full settings schema (all 109 fields) with types/enums and clarify the overlapping flags.

Related

• PR Fix iblai-login: dm_token uses Token scheme (not Bearer) + tenant/verify notes #6 fixes adjacent /iblai-login doc bugs (auth scheme Token vs Bearer, token-verification endpoint). This issue is about the deeper metadata-consistency problem rather than a doc typo.

---

Filed from a live /iblai-* skills session; all payloads above are real responses from api.iblai.app (org nycuniversity).