Skip to content

API Script Library

Ed Mozley edited this page Nov 19, 2026 · 1 revision

πŸ“œ API script library

(5.7.0) System β†’ API β†’ Scripts is a library of ready-made scripts that use the REST API to do real jobs: export open tickets, turn monitoring alerts into tickets, sync people from an HR spreadsheet, import assets, migrate a knowledge base, and more. Every script comes in PowerShell and Python, and every one is heavily commented, so it teaches you the API while it works and you can change it for your own install.

πŸšͺ Using one

  1. Find it. Search by what you want to do, or filter by module, by Read only / Changes data, and by level (Starter, Intermediate, Advanced).

  2. Check what it needs. Each script lists the endpoints it calls and the exact permissions the key needs.

  3. Make a key under System β†’ API β†’ Keys with just those permissions. A key that can do only what the script needs is the safe way to run anything.

  4. Copy or Download the script, and read it - the comments say what each part does.

  5. Run it on your own computer, pointing it at your FreeITSM:

    powershell -ExecutionPolicy Bypass -File .\export-open-tickets-csv.ps1 -Url https://helpdesk.example.com
    python export-open-tickets-csv.py --url https://helpdesk.example.com

πŸ’‘ Start with Check your API key. It needs no permissions, proves the key reaches your FreeITSM, and lists what the key is allowed to do.

πŸ”‘ Where the key goes

Never in the script. Every script reads it from the FREEITSM_API_KEY environment variable, or from a file - api-key.txt beside the script unless you pass -KeyFile / --key-file. Keep that file out of source control and readable only by you. The address can likewise come from FREEITSM_URL instead of -Url / --url.

πŸ‘€ Scripts that change data preview first

A script marked Changes data only shows what it would do until you add -Apply (PowerShell) or --apply (Python). Run it once without, read the list, then run it again with. Many are also safe to run twice: they check what already exists before creating anything.

🐍 What you need

  • PowerShell: Windows PowerShell 5.1 (built into Windows) or PowerShell 7 on any system.
  • Python: 3.8 or later. Nothing to install - the Python scripts use only Python's built-in libraries, so they also run on locked-down servers where pip install is not allowed.

πŸ”’ Why they are safe to trust

  • They ship with FreeITSM as files, reviewed in the public repository and updated with each release. They are not stored in the database, so nothing done inside FreeITSM - not even by an administrator, or by someone who broke in - can change what a script does. Decided with Ed, 19 November 2026: people run these with admin keys on their own machines, so a script must carry the same trust as the code itself.
  • The page only shows them. Nothing runs on the server; downloads are plain text.
  • Every script was run against a test install before it shipped, and an automatic check fails the build if a script calls an endpoint that does not exist, uses a permission it does not declare, carries a key, or writes without a preview mode.

Only system administrators can open System β†’ API, and so the Scripts tab.

How it works and how to add a script: API script library - Developer Guide. The design and decisions: API script library - design.

Related: REST API Β· REST API: Knowledge

FreeITSM

Getting Started

Modules

Multi-tenancy (planned)

Responses to feedback

Blue sky thinking

Bugs resolved

Pull requests

Links

Clone this wiki locally