# Route Management

**Page:** api/exec/routing

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

---

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



The Route Management API lets you inspect, discover, and test the URL routes that map to your script directory, manage imported SDK packages, and generate or validate user-defined OpenAPI specifications. Use these endpoints to debug routing behavior, onboard external SDKs, and produce machine-readable API documentation from your scripts.

## Route Management

### `POST /api/v1/exec/route/discover`

Discover all available routes in the script directory, classified by Next.js-style type. Scans for `.js` and `.ts` files and classifies each as: `static`, `dynamic` (`[param]`), `catch-all` (`[...slug]`), or `optional catch-all` (`[[...path]]`). Returns the route pattern, file path, type, and extracted parameter names for each route. Optionally includes file metadata (size, modification time) when `includeMetadata` is `true`.

#### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `baseDir` | string | No | `""` | Base directory to scan for routes. |
| `includeMetadata` | boolean | No | `false` | When `true`, includes file size and modification time for each route. |



```bash
curl -X POST https://api.example.com/api/v1/exec/route/discover \
  -H "Content-Type: application/json" \
  -d '{
    "baseDir": "scripts",
    "includeMetadata": true
  }'
```


```typescript
const result = await client.exec.route.discover({
  baseDir: "scripts",
  includeMetadata: true
});
```


```json
{
  "baseDir": "scripts",
  "count": 3,
  "routes": [
    {
      "pattern": "/api/users",
      "filePath": "scripts/default/api/users.ts",
      "type": "static",
      "params": []
    },
    {
      "pattern": "/api/users/[id]",
      "filePath": "scripts/default/api/users/[id].ts",
      "type": "dynamic",
      "params": ["id"]
    }
  ]
}
```


```json
{
  "error": "VALIDATION_ERROR",
  "code": "ERROR_400",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "details": {}
}
```

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


```json
{
  "error": "NOT_FOUND",
  "code": "ERROR_404",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "details": {}
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `NOT_FOUND` | Resource not found | The requested resource does not exist | Verify the resource identifier |


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



### `POST /api/v1/exec/route/resolve`

Resolve a URL path to the script file that handles it, using Next.js-style dynamic routing. Supports static routes, dynamic segments `[param]`, catch-all `[...slug]`, and optional catch-all `[[...path]]`. Routes are matched in priority order: static > dynamic > catch-all > optional catch-all. Scoped by hostname and execId: checks `{hostname}/{execId}/`, then `{hostname}/`, then `{execId}/`, then root. Returns the matched script path, extracted route parameters, and route type.

#### Request Body

This endpoint accepts a request payload. The request body schema is empty; the server derives the target URL, hostname, and execId from the request context.



```bash
curl -X POST https://api.example.com/api/v1/exec/route/resolve \
  -H "Content-Type: application/json" \
  -d '{}'
```


```typescript
const result = await client.exec.route.resolve({});
```


```json
{
  "matched": true,
  "path": "scripts/example.com/app-1/api/users/[id].ts",
  "hostname": "example.com",
  "execId": "app-1",
  "triedDirectories": [
    "scripts/example.com/app-1",
    "scripts/example.com",
    "scripts/app-1"
  ]
}
```


```json
{
  "error": "VALIDATION_ERROR",
  "code": "ERROR_400",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "details": {}
}
```

| 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": {}
}
```



### `POST /api/v1/exec/route/test`

Test multiple URL paths against the routing system in a single batch request. For each path, resolves which script would handle it using Next.js-style dynamic routing with the same priority and scoping rules as `resolveRoute`. Returns per-path match results with extracted parameters, plus aggregate `matched`/`notMatched` counts.

#### Request Body

This endpoint accepts a request payload. The request body schema is empty; provide the list of test paths in the request body according to the server contract.



```bash
curl -X POST https://api.example.com/api/v1/exec/route/test \
  -H "Content-Type: application/json" \
  -d '{}'
```


```typescript
const result = await client.exec.route.test({});
```


```json
{
  "tested": 2,
  "matched": 1,
  "notMatched": 1,
  "results": [
    {
      "path": "/api/users/42",
      "matched": true,
      "script": "scripts/default/api/users/[id].ts",
      "params": { "id": "42" },
      "type": "dynamic"
    },
    {
      "path": "/api/missing",
      "matched": false,
      "script": null,
      "params": {},
      "type": null
    }
  ]
}
```


```json
{
  "error": "VALIDATION_ERROR",
  "code": "ERROR_400",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "details": {}
}
```

| 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 Management

### `GET /api/v1/exec/sdk/:id`

Retrieve a single imported SDK by its identifier, including its source URL, on-disk path, marker, middleware files, and endpoint inventory.

#### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `id` | path | string | Yes | Id parameter |



```bash
curl https://api.example.com/api/v1/exec/sdk/stripe-v1
```


```typescript
const result = await client.exec.sdk.get("stripe-v1");
```


```json
{
  "id": "stripe-v1",
  "type": "sdk",
  "source_url": "https://github.com/stripe/stripe-node.git",
  "path": "scripts/sdks/stripe-v1",
  "marker": "STRIPE_SDK",
  "middleware": {
    "pre": {
      "exists": true,
      "path": "scripts/sdks/stripe-v1/middleware.pre.ts",
      "hash": "a1b2c3d4e5f67890"
    },
    "post": {
      "exists": false,
      "path": null,
      "hash": null
    }
  },
  "files": {
    "total": 42,
    "endpoints": 38,
    "list": [
      "scripts/sdks/stripe-v1/charges.ts",
      "scripts/sdks/stripe-v1/customers.ts"
    ]
  }
}
```


```json
{
  "error": "VALIDATION_ERROR",
  "code": "ERROR_400",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "details": {}
}
```

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


```json
{
  "error": "NOT_FOUND",
  "code": "ERROR_404",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "details": {}
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `NOT_FOUND` | Resource not found | The requested resource does not exist | Verify the resource identifier |


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



### `GET /api/v1/exec/sdk/list`

List all imported SDKs with summary metadata.

This endpoint takes no parameters.



```bash
curl https://api.example.com/api/v1/exec/sdk/list
```


```typescript
const result = await client.exec.sdk.list();
```


```json
{
  "sdks": [
    {
      "id": "stripe-v1",
      "source_url": "https://github.com/stripe/stripe-node.git",
      "files": 42,
      "middleware": {
        "pre": true,
        "post": false
      },
      "marker": "STRIPE_SDK"
    },
    {
      "id": "openai-v4",
      "source_url": "https://github.com/openai/openai-node.git",
      "files": 18,
      "middleware": {
        "pre": false,
        "post": true
      },
      "marker": "OPENAI_SDK"
    }
  ],
  "total": 2
}
```


```json
{
  "error": "VALIDATION_ERROR",
  "code": "ERROR_400",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "details": {}
}
```

| 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": {}
}
```



### `POST /api/v1/exec/sdk/import`

Import an SDK from a remote git source into the script directory, with optional pre- and post-middleware hooks and magic comments for the script generator.

#### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `execId` | string | Yes | — | Identifier for the target exec context. |
| `source_url` | string | Yes | — | Git URL of the SDK to import. |
| `source_auth` | string | No | — | Authentication string for private repositories. |
| `middleware` | string | No | — | Middleware configuration payload. |
| `magic_comments` | string | No | — | Magic comments to inject into generated scripts. |
| `force` | boolean | No | `false` | Re-import and overwrite when an SDK with the same marker already exists. |



```bash
curl -X POST https://api.example.com/api/v1/exec/sdk/import \
  -H "Content-Type: application/json" \
  -d '{
    "execId": "app-1",
    "source_url": "https://github.com/stripe/stripe-node.git",
    "source_auth": "ghp_exampleToken",
    "middleware": "auth",
    "force": false
  }'
```


```typescript
const result = await client.exec.sdk.importSDK({
  execId: "app-1",
  source_url: "https://github.com/stripe/stripe-node.git",
  source_auth: "ghp_exampleToken",
  middleware: "auth",
  force: false
});
```


```json
{
  "action": "imported",
  "summary": {
    "new": 42,
    "updated": 0,
    "conflicts": 0,
    "total": 42
  },
  "sdk": {
    "id": "stripe-v1",
    "source_url": "https://github.com/stripe/stripe-node.git",
    "path": "scripts/sdks/stripe-v1",
    "files": {
      "endpoints": 38,
      "pre": "scripts/sdks/stripe-v1/middleware.pre.ts",
      "post": "scripts/sdks/stripe-v1/middleware.post.ts",
      "marker": "STRIPE_SDK"
    }
  }
}
```


```json
{
  "error": "VALIDATION_ERROR",
  "code": "ERROR_400",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "details": {}
}
```

| 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": {}
}
```



### `DELETE /api/v1/exec/sdk/:id`

Delete an imported SDK, removing all of its generated files and the associated marker directory.

#### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `id` | path | string | Yes | Id parameter |



```bash
curl -X DELETE https://api.example.com/api/v1/exec/sdk/stripe-v1
```


```typescript
const result = await client.exec.sdk.delete("stripe-v1");
```


```json
{
  "message": "SDK deleted",
  "removed": {
    "marker": "STRIPE_SDK",
    "files": 42,
    "directory": "scripts/sdks/stripe-v1"
  }
}
```


```json
{
  "error": "VALIDATION_ERROR",
  "code": "ERROR_400",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "details": {}
}
```

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


```json
{
  "error": "NOT_FOUND",
  "code": "ERROR_404",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "details": {}
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `NOT_FOUND` | Resource not found | The requested resource does not exist | Verify the resource identifier |


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



## User OpenAPI

### `GET /api/v1/exec/user-openapi/list`

List available user scripts along with their detected schemas and route paths. Useful for inventorying which scripts are API endpoints, which carry a Zod/JSON schema, and which path parameters they expect.

#### Parameters

| Name | In | Type | Required | Default | Description |
|------|----|------|----------|---------|-------------|
| `directory` | query | string | No | `scripts` | Script directory to list (absolute or relative to `scripts-dir`). |
| `dir` | query | string | No | — | Alias of `directory`. Ignored when `directory` is provided. |
| `subdomain` | query | string | No | — | Limit scan to scripts under this subdomain. Falls back to the `Host` header when omitted. |
| `execId` | query | string | No | — | Limit scan to scripts under this `execId`. Falls back to the `Host` header when omitted. |



```bash
curl "https://api.example.com/api/v1/exec/user-openapi/list?directory=scripts&subdomain=example.com"
```


```typescript
const result = await client.exec.openapi.listScripts({
  directory: "scripts",
  subdomain: "example.com"
});
```


```json
{
  "success": true,
  "data": {
    "directory": "scripts",
    "totalScripts": 12,
    "withSchemas": 8,
    "scripts": [
      {
        "path": "scripts/default/api/users.ts",
        "routePath": "/api/users",
        "hasSchema": true,
        "schemaFormat": "zod",
        "pathParameters": []
      },
      {
        "path": "scripts/default/api/users/[id].ts",
        "routePath": "/api/users/[id]",
        "hasSchema": true,
        "schemaFormat": "zod",
        "pathParameters": ["id"]
      }
    ]
  }
}
```


```json
{
  "error": "VALIDATION_ERROR",
  "code": "ERROR_400",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "details": {}
}
```

| 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": {}
}
```



### `GET /api/v1/exec/user-openapi/schema`

Serve a single script's schema file directly, returning the raw Zod or JSON Schema definition as JSON.

#### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `file` | query | string | No | Absolute or `scripts-dir`-relative path to the target script (e.g. `default/api/users/[id].ts`). Either `file` or `path` must be provided. |
| `path` | query | string | No | Alias of `file`. Either `file` or `path` must be provided. |



```bash
curl "https://api.example.com/api/v1/exec/user-openapi/schema?file=default/api/users/%5Bid%5D.ts"
```


```typescript
const result = await client.exec.openapi.serveSchema({
  file: "default/api/users/[id].ts"
});
```


```json
{
  "type": "object",
  "properties": {
    "id": { "type": "string" },
    "email": { "type": "string", "format": "email" }
  },
  "required": ["id", "email"]
}
```


```json
{
  "error": "VALIDATION_ERROR",
  "code": "ERROR_400",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "details": {}
}
```

| 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": {}
}
```



### `GET /api/v1/exec/user-openapi/spec`

Generate and serve the full OpenAPI specification for the user scripts on-the-fly, combining the schema files of every script in the scanned directory. Output can be requested as JSON or YAML.

#### Parameters

| Name | In | Type | Required | Default | Description |
|------|----|------|----------|---------|-------------|
| `dir` | query | string | No | `scripts` | Script directory to scan (absolute or relative to `scripts-dir`). |
| `directory` | query | string | No | — | Alias of `dir`. Ignored when `dir` is provided. |
| `format` | query | string | No | `json` | Output format. `json` (default) or `yaml`. |
| `subdomain` | query | string | No | — | Limit scan to scripts under this subdomain. Falls back to the `Host` header when omitted. |
| `execId` | query | string | No | — | Limit scan to scripts under this `execId`. Falls back to the `Host` header when omitted. |



```bash
curl "https://api.example.com/api/v1/exec/user-openapi/spec?format=json&subdomain=example.com"
```


```typescript
const result = await client.exec.openapi.serve({
  format: "json",
  subdomain: "example.com"
});
```


```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "User Scripts API",
    "version": "1.0.0"
  },
  "paths": {
    "/api/users": {
      "get": {
        "summary": "List users",
        "responses": {
          "200": { "description": "OK" }
        }
      }
    },
    "/api/users/{id}": {
      "get": {
        "summary": "Get user by id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ]
      }
    }
  }
}
```


```json
{
  "error": "VALIDATION_ERROR",
  "code": "ERROR_400",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "details": {}
}
```

| 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": {}
}
```



### `POST /api/v1/exec/user-openapi/generate`

Generate the OpenAPI specification for the user scripts and return it inline in the response body, along with metadata about the scan (path count, scan directory, generation timestamp).

#### Request Body

This endpoint accepts a request payload. The request body schema is empty; supply scan options (e.g. `directory`, `subdomain`, `execId`) in the request body according to the server contract.



```bash
curl -X POST https://api.example.com/api/v1/exec/user-openapi/generate \
  -H "Content-Type: application/json" \
  -d '{}'
```


```typescript
const result = await client.exec.openapi.generate({});
```


```json
{
  "success": true,
  "data": {
    "openapi": "3.1.0",
    "info": { "title": "User Scripts API", "version": "1.0.0" },
    "paths": {}
  },
  "meta": {
    "pathCount": 12,
    "scanDirectory": "scripts",
    "generatedAt": "2025-01-15T12:34:56.789Z"
  }
}
```


```json
{
  "error": "VALIDATION_ERROR",
  "code": "ERROR_400",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "details": {}
}
```

| 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": {}
}
```



### `POST /api/v1/exec/user-openapi/merge`

Merge multiple OpenAPI specifications into a single combined document, returning the merged result.

#### Request Body

This endpoint accepts a request payload. The request body schema is empty; supply the list of specs to merge in the request body according to the server contract.



```bash
curl -X POST https://api.example.com/api/v1/exec/user-openapi/merge \
  -H "Content-Type: application/json" \
  -d '{}'
```


```typescript
const result = await client.exec.openapi.merge({});
```


```json
{
  "success": true,
  "data": {
    "openapi": "3.1.0",
    "info": { "title": "Merged API", "version": "1.0.0" },
    "paths": {
      "/api/users": { "get": { "summary": "List users" } },
      "/api/orders": { "get": { "summary": "List orders" } }
    }
  }
}
```


```json
{
  "error": "VALIDATION_ERROR",
  "code": "ERROR_400",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "details": {}
}
```

| 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": {}
}
```



### `POST /api/v1/exec/user-openapi/validate`

Validate a single script's schema file, returning whether the schema is well-formed and a list of validation errors when it is not.

#### Request Body

This endpoint accepts a request payload. The request body schema is empty; supply the script path to validate in the request body according to the server contract.



```bash
curl -X POST https://api.example.com/api/v1/exec/user-openapi/validate \
  -H "Content-Type: application/json" \
  -d '{}'
```


```typescript
const result = await client.exec.openapi.validateSchema({});
```


```json
{
  "success": true,
  "data": {
    "path": "scripts/default/api/users.ts",
    "format": "zod",
    "fields": ["id", "email", "name"]
  },
  "errors": []
}
```


```json
{
  "error": "VALIDATION_ERROR",
  "code": "ERROR_400",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "details": {}
}
```

| 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": {}
}
```