glpi-api

# GLPi REST API This skill enables you to interact with any GLPi instance through its REST API. GLPi is an open-source IT asset management and helpdesk system widely used in enterprise environments. ## Prerequisites Look for a `.env` file in the working directory (or ask the user) containing: ``` BASE_URL=https://your-glpi-instance/apirest.php APP_TOKEN=your_app_token USER_TOKEN=your_user_token ``` If the `.env` doesn't exist, ask the user for the base URL and credentials. **SSL certificates**: Many internal GLPi instances use self-signed certificates. Always use `curl -sk` (silent + insecure) when calling the API. This is expected for internal enterprise tools. ## Authentication Flow Every API session starts with `initSession` and should end with `killSession`. ```bash # Init session — returns a session_token SESSION=$(curl -sk -X GET \ -H 'Content-Type: application/json' \ -H "Authorization: user_token $USER_TOKEN" \ -H "App-Token: $APP_TOKEN" \ "$BASE_URL/initSession" | python3 -c "import json,sys; print(json.load(sys.stdin)['session_token'])") # All subsequent calls use Session-Token header curl -sk -X GET \ -H 'Content-Type: application/json' \ -H "Session-Token: $SESSION" \ -H "App-Token: $APP_TOKEN" \ "$BASE_URL/Ticket/?range=0-9" # Kill session when done curl -sk -X GET \ -H 'Content-Type: application/json' \ -H "Session-Token: $SESSION" \ -H "App-Token: $APP_TOKEN" \ "$BASE_URL/killSession" ``` Store the session token in a variable and reuse it across calls within the same conversation. No need to re-authenticate for every request. ## Core Endpoints ### Get items ``` GET /:itemtype/:id → single item GET /:itemtype/ → collection (paginated) GET /:itemtype/:id/:sub_itemtype → sub-items GET /getMultipleItems → mixed itemtypes in one call ``` Common itemtypes: `Ticket`, `Computer`, `User`, `Monitor`, `Software`, `Entity`, `Group`, `Profile`, `Document`, `Location`. **Useful query parameters:** - `expand_dropdowns=true` — show names instead of IDs (highly recommended) - `range=0-49` — pagination (default). Use `Content-Range` response header to know the total. - `order=DESC` / `sort=19` — sort by field (19 = date_mod for most types) - `with_documents`, `with_tickets`, `with_logs` — include related items ### Search items The search engine is the most powerful endpoint. It supports complex criteria with AND/OR/NOT logic, meta-criteria across itemtypes, and nested conditions. ``` GET /search/:itemtype/?criteria[0][field]=1&criteria[0][searchtype]=contains&criteria[0][value]=keyword ``` Before searching, discover available fields: ``` GET /listSearchOptions/:itemtype ``` This returns a map of field IDs to their meaning (e.g., `1` = name, `2` = id, `15` = date_creation). **Search criteria structure:** ```json { "field": 1, "searchtype": "contains", "value": "search term" } ``` Search types: `contains` (wildcard), `equals`, `notequals`, `lessthan`, `morethan`, `under`, `notunder`. Use `forcedisplay[0]=1&forcedisplay[1]=2` etc. to choose which columns appear in results. **Example — search tickets by name containing "arrivée":** ```bash curl -sk -g -X GET \ -H 'Content-Type: application/json' \ -H "Session-Token: $SESSION" \ -H "App-Token: $APP_TOKEN" \ "$BASE_URL/search/Ticket?criteria[0][field]=1&criteria[0][searchtype]=contains&criteria[0][value]=arriv&sort=15&order=DESC&range=0-9&forcedisplay[0]=1&forcedisplay[1]=2&forcedisplay[2]=12&forcedisplay[3]=15" ``` Always use `curl -g` (disable globbing) when passing bracket characters in URLs. ### Create / Update / Delete ``` POST /:itemtype/ → add (body: {"input": {...}}) PUT /:itemtype/:id → update (body: {"input": {...}}) DELETE /:itemtype/:id → delete (?force_purge=true to skip trash) ``` Bulk operations pass an array in `input`: ```json {"input": [{"name": "Item 1"}, {"name": "Item 2"}]} ``` ### Session & Profile Management ``` GET /getMyProfiles → list user profiles GET /getActiveProfile → current profile POST /changeActiveProfile → switch profile (body: {"profiles_id": N}) GET /getMyEntities → list accessible entities POST /changeActiveEntities → switch entity (body: {"entities_id": N, "is_recursive": true}) GET /getFullSession → full PHP session data GET /getGlpiConfig → GLPi configuration ``` ### Documents ```bash # Upload curl -sk -X POST \ -H 'Content-Type: multipart/form-data' \ -H "Session-Token: $SESSION" \ -H "App-Token: $APP_TOKEN" \ -F 'uploadManifest={"input": {"name": "Doc name", "_filename": ["file.pdf"]}};type=application/json' \ -F 'filename[0]=@file.pdf' \ "$BASE_URL/Document/" # Download curl -sk -X GET \ -H "Session-Token: $SESSION" \ -H "App-Token: $APP_TOKEN" \ -H "Accept: application/octet-stream" \ "$BASE_URL/Document/:id" ``` ### Massive Actions ``` GET /getMassiveActions/:itemtype/ → list available actions GET /getMassiveActionParameters/:itemtype/:action_key → action params POST /applyMassiveAction/:itemtype/:action_key → execute ``` ## Status Codes | Code | Meaning | |---|---| | 200 | OK | | 201 | Created (single add) | | 206 | Partial content (paginated) | | 207 | Multi-status (bulk with errors) | | 400 | Bad request / input error | | 401 | Unauthorized / invalid session | | 404 | Not found | ## Tips - **Pagination**: Default range is `0-49`. Always check the `Content-Range` header to know the total count. Max range varies per instance (often 1000). - **Sessions are read-only by default**. Pass `session_write=true` for write operations if you get permission errors. - **HTML content**: Responses are HTML-sanitized by default. Add `X-GLPI-Sanitized-Content: false` header to get raw content. - **Ticket status codes**: 1=Nouveau, 2=En cours (attribué), 3=En cours (planifié), 4=En attente, 5=Résolu, 6=Clos. - **Ticket types**: 1=Incident, 2=Demande. - **AllAssets**: Use `AllAssets` as itemtype in search to query across all asset types at once. ## Error Reference See `references/errors.md` for the full list of GLPi API error codes and their meaning.