/documents

name: "IT Glue Documents"
description: >
  IT Glue documents: rich-HTML documentation records scoped to an organization,
  including document folders, multi-section content via the Document Sections
  API, embedded passwords/configurations/images, and related-item links to
  other IT Glue resources.
when_to_use: >-
  When creating, organizing, and managing documentation. Use when: it glue document,
  documentation, runbook, procedure documentation, it glue docs, document management, sop
  documentation, or knowledge base.

IT Glue Documents Management

Overview

Documents in IT Glue provide structured documentation storage for organizations, enabling technicians to create runbooks, procedures, network diagrams, and general documentation. Documents support rich HTML content, embedded passwords, and relationships to other IT Glue resources.

Anti-triggers

• **Documentation with a fixed field schema** — repeatable, filterable

records are flexible assets, not free-form documents; use `itglue-flexible-assets`.

• **The credential a runbook refers to** — passwords are separate

records that documents embed by reference; use `itglue-passwords`.

• **Device facts rather than narrative** — use

`itglue-configurations`.

Key Concepts

Document Structure

Documents consist of:

• **Name** - Document title
• **Content** - Rich HTML content with embedded resources
• **Folder** - Organizational hierarchy location
• **Related Items** - Links to configurations, contacts, etc.

Document Folders

Folders provide hierarchical organization:

Organization: Acme Corporation
└── Documents
    ├── Onboarding
    │   ├── New User Setup
    │   └── Hardware Deployment
    ├── Procedures
    │   ├── Backup Procedures
    │   └── Disaster Recovery
    └── Network
        ├── Network Diagram
        └── IP Scheme

Embedded Resources

Documents can embed:

• **Passwords** - Inline credential display (`<div data-embedded-password-id="12345"></div>`)
• **Configurations** - Asset links (`<div data-embedded-configuration-id="67890"></div>`)
• **Contacts** - Contact information
• **Images** - Uploaded images/diagrams (`<img src="/uploads/organization/123/...">`)

Document Sections

Multi-section documents are composed of ordered sections rather than a single `content` blob — this is what the Document Sections API reads and writes.

| Type | Description | |------|-------------| | `Document::Heading` | Heading element (renders as `<h2>`, etc.) | | `Document::Text` | Rich HTML text block |

See [references/fields.md](references/fields.md) for the complete field reference.

Common Workflows

Restructure a Document

Sections must be replaced, not patched, and the document must be republished for changes to appear:

1. List existing sections (`GET .../relationships/sections`) 2. Delete all existing sections 3. Create new sections in the desired order 4. Publish the document with **PATCH** (not POST) to make changes visible

See [references/examples.md](references/examples.md) for the full `restructureDocument` implementation, plus runbook creation, search, export, health-check, and template-cloning workflow examples.

New Client Runbook

Ensure the target folder exists, build HTML content section by section (overview, prerequisites, steps, embedded credentials), create the document, then create related items linking it to relevant configurations.

Renaming, Deleting and Attachments

• `update_document` (write) **renames** a document (`document_id`, `name`). It cannot move a document between folders: IT Glue does not accept `document_folder_id` on update.
• `delete_document` (admin) permanently deletes a document and all its sections. Prefer `archive_document`, which is recoverable with `unarchive_document`; delete only when the user explicitly asks and has confirmed the document ID.
• `create_attachment` (write) attaches a file (`resource_type`, `resource_id`, `file_name`, base64 `content` without a `data:` prefix) to a document or any other record. It is the only supported way to get an image into a document body: upload it, then reference the returned download URL from an `<img src>` in a section.
• `list_attachments` (read) lists the files on a record with their download URLs.

Who Has Been Using IT Glue

`search_user_metrics` (read) returns per-user, per-organization, per-resource-type counts of created, viewed, edited and deleted actions by date. The date range is at most 7 days per call; page through longer periods week by week. Use it for "who viewed the passwords for this client last week?" and for documentation-engagement reports.

API Patterns

• **List documents by organization only** — `GET /documents` (top-level) returns 404 in practice. Use `GET /organizations/:id/relationships/documents` instead.
• **Editing body content** — `PATCH /documents/:id` with a `content` attribute silently does nothing on multi-section documents. Use the Document Sections API (create/update/delete individual sections) instead.
• **Publishing** — `PATCH /documents/:id/publish` makes section edits visible. POST returns 404; no request body is required.

See [references/api.md](references/api.md) for the complete endpoint catalog: document, section, folder, and related-item CRUD with full request/response examples.

Gotchas

• **404 on organization documents** usually means the IT Glue Documents module isn't enabled for that organization — fall back to `search_flexible_assets`, since flexible assets are the more common documentation mechanism in practice.
• **Section content updates require the Sections API**, not `PATCH /documents/:id` — the top-level `content` attribute is only honored for single-blob (non-sectioned) documents.
• **Publish is PATCH, not POST** — POSTing to `/documents/:id/publish` returns 404.

See [references/errors.md](references/errors.md) for the complete error-code and validation-error tables plus a retry pattern for invalid-folder errors.

Be