framework-ignition-docker/ignition/ignition-api.md

Ignition Gateway HTTP API — Reference

Parent: ../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.

TOKEN="Claude:0Pda7AWJeXENyHlvqi74ORZ20BeWtaDzk2L3WIsaUZs"
GW="http://localhost:8088"
curl -s -H "X-Ignition-API-Token: $TOKEN" $GW/data/api/v1/overview

---

Gateway Status

# 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.

# 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.

# 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

# 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.

# 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.).

# 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

# 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.

# 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

# 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:

curl -s -X POST -H "X-Ignition-API-Token: $TOKEN" $GW/data/api/v1/scan/projects

---

Perspective Sessions

# 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

# 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

# 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

# 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

# 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.

# 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

# 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
  }
}