API Reference

RTILA X exposes a REST API that allows external systems to interact with your automations programmatically. This API reference documents all available endpoints, authentication methods, and request/response formats.

The RTILA X API is built on PocketBase, a lightweight backend framework. The API runs on http://127.0.0.1:8880 by default (or on your public tunnel URL if enabled).

API Base URL

Mode	Base URL
Local (default)	http://127.0.0.1:8880
Public Tunnel	https://<random>.trycloudflare.com

All API endpoints are relative to this base URL.

Authentication

Most API endpoints require authentication. RTILA X uses PocketBase’s authentication system.

Authentication Methods

Method	Description	Use Case
Session Token	A JWT token obtained by logging in. Sent in the Authorization header.	User-authenticated requests
Superuser Token	A special token for administrative operations.	Administrative operations
API Key	A project-specific key for remote execution.	Triggering project runs remotely

Obtaining a Session Token

To authenticate with the API, you need to log in first:

curl -X POST 'http://127.0.0.1:8880/api/collections/users/auth-with-password' \
  -H "Content-Type: application/json" \
  -d '{
    "identity": "your-email@example.com",
    "password": "your-password"
  }'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "record": {
    "id": "user123",
    "email": "your-email@example.com",
    "name": "Your Name"
  }
}

Use the returned token in subsequent requests:

curl -X GET 'http://127.0.0.1:8880/api/collections/projects/records' \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Health Check Endpoint

GET /api/health

Checks if the RTILA X backend is running and responsive.

Request:

curl -X GET 'http://127.0.0.1:8880/api/health'

Response (200 OK):

{
  "code": 200,
  "message": "API is healthy."
}

Use Cases:

• Verify RTILA X is running before making API calls.
• Health monitoring for external systems.
• Pre-flight check before triggering automations.

Remote Execution Endpoint

POST /api/remote

Triggers a project run remotely. This is the primary endpoint for external systems to trigger RTILA X automations.

Request:

curl -X POST 'http://127.0.0.1:8880/api/remote' \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_PROJECT_API_KEY",
    "variables": {
      "query": "web scraping",
      "max_pages": 10
    }
  }'

Request Body:

Field	Type	Required	Description
api_key	string	✅ Yes	The project’s API key. Found in the project’s Remote settings.
variables	object	No	Variables to pass to the project. Overrides project defaults.
target_type	string	No	Set to "trigger_chain" to trigger a trigger chain instead of a project.

Response (200 OK):

{
  "message": "Project execution queued",
  "queue_id": "queue_record_id",
  "status": "pending"
}

Error Responses:

Status Code	Error	Description
400	Missing api_key	No API key provided
401	Invalid API key	API key doesn’t match
403	Project not found or remote disabled	Project doesn’t exist or remote execution is disabled
409	Already running	A run is already in progress

Example with variables:

curl -X POST 'http://127.0.0.1:8880/api/remote' \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "abc123-def456-ghi789",
    "variables": {
      "search_term": "wireless headphones",
      "max_pages": 5,
      "output_format": "csv"
    }
  }'

Example triggering a trigger chain:

curl -X POST 'http://127.0.0.1:8880/api/remote' \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "chain_api_key_here",
    "target_type": "trigger_chain",
    "variables": {
      "data_source": "daily_scrape"
    }
  }'

Webhook Receiver Endpoint

POST /api/rtila/webhook/{chain_id}

Receives webhook requests and triggers a trigger chain. This endpoint is used by external services to trigger trigger chains.

Request:

curl -X POST 'http://127.0.0.1:8880/api/rtila/webhook/chain_abc123' \
  -H "X-Api-Key: YOUR_CHAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_payload": {
      "event": "new_order",
      "order_id": "12345"
    }
  }'

Request Headers:

Header	Required	Description
X-Api-Key	✅ Yes	The trigger chain’s API key
Content-Type	✅ Yes	Must be application/json
X-Webhook-Signature	If configured	HMAC-SHA256 signature for verification

Response (202 Accepted):

{
  "run_id": "run_abc123",
  "queue_id": "queue_xyz789",
  "status": "queued"
}

See Webhook Triggers for complete documentation.

PocketBase API Overview

RTILA X uses PocketBase as its backend database. The full PocketBase API is available for advanced integrations. PocketBase provides a RESTful API for CRUD operations on all collections.

API Structure

All PocketBase API endpoints follow this pattern:

GET    /api/collections/{collection}/records          # List records
GET    /api/collections/{collection}/records/{id}     # Get a specific record
POST   /api/collections/{collection}/records          # Create a record
PATCH  /api/collections/{collection}/records/{id}     # Update a record
DELETE /api/collections/{collection}/records/{id}     # Delete a record

Authentication

All PocketBase API requests require an Authorization header with a valid JWT token:

Authorization: Bearer YOUR_JWT_TOKEN

Available Collections

RTILA X uses the following PocketBase collections:

Collection	Description	Key Fields
projects	Automation projects	name, content, folder, created_by_assistant
sessions	Execution sessions	project, status, startTime, endTime, checkpoint
logs	Execution logs	session, level, message
notifications	User notifications	owner, title, message, type
chats	AI chat conversations	title, project, project_examples_count
messages	Chat messages	chat, role, content, attachments
schedulers	Scheduled tasks	project, schedule_type, interval, enabled
queue	Job queue	type, status, args, project, session
users	User profiles	name, email, license, protected
licenses	License records	key, status, deal_id, activation_url
machines	Machine activations	license, unique_id, target
browser_profiles	Browser profiles	owner, name, proxyEnabled, captchaEnabled
global_variables	Global variables	owner, name, value, is_secure
bots	Standalone bots	owner, project, name, snips_id, active
trigger_chains	Trigger chains	owner, name, triggers, status
trigger_chain_runs	Trigger chain runs	trigger_chain, status, triggered_by
trigger_chain_schedules	Trigger chain schedules	trigger_chain, schedule_type, enabled
project_history	Project version history	project, content
audit_logs	Audit trail	user, event, collection, record_id

Example API Requests

List all projects:

curl -X GET 'http://127.0.0.1:8880/api/collections/projects/records' \
  -H "Authorization: Bearer YOUR_TOKEN"

Get a specific project:

curl -X GET 'http://127.0.0.1:8880/api/collections/projects/records/PROJECT_ID' \
  -H "Authorization: Bearer YOUR_TOKEN"

List sessions for a project:

curl -X GET 'http://127.0.0.1:8880/api/collections/sessions/records?filter=project%3D%27PROJECT_ID%27' \
  -H "Authorization: Bearer YOUR_TOKEN"

Get notifications:

curl -X GET 'http://127.0.0.1:8880/api/collections/notifications/records?filter=owner%3D%27USER_ID%27&sort=-created' \
  -H "Authorization: Bearer YOUR_TOKEN"

Query Parameters

PocketBase supports these query parameters for list endpoints:

Parameter	Description	Example
page	Page number (1-based)	?page=2
perPage	Records per page	?perPage=50
filter	Filter expression	?filter=status%3D%27completed%27
sort	Sort field (prefix - for descending)	?sort=-created
expand	Expand related records	?expand=project

Filter Syntax

PocketBase uses a special filter syntax:

filter=status='completed' && project='PROJECT_ID'

URL-encoded:

filter=status%3D%27completed%27%20%26%26%20project%3D%27PROJECT_ID%27

Realtime Subscriptions

PocketBase supports Server-Sent Events (SSE) for real-time updates. RTILA X uses this internally for the job executor.

Subscribe to Collection Changes

curl -X GET 'http://127.0.0.1:8880/api/realtime' \
  -H "Authorization: Bearer YOUR_TOKEN"

This returns an SSE stream. You can subscribe to specific collections:

{
  "clientId": "CLIENT_ID",
  "subscriptions": ["queue?expand=scheduler"]
}

Error Response Format

All API errors return a consistent format:

{
  "code": 404,
  "message": "The requested resource wasn't found.",
  "data": {}
}

Status Code	Description
400	Bad Request — Invalid request parameters
401	Unauthorized — Invalid or missing authentication
403	Forbidden — Insufficient permissions
404	Not Found — Resource doesn’t exist
409	Conflict — Resource already exists or is in use
500	Internal Server Error — Server-side error

API Rate Limiting

RTILA X supports API rate limiting to prevent abuse. Rate limits are configured in the Administration panel under Rate Limiting.

Rule	Default	Description
Authentication requests	100 per minute	Limits login attempts
Resource creation	100 per minute	Limits record creation
Batch API	50 per minute	Limits batch operations
General API	500 per minute	General API request limit

API Security Best Practices

Practice	Why It Matters
Use HTTPS for remote access	The public tunnel uses HTTPS. Always use it for remote access.
Use session tokens, not passwords	Session tokens expire. Passwords don’t.
Rotate API keys regularly	Reduces the risk of compromised keys.
Use least-privilege permissions	Grant only the minimum permissions needed.
Monitor API access	Check audit logs for unauthorized access attempts.
Use environment variables for credentials	Don’t hardcode credentials in scripts.
Validate all inputs	Sanitize user-provided data before using it in API calls.