Developer & AI ready

CloudSignal is built for developers who want to integrate real-time messaging without learning a proprietary framework. Every operation available in the dashboard is also available through the API, SDKs, and CLI - and all of them are structured for straightforward use by both humans and AI coding agents.

REST API

The API follows standard REST conventions with JSON payloads, predictable endpoints, and standard HTTP status codes. If your tools can make HTTP requests, they can manage your CloudSignal infrastructure.

# Create an MQTT user
curl -X POST https://api.cloudsignal.io/v2/users \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{"username": "agent-01", "password": "secure-password"}'

# Publish a message (no MQTT connection needed)
curl -X POST https://api.cloudsignal.io/v2/publish \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{"topic": "agents/agent-01/inbox", "payload": "{\"task\": \"summarize-thread\"}", "qos": 1}'

# List active sessions
curl https://api.cloudsignal.io/v2/sessions \
  -H "Authorization: Bearer sk_your_secret_key"

What you can do

Authentication

All API requests use a secret key in the Authorization header:

Authorization: Bearer sk_your_secret_key_here

Secret keys use the sk_ prefix and provide full access to your organization's resources. Keep them server-side - never in client code.

Server-side publishing

One of the most practical API features: publish messages to MQTT topics without maintaining a broker connection. Your backend sends an HTTP POST and the broker delivers the message to all matching subscribers.

This is useful for:

• Sending commands to devices from a web application
• Broadcasting notifications from a background job
• Injecting test messages during development
• Triggering workflows from webhooks or cron jobs

No MQTT library, no persistent connection, no connection management. One HTTP call.

SDKs

JavaScript / TypeScript

Connect from Node.js, browsers, or any JavaScript runtime:

import { CloudSignalClient } from '@cloudsignal/sdk'

const client = new CloudSignalClient({
  host: 'mqtt.cloudsignal.app',
  username: 'agent-01@org_k7xm4pqr2n5t',
  password: 'your-password',
})

// Subscribe and handle messages
client.subscribe('agents/+/state', (topic, message) => {
  console.log(`${topic}: ${message}`)
})

// Publish
client.publish('agents/agent-01/state', JSON.stringify({
  status: 'idle',
  load: 0.12,
}), { qos: 1 })

Python

Connect from backend services, data pipelines, or scripts:

from cloudsignal import CloudSignalClient

client = CloudSignalClient(
    host="mqtt.cloudsignal.app",
    username="agent-01@org_k7xm4pqr2n5t",
    password="your-password",
)

# Subscribe
@client.on_message("agents/+/state")
def handle_state(topic, payload):
    print(f"{topic}: {payload}")

# Publish
client.publish(
    "agents/agent-01/state",
    {"status": "idle", "load": 0.12},
    qos=1,
)

client.connect()

Both SDKs handle connection management, automatic reconnection, and credential handling. They are thin wrappers around standard MQTT clients with CloudSignal-specific defaults built in.

CLI

The CloudSignal CLI lets you manage your infrastructure from the terminal - useful for scripting, CI/CD pipelines, and quick operations without opening the dashboard.

# Authenticate
cloudsignal auth login

# Manage users
cloudsignal users list
cloudsignal users create --username agent-01 --password secure-pw

# Manage ACL rules
cloudsignal acl list
cloudsignal acl create --topic "agents/{username}/#" --action publish --permission allow

# Publish a message
cloudsignal publish --topic "test/hello" --message "Hello from CLI"

# View sessions
cloudsignal sessions list

CI/CD integration

The CLI authenticates with API keys, so you can automate infrastructure management in deployment pipelines:

# In your deployment script
cloudsignal users create \
  --username "service-${DEPLOY_ENV}" \
  --password "${MQTT_PASSWORD}" \
  --acl-set "backend-services"

AI agent compatibility

Every interface - API, SDKs, CLI - is structured for use with AI coding agents. This is not an afterthought; it is a design principle:

Predictable, RESTful API - AI agents that can make HTTP requests can manage CloudSignal resources. Standard REST patterns mean agents do not need CloudSignal-specific training to use the API effectively.

Self-documenting CLI - Commands follow noun verb patterns with --help on every subcommand. Agents can discover available operations by exploring the help tree.

Typed SDKs - TypeScript definitions and Python type hints give AI agents full parameter and return type information. Code completion and type checking work out of the box.

JSON everywhere - API responses, CLI output (with --json flag), and SDK payloads all use JSON. No custom serialization formats to parse.

An AI coding agent (Claude, Cursor, Copilot, and similar) typically reaches for CloudSignal in three ways:

• REST API directly for one-off operations and lookups
• SDK when generating client or server code
• CLI for quick infrastructure tasks during development

Error handling

The API uses standard HTTP status codes with descriptive JSON error bodies:

Rate limits are per-organization and returned in response headers. Multiple API keys within the same organization share the same rate limit pool.

Next steps

• API keys guide - Generate and manage API keys
• CLI documentation - Full CLI reference and authentication setup
• Connect from JavaScript - Get connected in under five minutes
• SDK catalog - Official @cloudsignal/* packages plus recommended clients for Python, Go, Rust, Java, and .NET