Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.runalloy.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Field Limits

The API enforces the following limits to ensure system stability:

​
String Fields

FieldMin LengthMax LengthPattern
Server name1100Any characters
Description0UnlimitedAny characters
Connector ID1UnlimitedAny non-empty string
Action ID1UnlimitedAny non-empty string
User ID110000Any non-empty string
API Key16UnlimitedAlphanumeric, underscore, hyphen
Credential ID2424MongoDB ObjectId (hex)

​
Numeric Fields

FieldMin ValueMax ValueDefault
Token expiration days136590
Request timeout (ms)100030000030000

​
Request Limits

  • Request body size: 10MB maximum
  • Rate limit: 100 requests per minute per IP address

​
Input Requirements

​
Server Creation

Required fields:
  • name: Unique per user
Optional fields with defaults:
  • description: empty string
  • tokenExpiresInDays: no expiration
  • restrictions:
  • isPublic: false

​
Action Execution

Required fields:
  • connectorId: Valid connector identifier (non-empty string)
  • actionId: Valid action for the connector (non-empty string)
  • parameters: Action-specific parameters (object)
Optional fields:
  • credentialId: 24-character MongoDB ObjectId for specific credential
  • timeout: Custom timeout in milliseconds

​
Validation Rules

​
Server Names

  • Must be unique per user
  • Cannot be empty or whitespace only
  • Special characters allowed: spaces, hyphens, underscores
  • Cannot start or end with whitespace
Valid examples: 
"My Production Server"
"test-server-01"
"Customer_Support_Bot"
Invalid examples: 
"" (empty)
"  " (whitespace only)
"server@123" (invalid character @)
"my-server-" (trailing hyphen)

​
API Keys

  • Must be at least 16 characters
  • Alphanumeric characters, underscores, and hyphens allowed
  • Case-sensitive
  • JWT tokens are also accepted as API keys

​
User IDs

  • Must be a non-empty string
  • Maximum 10,000 characters
  • Any format accepted (MongoDB ObjectId, UUID, custom ID)
Valid examples: 
682a9d8bf35534170bcb457b  // MongoDB ObjectId
user_xyz789                // Custom ID
550e8400-e29b-41d4-a716    // UUID

​
Restrictions

Restrictions must follow specific schemas: 
{
  "connectors": {
    "mode": "allowlist" | "blocklist",
    "allowedIds": ["string"],     // Use with allowlist mode
    "blockedIds": ["string"]      // Use with blocklist mode
  },
  "actions": {
    "mode": "allowlist" | "blocklist",
    "allowedActions": ["string"], // Use with allowlist mode
    "blockedActions": ["string"]  // Use with blocklist mode
  },
  "users": {
    "mode": "allowlist" | "blocklist",
    "allowedIds": ["string"],     // Use with allowlist mode
    "blockedIds": ["string"]      // Use with blocklist mode
  }
}
Note: Provide either allowedIds/allowedActions OR blockedIds/blockedActions based on the mode, not both.

​
Validation Errors

When validation fails, you’ll receive a 400 Bad Request with details: 
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "field": "name",
      "constraint": "maxLength",
      "value": 100,
      "message": "Server name must not exceed 100 characters"
    }
  }
}

​
Common Validation Errors

Error CodeDescriptionSolution
MISSING_REQUIRED_FIELDRequired field not providedInclude all required fields
INVALID_FORMATField format incorrectCheck field format requirements
VALUE_TOO_LONGExceeds maximum lengthShorten the value
VALUE_TOO_SHORTBelow minimum lengthProvide longer value
DUPLICATE_VALUEValue already existsUse unique value
INVALID_ENUM_VALUENot in allowed valuesUse one of the allowed values
INVALID_JSONMalformed JSONFix JSON syntax

​
Type Coercion

The API performs automatic type coercion where safe:
  • Strings to numbers: “100” → 100
  • Numbers to strings: 123 → “123”
  • Booleans: “true”/“false” → true/false
No coercion for:
  • Arrays and objects
  • Null values
  • Undefined values

​
Security Validation

Additional security checks:

​
Input Sanitization

  • All user inputs are validated using Zod schemas
  • Server IDs are generated from names with sanitization
  • Special characters in names are converted to hyphens

​
Best Practices

  1. Validate on client side for better UX
  2. Handle validation errors gracefully
  3. Use appropriate field types in requests
  4. Respect field limits to avoid truncation
  5. Sanitize user input before sending
  6. Implement retry logic for validation errors