Reference

This section provides technical reference materials for integrating with OpenIndustrial.

---

API Reference

REST API

The REST API provides programmatic access to your warm queries and workspace resources.

Quick reference:

Method	Endpoint	Purpose
GET	/oi-api/warm-queries/{lookup}	Execute a named warm query
POST	/oi-api/warm-queries	Execute an ad-hoc query
GET	/oi-api/data-stores/{lookup}/containers	List containers in a database
GET	/oi-api/data-stores/{store}/databases/{database}/tables/{table}	List documents in a table
GET	/oi-api/openapi	The OpenAPI 3.1 spec for this workspace

Full REST API Reference →

GraphQL API

For more complex queries and graph-based access to workspace resources.

Full GraphQL Reference →

---

Authentication

API Key Authentication

Include your API key in the request header:

Authorization: Bearer YOUR_API_KEY

Getting your API key:

1. Go to workspace settings
2. Navigate to API Keys section
3. Generate a new key
4. Copy and store securely (shown only once)

Key Management

Action	How
Generate key	Workspace settings → API Keys → Generate
Revoke key	Workspace settings → API Keys → Revoke
View usage	Workspace settings → API Keys → Usage

---

Base URLs

All consumer API endpoints live under /oi-api/ on your own workspace host.

https://{your-workspace-host}/oi-api/

There is no separate API hostname and no workspace id in the path - the host you sign in to is the host you call.

---

Response Formats

Success Response

{
  "data": { ... },
  "meta": {
    "requestId": "abc123",
    "timestamp": "2026-01-19T10:30:00Z"
  }
}

Error Response

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Query 'my-query' not found",
    "details": { ... }
  },
  "meta": {
    "requestId": "abc123",
    "timestamp": "2026-01-19T10:30:00Z"
  }
}

Common Error Codes

Code	HTTP Status	Meaning
UNAUTHORIZED	401	Invalid or missing API key
FORBIDDEN	403	Valid key, insufficient permissions
RESOURCE_NOT_FOUND	404	Resource doesn't exist
VALIDATION_ERROR	400	Invalid request parameters
RATE_LIMITED	429	Too many requests
INTERNAL_ERROR	500	Server error

---

Rate Limits

Tier	Requests/second	Requests/minute
Standard	10	300
Enterprise	50	1500

When rate limited, the response includes:

X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705661400

Best practices:

• Implement exponential backoff
• Cache responses where appropriate
• Use webhooks instead of polling (when available)

---

Glossary

Quick access to terminology used throughout OpenIndustrial.

Full Glossary →

Key Terms

Term	Definition
Connection	Entry point for telemetry data (IoT Hub, Event Hub)
Surface	Queryable workspace containing warm queries
Warm Query	Saved KQL query with API endpoint
Proposal	AI-generated change awaiting your approval

---

SDKs & Tools

MCP Integration

Connect any MCP-native AI to your OpenIndustrial workspace:

• Claude Desktop
• VS Code with Copilot
• Any MCP-compatible agent

MCP Integration Guide →

Coming Soon

• Python SDK
• TypeScript/JavaScript SDK
• CLI tools

---

Additional Resources

• REST API Reference - Complete endpoint documentation
• GraphQL Reference - Schema and query examples
• Glossary - All terminology defined
• Troubleshooting - Common issues and solutions