Updates for Documentation
This commit is contained in:
434
ignition/ignition-api.md
Normal file
434
ignition/ignition-api.md
Normal file
@@ -0,0 +1,434 @@
|
||||
# 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
|
||||
}
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user