435 lines
11 KiB
Markdown
435 lines
11 KiB
Markdown
# Ignition Gateway HTTP API — Reference
|
|
|
|
Parent: [../CLAUDE.md](../CLAUDE.md)
|
|
|
|
Live spec: `http://<gateway-host>:8088/openapi` (UI) · `http://<gateway-host>:8088/openapi.json` (JSON)
|
|
|
|
---
|
|
|
|
## Authentication
|
|
|
|
All requests require an API token in a custom header:
|
|
|
|
```
|
|
X-Ignition-API-Token: <name>:<token>
|
|
```
|
|
|
|
The `<name>` 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=<name>:<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": "<password>",
|
|
"ValidateOnCheckout": true
|
|
}
|
|
}
|
|
|
|
# Modify (requires signature from GET)
|
|
PUT /data/api/v1/resources/ignition/database-connection
|
|
{ "name": "ignition_db", "signature": "<sig>", "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
|
|
<tag export JSON body>
|
|
```
|
|
|
|
---
|
|
|
|
## 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
|
|
<zip file body>
|
|
|
|
# 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
|
|
<gwbk file>
|
|
```
|
|
|
|
---
|
|
|
|
## 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
|
|
}
|
|
}
|
|
```
|