InTouch Automation REST API
Technical Architecture and Implementation Guide
Micronaut Framework | OpenAPI 3.0 | Swagger UI | 413 Endpoints across 26 Domains
Built on the Micronaut framework with compile-time dependency injection, the InTouch REST API follows the OpenAPI 3.0 specification with integrated Swagger documentation. 413 endpoints across 26 functional domains provide complete programmatic control over jobs, scheduling, triggers, credentials, AI gateway, the tool plugin system, skills, YAML jobs, and server administration.
Technology Stack
Micronaut 4.x
Compile-time DI eliminates reflection overhead. Fast startup, low memory footprint, non-blocking I/O.
OpenAPI 3.0
Standards-based specification enables automatic client generation in Java, Python, JS, C#, and more.
RESTful Design
Standard HTTP methods, stateless architecture, predictable URI patterns, JSON payloads.
JSON Format
All request and response bodies use JSON for maximum interoperability across platforms.
API Design Principles
Comprehensive Coverage
Every UI feature accessible via API
Consistent Patterns
Uniform CRUD operations across all domains
Idempotent Operations
GET, PUT, DELETE are safely repeatable
Clear Versioning
API versioning for backward compatibility
Descriptive Errors
Meaningful error codes and messages
Pagination Support
Efficient handling of large result sets
Integrated Swagger UI
Browse, test, and explore every API endpoint directly in your browser. The integrated Swagger UI provides live API testing, schema validation, code generation for multiple languages, and authentication integration. Access at http://[server]:[port]/swagger-ui.
API Functional Domains
Complete coverage from the live OpenAPI spec — 413 endpoints organized across 26 functional tag groups. Counts below match what is actually implemented in the running server.
| Domain | Endpoints | Description |
|---|---|---|
| Job | 59 | Full CRUD on jobs plus run, copy, content/schedule/trigger management, collision rules, exclusivity, tool editing, and AI-trigger linkage. The largest surface in the API. |
| Configuration | 33 | Server-wide settings: SMTP, SMS, messaging platforms (Slack, Discord, Telegram, WhatsApp, Teams, LINE), LDAP, CyberArk, AI assistant, encryption, runtime polling, sender filters. |
| Server | 26 | Edition info, license, autostart, log purge, AI-trigger polling, maintenance mode, shutdown, restart, health and version endpoints. |
| Credential | 23 | Encrypted credential vault: connections to databases, cloud services, SSH/SFTP, AI providers, message channels, webhooks, OAuth, runtime environments. Full CRUD plus test/validate. |
| YAML Job | 19 | Jobs-as-Code lifecycle: load, validate, sync to DB, list, install, export, reload, dry-run, schedule wiring. |
| Role | 19 | RBAC roles, custom roles, role-to-publisher and role-to-group assignments, per-object rights. |
| Skill | 18 | InTouch skills (SKILL.md) and OpenClaw skills: list, get, install, update, delete, invoke, source export, Hubue search. |
| InTouch Tool | 18 | IToolConnector plugins and YAML tools: list, install, reload (single + all), scan, source export, hot-deploy. |
| Schedule | 17 | Seven native schedule types (Day, Week, Weekday, Weekend, Month/Specific, Month/Relative, Custom) with timezone, blackout dates, expiration, and group management. |
| Job Activity | 17 | Execution history, log messages by date range / last execution / single run, work-completed time series, run/job ID lookups. |
| AI | 16 | AI gateway routing (Enterprise-only feature: cost-optimized / latency-optimized / failover / round-robin / policy strategies across providers), prompt CRUD with named-resolve, usage summary by model / provider / project, usage purge. |
| Group | 14 | Object groups for credentials, schedules, trigger files, AI triggers, runtime envs, subscribers — plus default-group resolution. |
| AI Trigger | 13 | LLM-evaluated trigger conditions, polling, group membership, enable/disable, dry-run. |
| Trigger file | 11 | Filesystem watch triggers with settle time, glob filters, group assignment, enable/disable. |
| Alert | 11 | Multi-channel alert subscriptions for job state transitions (start, done, error, retry, overrun, warning). |
| Intouch Message | 14 | Per-publisher inbox (v8): list-mine / list-mine-unread / list-by-publisher-id, get-by-id, get-unread-count, get-attachment, mark-read / mark-unread / mark-all-read, delete, delete-batch, delete-older-than-days, delete-before, export-csv. |
| Subscriber | 9 | Notification recipients (email, SMS, Slack, Discord, Telegram, WhatsApp, Teams, LINE) and group membership. |
| Project | 9 | Top-level resource container; create, copy, list, delete with optional cascade. |
| Jobset | 9 | Group jobs into executable sets within a project; CRUD plus list-by-project. |
| Access | 8 | Login, logout, change password, generate / revoke API key, ownership transfer. |
| Runtime Environment | 7 | Python, Node, Bash, PowerShell, Ruby, Perl runtimes — registration, env-var management, test execution. |
| Publisher | 7 | User account CRUD, group membership, locking. |
| Import/Export | 7 | Configuration migration between environments — projects, jobs, schedules, credentials with selective export. |
| Oneshot | 6 | One-time tool execution outside the job framework — for AI assistant tool calls and script-driven actions. |
| Assistant | 6 | AI assistant chat session, tool-use loop, command translation, prompt patterns. |
| Filesystem | 1 | Server-side filesystem listing for path pickers in the UI. |
| Total | 413 | 26 functional domains |
Authentication
Session-based authentication via POST /intouch/access/login. The body is a LoginDTO with publisher + password (and an optional server override; default is intouch):
Content-Type: application/json
{
"publisher": "intouch",
"password": "your-password"
}
Response: { "sessionId": 1, "sessionToken": "1:4829371650284719", ... }
All subsequent API calls include the sessionToken (or sessionId) as a query parameter for authorization. API keys are an alternative — generate via POST /intouch/access/generate-api-key and revoke via /revoke-api-key.
Authorization Model
Multi-Tier Permissions
Read, create, update, delete, execute, and admin permission levels per resource.
Object-Level Security
Fine-grained access control on individual jobs, connections, and resources.
Group-Based Management
Assign permissions to groups, users inherit from group membership.
Session Controls
Configurable session timeouts, concurrent session limits, and audit logging.
HTTP Methods
| Method | Usage | Idempotent |
|---|---|---|
| GET | Retrieve resources | Yes |
| POST | Create resources, execute actions | No |
| PUT | Update existing resources | Yes |
| DELETE | Remove resources | Yes |
Response Codes
| Code | Meaning |
|---|---|
| 200 | Success — resource returned or action completed |
| 204 | Success — no content returned (delete operations) |
| 207 | Multi-status — partial success in batch operations |
| 400 | Bad request — invalid parameters or payload |
| 401 | Unauthorized — invalid or expired session |
| 403 | Forbidden — insufficient permissions |
| 404 | Not found — resource does not exist |
| 409 | Conflict — resource already exists or state conflict |
| 500 | Internal server error |
Integration Examples
Job Execution Workflow
Real endpoints from the live OpenAPI spec. Resource paths are kebab-cased; most lookups have by-id and by-name variants.
POST /intouch/access/login
# body: { "publisher": "intouch", "password": "..." }
# Step 2: Resolve job by fully-qualified name
GET /intouch/job/get-by-name?sessionId=$T&fqnJob=Default/Default/DailyETL
# Step 3: Run the job (returns 204 on success)
POST /intouch/job/run-job-by-names?sessionId=$T&fqnJobNames=Default/Default/DailyETL
# Step 4: List recent activity for the job
GET /intouch/job-activity/get-job-work-completed-from-days-ago?sessionId=$T&jobId=42&daysAgo=1
# Step 5: Pull log messages for the latest run
GET /intouch/job-activity/get-job-log-messages-for-last-execution?sessionId=$T&jobId=42
OneShot Ad-Hoc Execution
OneShot is the synchronous run-and-wait surface for ad-hoc job and task execution from REST clients, the AI assistant, or scripts. Returns a runId immediately, then poll status:
POST /intouch/oneshot/run-job?sessionId=$T
Content-Type: application/json
{
"fqnJob": "Default/Default/DailyETL",
"parameters": { "asOfDate": "2026-04-30" }
}
# Response: { "runId": 91240, "status": "running" }
# Poll for completion
GET /intouch/oneshot/status?sessionId=$T&runId=91240
# Or run a single task without a job wrapper
POST /intouch/oneshot/run-task?sessionId=$T
Content-Type: application/json
{
"taskType": "sql",
"credentialName": "warehouse",
"json": { "command": "SELECT count(*) FROM orders" }
}
Install a YAML Tool from Source
Content-Type: application/json
{
"name": "disk-space-check",
"yamlContent": "name: disk-space-check\\ninputs: ...",
"reload": true
}
# Hot-reload a single tool without server restart
POST /intouch/intouch-tool/reload/disk-space-check?sessionId=$T
Install a Skill from a SKILL.md
Content-Type: application/json
{
"name": "weekly-summary",
"markdown": "---\\nname: weekly-summary\\n---\\n..."
}
# Then invoke from any messaging channel: @weekly-summary
Performance
Micronaut Advantages
Compile-time dependency injection eliminates reflection overhead. Sub-second startup, minimal memory footprint, reactive non-blocking I/O.
Optimization Recommendations
Use batch operations for bulk changes, implement connection pooling, cache session IDs, use pagination for large result sets, prefer specific queries over broad searches.
Getting Started
API Access Points
API Base URL: http://[server]:[port]/intouch/
Swagger UI: http://[server]:[port]/swagger-ui
Quick Start Checklist
Setup
- Obtain InTouch server URL and port
- Get publisher credentials from admin
- Open Swagger UI to explore endpoints
- Test authentication with POST /access/login
Develop
- Download OpenAPI spec for code generation
- Import Postman collections for testing
- Implement authentication flow
- Build integration with your target platform
Development Tools
Postman
Pre-built collections for all API domains
Swagger Codegen
Auto-generate client libraries
curl
Command-line API testing
OpenAPI Generator
Enterprise client SDK generation
Best Practices
Security
- Use HTTPS in production
- Implement session timeout handling
- Follow least-privilege principle
- Rotate credentials regularly
- Log all API access for audit
- Validate all input parameters
Error Handling
- Check HTTP status codes on every response
- Handle 401 with automatic re-authentication
- Implement exponential backoff for retries
- Log error responses for debugging
- Handle 207 multi-status for batch ops
Performance
- Reuse sessions across requests
- Use batch operations for bulk changes
- Implement pagination for large datasets
- Cache frequently accessed resources
- Use specific queries over broad searches
Support Resources
Swagger UI
Interactive API documentation and testing
OpenAPI Spec
Download the full specification for code generation
Technical Support
Documentation
Start Building with the InTouch API
Standard REST. OpenAPI 3.0. Swagger UI. Everything you need to integrate.
Contact Technical Support View Business Overview