Route Management

Download Page (.md)

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.

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

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

{
  "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"]
    }
  ]
}

{
  "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

{
  "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

{
  "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.

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

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

{
  "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"
  ]
}

{
  "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

{
  "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.

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

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

{
  "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
    }
  ]
}

{
  "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

{
  "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

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

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

{
  "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"
    ]
  }
}

{
  "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

{
  "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

{
  "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.

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

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

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

{
  "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

{
  "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.

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
  }'

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
});

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

{
  "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

{
  "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

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

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

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

{
  "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

{
  "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

{
  "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.

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

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

{
  "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"]
      }
    ]
  }
}

{
  "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

{
  "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.

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

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

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

{
  "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

{
  "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.

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

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

{
  "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" }
          }
        ]
      }
    }
  }
}

{
  "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

{
  "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.

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

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

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

{
  "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

{
  "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.

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

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

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

{
  "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

{
  "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.

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

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

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

{
  "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

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