> ## 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.

# Input Validation

## Field Limits

The API enforces the following limits to ensure system stability:

### String Fields

| Field         | Min Length | Max Length | Pattern                          |
| :------------ | :--------- | :--------- | :------------------------------- |
| Server name   | 1          | 100        | Any characters                   |
| Description   | 0          | Unlimited  | Any characters                   |
| Connector ID  | 1          | Unlimited  | Any non-empty string             |
| Action ID     | 1          | Unlimited  | Any non-empty string             |
| User ID       | 1          | 10000      | Any non-empty string             |
| API Key       | 16         | Unlimited  | Alphanumeric, underscore, hyphen |
| Credential ID | 24         | 24         | MongoDB ObjectId (hex)           |

### Numeric Fields

| Field                 | Min Value | Max Value | Default |
| :-------------------- | :-------- | :-------- | :------ |
| Token expiration days | 1         | 365       | 90      |
| Request timeout (ms)  | 1000      | 300000    | 30000   |

### 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:

```json expandable theme={null}
{
  "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:

```json expandable theme={null}
{
  "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 Code               | Description                 | Solution                        |
| :----------------------- | :-------------------------- | :------------------------------ |
| `MISSING_REQUIRED_FIELD` | Required field not provided | Include all required fields     |
| `INVALID_FORMAT`         | Field format incorrect      | Check field format requirements |
| `VALUE_TOO_LONG`         | Exceeds maximum length      | Shorten the value               |
| `VALUE_TOO_SHORT`        | Below minimum length        | Provide longer value            |
| `DUPLICATE_VALUE`        | Value already exists        | Use unique value                |
| `INVALID_ENUM_VALUE`     | Not in allowed values       | Use one of the allowed values   |
| `INVALID_JSON`           | Malformed JSON              | Fix 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