Documents

Documents provide reference material that grounds AI-driven simulations in real institutional content. They attach to scenarios so the AI character can draw on policies, syllabi, and other materials during a conversation.

What is a Document?

A document is a piece of content — such as a policy, syllabus, lab template, or homework assignment — that gets attached to a scenario. When a learner runs a simulation, the AI character uses the document as context to stay accurate and on-topic.

University example: An “Academic Integrity Policy” document ensures that when a student character asks about cheating consequences, the AI responds with the actual university policy rather than generic information. A “FERPA Policy” document gives the AI grounding in privacy regulations for scenarios involving student records.

How It Connects: The 5-Step Workflow

Documents participate in step 2 of the Glow workflow:

1. Create Personas — Define AI student characters with temperaments and behaviors.
2. Assign to Scenarios — Attach personas and documents to scenarios. Documents give the AI factual grounding.
3. Add to Simulations — Group scenarios into simulations.
4. Add to Cohorts — Assign profiles and simulations to a cohort.
5. Run Attempts — Learners launch simulations; the AI uses document content during the conversation.

Documents connect to scenarios, not agents. A single document can be shared across multiple scenarios. For example, the Academic Integrity Policy might be referenced in both a “Student Caught Cheating” scenario and a “Grade Appeal” scenario.

Create a document

Via the CLI

Calls below use $GLOW_INSTANCE_URL + $GLOW_TOKEN — see Authentication to export them once.

glow documents create --body '{
  "documents": [
    {
      "name": "Academic Integrity Policy",
      "description": "University policy on academic honesty, plagiarism, and cheating"
    }
  ]
}'

Via the API

All endpoints use POST and require an Authorization: Bearer header.

curl -X POST $GLOW_INSTANCE_URL/document/create \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {
        "name": "FERPA Policy",
        "description": "Family Educational Rights and Privacy Act guidelines for the university"
      }
    ]
  }'

Document Types and Templates

Documents can represent many types of institutional content:

Example: The CS-180 syllabus document contains the course schedule, grading breakdown, and late policy. When attached to a scenario about a student requesting a deadline extension, the AI character can reference the actual late policy from the syllabus.

Content Sections

A document in Glow can include several types of content:

• Name and description — The document title and a summary of what it contains.
• Text content — The main body of the document, such as policy text or syllabus content.
• File uploads — Attached files like PDFs or Word documents that supplement the text content.
• Images — Visual content such as diagrams or charts.
• Parameters and fields — Link the document to specific parameter categories and field values for filtering and organization.
• Department — Scope the document to a department so it appears only for relevant users.

Uploading files

Documents support file uploads for rich content. The upload endpoint is binary-body (no JSON wrapper) and returns an upload_id that you then reference when saving the document draft.

# Upload a file
curl -X POST $GLOW_INSTANCE_URL/document/upload \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/pdf" \
  -H "X-Filename: academic_integrity_policy.pdf" \
  --data-binary @academic_integrity_policy.pdf

The upload returns an upload_id. Reference it when saving the document draft:

glow documents draft --body '{
  "input_draft_id": "doc-draft-uuid",
  "expected_version": 1,
  "name": "Academic Integrity Policy",
  "file_ids": ["upload-id-returned-above"]
}'

Drafts

Documents support the draft workflow. Changes are saved as a draft before being published, with optimistic concurrency via expected_version.

# Save a document draft
glow documents draft --body '{
  "name": "Academic Integrity Policy",
  "description": "Updated policy for the 2026 academic year"
}'

Via the API, use PATCH /document/draft with fields like input_draft_id, expected_version, name, description, file_ids, text_ids, department_ids, parameter_ids, and parameter_field_ids.

Search and filter

Document search supports full-text plus facet filters across department, parameter, and field.

curl -X POST $GLOW_INSTANCE_URL/document/search \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "search": "FERPA",
    "page_size": 10
  }'

Bulk operations

Bulk delete and update follow the canonical all-matching shape — pass either explicit IDs, or all: true with flat filter fields + optional excluded_ids + a patch for updates.

# Delete every document in a deprecated department, except the canonical references
glow documents delete --body '{
  "all": true,
  "filter_department_ids": ["dept-deprecated"],
  "excluded_ids": ["doc-keep-canonical-policy"]
}'
 
# Bulk update via patch
glow documents update --body '{
  "all": true,
  "filter_department_ids": ["dept-archive"],
  "patch": { "archived": true }
}'

See the Personas guide for the canonical write-up of this pattern.

Common Operations

Related

• Documents API
• Documents CLI
• Parameters Guide — parameters and fields that organize documents
• Fields Guide — field values attached to documents
• Departments Guide — scope documents to departments