# Ignition Gateway HTTP API — Reference Parent: [../CLAUDE.md](../CLAUDE.md) Live spec: `http://:8088/openapi` (UI) · `http://:8088/openapi.json` (JSON) --- ## Authentication All requests require an API token in a custom header: ``` X-Ignition-API-Token: : ``` The `` is the token's display name in the gateway. Tokens are managed at **Platform > Security > API Keys** in the gateway web UI, or via the config API. - **GET requests** are not recorded in the audit log. - **POST / PUT / DELETE** are recorded in the audit log — use with intent. - Store tokens in `~/.config/ignition-dev/secrets.env` as `IGNITION_API_TOKEN=:`. Never hardcode tokens in scripts or commit them. ```bash TOKEN="Claude:0Pda7AWJeXENyHlvqi74ORZ20BeWtaDzk2L3WIsaUZs" GW="http://localhost:8088" curl -s -H "X-Ignition-API-Token: $TOKEN" $GW/data/api/v1/overview ``` --- ## Gateway Status ```bash # General status — uptime, edition, state GET /data/api/v1/overview # All connections (DB, OPC, device) GET /data/api/v1/overview/connections # Critical problems blocking normal operation GET /data/api/v1/overview/problems # Gateway name only GET /data/api/v1/overview/name # Detailed gateway info GET /data/api/v1/gateway-info ``` --- ## Scan / Filesystem Sync Ignition watches mounted directories for changes, but an explicit scan guarantees immediate pickup. **Always scan after editing project or config files.** ```bash # Trigger project scan — run after editing ignition/project/ files POST /data/api/v1/scan/projects # Check project scan status GET /data/api/v1/scan/projects # Trigger config scan — run after editing gw-config/ files POST /data/api/v1/scan/config # Check config scan status GET /data/api/v1/scan/config ``` ### Scan Lock (bulk operations) Acquire a scan lock before making multiple changes to prevent partial-state scans. The lock releases automatically when the POST scan is triggered. ```bash # Acquire lock (body: {"timeoutSeconds": 60}) POST /data/api/v1/scan-lock/projects POST /data/api/v1/scan-lock/config # Check current lock holder GET /data/api/v1/scan-lock/projects GET /data/api/v1/scan-lock/config ``` --- ## Resource API Pattern Almost all gateway configuration uses a common CRUD pattern: ``` GET /data/api/v1/resources/list/{moduleId}/{typeId} list all (verbose) GET /data/api/v1/resources/names/{moduleId}/{typeId} names + enabled status GET /data/api/v1/resources/find/{moduleId}/{typeId}/{name} get one + signature GET /data/api/v1/resources/type/{moduleId}/{typeId} describe schema POST /data/api/v1/resources/{moduleId}/{typeId} create PUT /data/api/v1/resources/{moduleId}/{typeId} modify (requires signature) DELETE /data/api/v1/resources/{moduleId}/{typeId}/{name}/{sig} delete POST /data/api/v1/resources/rename/{moduleId}/{typeId}/{name} rename ``` > **Always GET before PUT/DELETE** — the `signature` field from a GET response is required > for modify and delete operations. It changes whenever the resource is updated. ### Key moduleId / typeId pairs | Resource | moduleId | typeId | |---|---|---| | Database connection | `ignition` | `database-connection` | | OPC connection | `ignition` | `opc-connection` | | Tag provider | `ignition` | `tag-provider` | | OPC-UA device | `com.inductiveautomation.opcua` | `device` | | OPC-UA server config | `com.inductiveautomation.opcua` | `server-config` | | OPC-UA access control | `com.inductiveautomation.opcua` | `access-control` | ### Common query parameters | Param | Example | Description | |---|---|---| | `limit` | `25` | Max items to return | | `offset` | `50` | Items to skip | | `sortBy` | `asc(name)` | Sort field + direction | | `search` | `postgres` | Free-text filter | | `filter[field[op]]` | `filter[enabled[eq]]=true` | Field filter | Filter operators: `eq` `ne` `cn` `sw` `ew` `gt` `gte` `lt` `lte` `rgx` --- ## Database Connections ```bash # List all database connections GET /data/api/v1/resources/list/ignition/database-connection # Get one (returns config + signature) GET /data/api/v1/resources/find/ignition/database-connection/{name} # Create a PostgreSQL connection POST /data/api/v1/resources/ignition/database-connection Content-Type: application/json { "name": "ignition_db", "enabled": true, "props": { "ConnectURL": "jdbc:postgresql://postgres:5432/ignition", "Username": "ignition", "Password": "", "ValidateOnCheckout": true } } # Modify (requires signature from GET) PUT /data/api/v1/resources/ignition/database-connection { "name": "ignition_db", "signature": "", "props": { ... } } # Delete DELETE /data/api/v1/resources/ignition/database-connection/{name}/{signature} # Describe schema (shows all available props) GET /data/api/v1/resources/type/ignition/database-connection ``` --- ## OPC Connections Used to connect Ignition to Modbus simulators and AB PLC controllers via OPC-UA. ```bash # List all OPC connections GET /data/api/v1/resources/list/ignition/opc-connection # Get one GET /data/api/v1/resources/find/ignition/opc-connection/{name} # Create an OPC-UA connection to a Modbus sim POST /data/api/v1/resources/ignition/opc-connection { "name": "modbus-sim-pumps", "enabled": true, "props": { "EndpointUrl": "opc.tcp://modbus-sim-pumps:4840", "SecurityPolicy": "None", "MessageSecurity": "None" } } # Describe schema GET /data/api/v1/resources/type/ignition/opc-connection ``` --- ## OPC-UA Devices OPC-UA device driver instances (Allen-Bradley, Modbus TCP, etc.). ```bash # List all devices GET /data/api/v1/resources/list/com.inductiveautomation.opcua/device # Get one GET /data/api/v1/resources/find/com.inductiveautomation.opcua/device/{name} # Describe available device types and their properties GET /data/api/v1/resources/type/com.inductiveautomation.opcua/device # Create (body varies by device type — use type endpoint to discover props) POST /data/api/v1/resources/com.inductiveautomation.opcua/device ``` --- ## Tag Providers ```bash # List tag providers GET /data/api/v1/resources/list/ignition/tag-provider # Get one GET /data/api/v1/resources/find/ignition/tag-provider/{name} # Describe schema GET /data/api/v1/resources/type/ignition/tag-provider # Create / modify follow the standard resource pattern POST /data/api/v1/resources/ignition/tag-provider PUT /data/api/v1/resources/ignition/tag-provider ``` --- ## Tag Import / Export Primary mechanism for bulk tag management outside of Designer. ```bash # Export tags as JSON (default), XML, or CSV GET /data/api/v1/tags/export?provider=default&path=Devices&recursive=true&type=json # Save to file: curl -s -H "X-Ignition-API-Token: $TOKEN" \ "$GW/data/api/v1/tags/export?provider=default&path=Devices&recursive=true" \ -o tags-export.json # Import tags # collisionPolicy: Abort | Overwrite | Ignore | MergeOverwrite | MergeIgnore POST /data/api/v1/tags/import?provider=default&path=Devices&collisionPolicy=Overwrite Content-Type: application/json ``` --- ## Projects ```bash # List all projects GET /data/api/v1/projects/list # Get project details GET /data/api/v1/projects/find/{name} # Create a project POST /data/api/v1/projects { "name": "my-project", "title": "My Project", "enabled": true } # Modify a project PUT /data/api/v1/projects/{name} # Export project as zip archive GET /data/api/v1/projects/export/{name} # Import project from zip POST /data/api/v1/projects/import/{name}?overwrite=true Content-Type: application/octet-stream # Delete project DELETE /data/api/v1/projects/{name}?confirm=true ``` After creating or modifying projects via file edits, trigger a scan: ```bash curl -s -X POST -H "X-Ignition-API-Token: $TOKEN" $GW/data/api/v1/scan/projects ``` --- ## Perspective Sessions ```bash # List all active Perspective sessions GET /data/perspective/api/v1/sessions/ # Get session details GET /data/perspective/api/v1/session/{sessionId} # List pages in a session GET /data/perspective/api/v1/session/{sessionId}/pages # List views on a page GET /data/perspective/api/v1/session/{sessionId}/page/{pageId}/views # Terminate session(s) DELETE /data/perspective/api/v1/sessions?sessionId={id}&message=Maintenance ``` --- ## Modules ```bash # List all healthy (non-quarantined) modules GET /data/api/v1/modules/healthy # List quarantined modules GET /data/api/v1/modules/quarantined # Enable or disable a module PUT /data/api/v1/modules/toggle-state { "moduleId": "com.inductiveautomation.webdev", "enabled": true } # Upload a module file (.modl) POST /data/api/v1/modules/upload?fileName=MyModule.modl Content-Type: application/octet-stream # Install after upload POST /data/api/v1/modules/install?moduleId=com.example.mymodule # Accept EULA POST /data/api/v1/modules/eula?moduleId=com.example.mymodule # Uninstall (takes effect after restart) DELETE /data/api/v1/modules/uninstall { "moduleIds": ["com.example.mymodule"] } ``` --- ## Logs ```bash # Query gateway logs GET /data/api/v1/logs?minLevel=WARN&limit=100 # Filter by logger name GET /data/api/v1/logs?logger=IgnitionGateway&limit=50 # Filter by time range (ISO 8601) GET /data/api/v1/logs?startTime=2026-03-17T00:00:00Z&endTime=2026-03-17T23:59:59Z # List all loggers and their current levels GET /data/api/v1/logs/loggers # Set a logger level temporarily POST /data/api/v1/logs/loggers/{loggerName}?level=DEBUG # Download full log file GET /data/api/v1/logs/download ``` --- ## Audit Log ```bash # Query audit events for a profile (default profile name: "Audit") GET /data/api/v1/audit/log/Audit?limit=50 # Filter by actor GET /data/api/v1/audit/log/Audit?actorFilter=admin # Filter by action GET /data/api/v1/audit/log/Audit?actionFilter=Created ``` --- ## Gateway Backup ```bash # Download a .gwbk backup file curl -s -H "X-Ignition-API-Token: $TOKEN" \ "$GW/data/api/v1/backup" \ -o "gateway-$(date +%Y%m%d-%H%M%S).gwbk" # Restore from backup (gateway will restart) POST /data/api/v1/backup?restoreDisabled=false Content-Type: multipart/form-data ``` --- ## Gateway Restart ⚠️ **Disruptive — all sessions will be terminated. Get explicit user confirmation first.** ```bash # Check if a restart is needed (pending tasks) GET /data/api/v1/restart-tasks/pending # Restart — confirm=true is required curl -s -X POST -H "X-Ignition-API-Token: $TOKEN" \ "$GW/data/api/v1/restart-tasks/restart?confirm=true" ``` Per `CLAUDE.md` safety rules: never restart the gateway without explicit user confirmation. --- ## API Token Management ```bash # Generate a new key/hash pair (store the key — it is not retrievable again) POST /data/api/v1/api-token/generate # List existing API token configs GET /data/api/v1/resources/list/ignition/api-token # Create an API token resource POST /data/api/v1/resources/ignition/api-token { "name": "MyToken", "props": { "Enabled": true, "RateLimit": -1 } } ```