# Code Validation

**Page:** api/exec/validation

[Download Raw Markdown](./api/exec/validation.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



# Code Validation

Validate script source code across multiple dimensions: syntax, TypeScript transpilation, runtime dependencies, magic comments, and return type conformance. Use these endpoints to lint user-submitted scripts before execution, surface dependency gaps, or extract structured metadata from inline annotations.

All endpoints accept a JSON body containing the source code (and optionally a type definition and value), and return structured validation results.

---

## Validate Script

`POST /api/v1/exec/validate/script`

Run a full validation pass against a script: syntax check, TypeScript transpilation, dependency inspection, and magic comment parsing — all in one call.

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `code` | string | Yes | Code |

### Response



```json
{
  "valid": true,
  "results": {
    "syntax": {
      "valid": true,
      "message": "JavaScript syntax is valid"
    },
    "typescript": {
      "valid": true,
      "transpiledLength": 1248
    },
    "dependencies": {
      "total": 3,
      "installed": 2,
      "missing": 1,
      "missingModules": ["lodash"],
      "allInstalled": false
    },
    "magicComments": {
      "endpoint": "GET /users"
    },
    "normalized": true,
    "transformations": ["trim", "stripBom"]
  },
  "message": "Script validation completed"
}
```


```json
{
  "error": "VALIDATION_ERROR",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "details": {
    "field": "code",
    "issue": "must be a non-empty string"
  }
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `VALIDATION_ERROR` | Invalid input | Request parameters failed validation | Check parameter format and requirements |


```json
{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "details": {}
}
```



### SDK

```ts
const result = await client.exec.validate.validateScript({
  data: {
    code: "import _ from 'lodash';\nexport default function() { return _.range(1, 10); }"
  }
});
```

---

## Validate Syntax

`POST /api/v1/exec/validate/syntax`

Check that a script is syntactically valid JavaScript. Returns the normalized form and any transformations applied during normalization.

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `code` | string | Yes | Code |

### Response



```json
{
  "valid": true,
  "message": "JavaScript syntax is valid",
  "codeLength": 1024,
  "normalized": true,
  "transformations": ["trim", "stripBom", "stripShebang"]
}
```


```json
{
  "error": "VALIDATION_ERROR",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "details": {
    "field": "code",
    "issue": "must be a non-empty string"
  }
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `VALIDATION_ERROR` | Invalid input | Request parameters failed validation | Check parameter format and requirements |


```json
{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "details": {}
}
```



### SDK

```ts
const result = await client.exec.validate.validateSyntax({
  data: {
    code: "function add(a, b) { return a + b; }"
  }
});
```

---

## Validate TypeScript

`POST /api/v1/exec/validate/typescript`

Transpile TypeScript source to JavaScript and verify the transpilation succeeds. Returns the generated JavaScript output and a list of normalization transformations.

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `code` | string | Yes | Code |

### Response



```json
{
  "valid": true,
  "javascript": "function add(a, b) { return a + b; }",
  "originalLength": 1280,
  "transpiledLength": 960,
  "normalized": true,
  "transformations": ["trim", "stripBom", "stripTypeAnnotations"],
  "message": "TypeScript validation successful"
}
```


```json
{
  "error": "VALIDATION_ERROR",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "details": {
    "field": "code",
    "issue": "must be a non-empty string"
  }
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `VALIDATION_ERROR` | Invalid input | Request parameters failed validation | Check parameter format and requirements |


```json
{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "details": {}
}
```



### SDK

```ts
const result = await client.exec.validate.validateTypeScript({
  data: {
    code: "interface User { id: number; name: string; }\nfunction greet(u: User) { return u.name; }"
  }
});
```

---

## Validate Dependencies

`POST /api/v1/exec/validate/dependencies`

Inspect a script for `import` statements and `require()` calls, then report which modules are missing from the runtime environment. Useful for surfacing installation requirements before execution.

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `code` | string | Yes | Code |

### Response



```json
{
  "totalModules": 4,
  "allInstalled": false,
  "missingCount": 1,
  "missingModules": ["axios"],
  "dependencies": [
    { "module": "lodash", "installed": true },
    { "module": "axios", "installed": false },
    { "module": "fs", "installed": true },
    { "module": "path", "installed": true }
  ],
  "message": "1 module is missing",
  "installCommand": "npm install axios"
}
```


```json
{
  "error": "VALIDATION_ERROR",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "details": {
    "field": "code",
    "issue": "must be a non-empty string"
  }
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `VALIDATION_ERROR` | Invalid input | Request parameters failed validation | Check parameter format and requirements |


```json
{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "details": {}
}
```



### SDK

```ts
const result = await client.exec.validate.validateDependencies({
  data: {
    code: "import axios from 'axios';\nimport _ from 'lodash';\nexport default async function() { return _.head(await axios.get('https://api.example.com')); }"
  }
});
```

---

## Validate Magic Comments

`POST /api/v1/exec/validate/magic-comments`

Parse inline magic comments (e.g. `/* endpoint: ... */`, `/* timeout: ... */`) and the declared return type from a script. Returns the structured metadata extracted from annotations.

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `code` | string | Yes | Code |

### Response



```json
{
  "magicComments": {
    "endpoint": "POST /orders",
    "timeout": 5000,
    "schedule": "0 */6 * * *"
  },
  "returnType": {
    "definition": "{ orderId: string, status: 'pending' | 'confirmed' }",
    "mode": "strict",
    "location": "line 3, column 18"
  },
  "message": "Magic comments parsed successfully"
}
```


```json
{
  "error": "VALIDATION_ERROR",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "details": {
    "field": "code",
    "issue": "must be a non-empty string"
  }
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `VALIDATION_ERROR` | Invalid input | Request parameters failed validation | Check parameter format and requirements |


```json
{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "details": {}
}
```



### SDK

```ts
const result = await client.exec.validate.validateMagicComments({
  data: {
    code: "/* endpoint: POST /orders */\n/* timeout: 5000 */\n/** @returns {{ orderId: string, status: 'pending' | 'confirmed' }} */\nexport default function() { return { orderId: 'abc', status: 'pending' }; }"
  }
});
```

---

## Validate Return Type

`POST /api/v1/exec/validate/return-type`

Verify that a JSON value conforms to a declared TypeScript-style type definition. Returns whether the value matches, a list of validation errors (if any), and a parsed representation of the type.

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `typeDefinition` | string | Yes | Type Definition |
| `value` | object | Yes | Arbitrary JSON value to validate against the declared return type |

### Response



```json
{
  "valid": true,
  "errors": [],
  "typeDefinition": "{ id: number, name: string, tags: string[] }",
  "parsedType": {
    "kind": "object",
    "properties": {
      "id": { "kind": "primitive", "type": "number" },
      "name": { "kind": "primitive", "type": "string" },
      "tags": { "kind": "array", "element": { "kind": "primitive", "type": "string" } }
    }
  },
  "message": "Value conforms to declared return type"
}
```


```json
{
  "error": "VALIDATION_ERROR",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "details": {
    "field": "typeDefinition",
    "issue": "must be a non-empty string"
  }
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `VALIDATION_ERROR` | Invalid input | Request parameters failed validation | Check parameter format and requirements |


```json
{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "details": {}
}
```



### SDK

```ts
const result = await client.exec.validate.validateReturnType({
  data: {
    typeDefinition: "{ id: number, name: string, tags: string[] }",
    value: { id: 42, name: "ada", tags: ["admin", "user"] }
  }
});
```