Route Management

Route Management provides operations for inspecting and managing your project’s script routing layer. Use these endpoints to discover and resolve URL paths to handler scripts, generate OpenAPI specifications from user scripts, validate schema files, and manage imported SDKs.

Note

All endpoints on this page are scoped to a single execution container. The base URL is container-specific and follows the template https://{projectId}-{containerId}-exec-1.{server}.containers.hoody.icu. Substitute your project’s identifiers in every request.

SDK Management

Import, list, inspect, and remove SDKs that the routing layer can integrate with.

GET /api/v1/exec/sdk/list

Returns every SDK registered with the routing layer, including file count and middleware presence.

This endpoint takes no parameters.

cURL

curl -X GET "https://acme-prod-abc123-exec-1.eu-west-1.containers.hoody.icu/api/v1/exec/sdk/list"

SDK

await client.exec.sdk.list();

Response

200

{
  "sdks": [
    {
      "id": "sdk_a1b2c3d4e5f6",
      "source_url": "https://github.com/acme/sdk-repo",
      "files": 12,
      "middleware": {
        "pre": true,
        "post": false
      },
      "marker": "// @hoody:sdk:marker"
    }
  ],
  "total": 1
}

400

{
  "error": "Invalid request",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {}
}

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

500

{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {}
}

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

Returns a single SDK by its identifier, including source metadata, middleware status, and file inventory.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	SDK identifier

cURL

curl -X GET "https://acme-prod-abc123-exec-1.eu-west-1.containers.hoody.icu/api/v1/exec/sdk/sdk_a1b2c3d4e5f6"

SDK

await client.exec.sdk.get("sdk_a1b2c3d4e5f6");

Response

200

{
  "id": "sdk_a1b2c3d4e5f6",
  "type": "sdk",
  "source_url": "https://github.com/acme/sdk-repo",
  "path": "/scripts/sdk/sdk_a1b2c3d4e5f6",
  "marker": "// @hoody:sdk:marker",
  "middleware": {
    "pre": {
      "exists": true,
      "path": "/scripts/sdk/sdk_a1b2c3d4e5f6/_middleware.pre.ts",
      "hash": "a1b2c3d4e5f67890"
    },
    "post": {
      "exists": false,
      "path": null,
      "hash": null
    }
  },
  "files": {
    "total": 12,
    "endpoints": 8,
    "list": []
  }
}

400

{
  "error": "Invalid request",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {}
}

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

404

{
  "error": "SDK not found",
  "code": "NOT_FOUND",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {}
}

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

500

{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {}
}

POST /api/v1/exec/sdk/import

Imports an SDK from a remote source URL into the routing layer, downloading and indexing its files.

This endpoint takes no parameters.

Request Body

Field	Type	Required	Default	Description
execId	string	Yes	-	Identifier of the execution container the SDK is imported into
source_url	string	Yes	-	Remote URL of the SDK repository or tarball
source_auth	string	No	-	Optional authentication header or token for the source
middleware	string	No	-	Middleware configuration for the imported SDK
magic_comments	string	No	-	Magic comment directives applied during import
force	boolean	No	false	Force re-import when the SDK already exists

cURL

curl -X POST "https://acme-prod-abc123-exec-1.eu-west-1.containers.hoody.icu/api/v1/exec/sdk/import" \
  -H "Content-Type: application/json" \
  -d '{
    "execId": "exec-1",
    "source_url": "https://github.com/acme/sdk-repo",
    "force": false
  }'

SDK

await client.exec.sdk.importSDK({
  execId: "exec-1",
  source_url: "https://github.com/acme/sdk-repo",
  force: false
});

Response

200

{
  "action": "imported",
  "summary": {
    "new": 5,
    "updated": 2,
    "conflicts": 0,
    "total": 7
  },
  "sdk": {
    "id": "sdk_a1b2c3d4e5f6",
    "source_url": "https://github.com/acme/sdk-repo",
    "path": "/scripts/sdk/sdk_a1b2c3d4e5f6",
    "files": {
      "endpoints": 8,
      "pre": "_middleware.pre.ts",
      "post": "_middleware.post.ts",
      "marker": "_marker.ts"
    }
  }
}

400

{
  "error": "Invalid request payload",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {}
}

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

500

{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {}
}

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

Removes an SDK from the routing layer, deleting its marker and all associated files.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	SDK identifier

cURL

curl -X DELETE "https://acme-prod-abc123-exec-1.eu-west-1.containers.hoody.icu/api/v1/exec/sdk/sdk_a1b2c3d4e5f6"

SDK

await client.exec.sdk.delete("sdk_a1b2c3d4e5f6");

Response

200

{
  "message": "SDK deleted",
  "removed": {
    "marker": "// @hoody:sdk:marker",
    "files": 12,
    "directory": "/scripts/sdk/sdk_a1b2c3d4e5f6"
  }
}

400

{
  "error": "Invalid request",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {}
}

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

404

{
  "error": "SDK not found",
  "code": "NOT_FOUND",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {}
}

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

500

{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {}
}

Route Resolution

Resolve URL paths to handler scripts and batch-test routing behavior. All three endpoints use Next.js-style dynamic routing (static, [param], [...slug], [[...path]]) with priority static > dynamic > catch-all > optional catch-all.

POST /api/v1/exec/route/discover

Scans a script directory for .js and .ts files and returns every route pattern, classified by Next.js-style type. Each entry includes the route pattern, file path, route type, and extracted parameter names. Set includeMetadata to also receive file size and modification time.

This endpoint takes no parameters.

Request Body

Field	Type	Required	Default	Description
baseDir	string	No	""	Base directory to scan, absolute or relative to the scripts directory
includeMetadata	boolean	No	false	When true, include file size and modification time for each route

cURL

curl -X POST "https://acme-prod-abc123-exec-1.eu-west-1.containers.hoody.icu/api/v1/exec/route/discover" \
  -H "Content-Type: application/json" \
  -d '{
    "baseDir": "scripts",
    "includeMetadata": true
  }'

SDK

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

Response

200

{
  "baseDir": "scripts",
  "count": 3,
  "routes": [
    {
      "pattern": "/api/users",
      "filePath": "scripts/api/users.ts",
      "type": "static",
      "params": []
    },
    {
      "pattern": "/api/users/:id",
      "filePath": "scripts/api/users/[id].ts",
      "type": "dynamic",
      "params": ["id"]
    },
    {
      "pattern": "/api/files/:path*",
      "filePath": "scripts/api/files/[...path].ts",
      "type": "catchall",
      "params": ["path"]
    }
  ]
}

400

{
  "error": "Invalid request payload",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {}
}

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

404

{
  "error": "Scripts directory not found",
  "code": "NOT_FOUND",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {}
}

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

500

{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {}
}

POST /api/v1/exec/route/resolve

Resolves a single URL path to the script file that would handle it. Resolution is scoped by hostname and execId and checks, in order: {hostname}/{execId}/, {hostname}/, {execId}/, and the root.

This endpoint takes no parameters.

Request Body

This endpoint accepts a JSON request body. Specific field shapes are defined by the implementation.

cURL

curl -X POST "https://acme-prod-abc123-exec-1.eu-west-1.containers.hoody.icu/api/v1/exec/route/resolve" \
  -H "Content-Type: application/json" \
  -d '{}'

SDK

await client.exec.route.resolve({});

Response

200

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

400

{
  "error": "Invalid request payload",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {}
}

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

500

{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {}
}

POST /api/v1/exec/route/test

Tests multiple URL paths against the routing system in a single batch request. For each path, returns the resolved script, extracted parameters, and route type. The aggregate matched and notMatched counts are included.

This endpoint takes no parameters.

Request Body

This endpoint accepts a JSON request body. Specific field shapes are defined by the implementation.

cURL

curl -X POST "https://acme-prod-abc123-exec-1.eu-west-1.containers.hoody.icu/api/v1/exec/route/test" \
  -H "Content-Type: application/json" \
  -d '{}'

SDK

await client.exec.route.test({});

Response

200

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

400

{
  "error": "Invalid request payload",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {}
}

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

500

{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {}
}

User OpenAPI

List user scripts, serve their schemas, and generate, merge, or validate OpenAPI specifications derived from them.

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

Lists available scripts under the configured scripts directory along with per-script schema metadata, route path, and extracted path parameters.

Parameters

Name	In	Type	Required	Description
directory	query	string	No	Script directory to list (absolute or relative to scripts-dir). Default: scripts.
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

curl -X GET "https://acme-prod-abc123-exec-1.eu-west-1.containers.hoody.icu/api/v1/exec/user-openapi/list?directory=api"

SDK

await client.exec.openapi.listScripts({ directory: "api" });

Response

200

{
  "success": true,
  "data": {
    "directory": "api",
    "totalScripts": 2,
    "withSchemas": 2,
    "scripts": [
      {
        "path": "api/users/index.ts",
        "routePath": "/api/users",
        "hasSchema": true,
        "schemaFormat": "zod",
        "pathParameters": []
      },
      {
        "path": "api/users/[id].ts",
        "routePath": "/api/users/:id",
        "hasSchema": true,
        "schemaFormat": "zod",
        "pathParameters": ["id"]
      }
    ]
  }
}

400

{
  "error": "Invalid request",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {}
}

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

500

{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {}
}

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

Serves the schema file (Zod or JSON Schema) for a specific user script directly, without rendering the surrounding route metadata.

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

curl -X GET "https://acme-prod-abc123-exec-1.eu-west-1.containers.hoody.icu/api/v1/exec/user-openapi/schema?file=default/api/users/%5Bid%5D.ts"

SDK

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

Response

200

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "number" }
  },
  "required": ["name"]
}

400

{
  "error": "Either `file` or `path` query parameter is required",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {}
}

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

500

{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {}
}

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

Generates and serves the OpenAPI specification on-the-fly from the user scripts directory. Use format=yaml to receive YAML instead of JSON.

Parameters

Name	In	Type	Required	Description
dir	query	string	No	Script directory to scan (absolute or relative to scripts-dir). Default: scripts.
directory	query	string	No	Alias of dir. Ignored when dir is provided.
format	query	string	No	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

curl -X GET "https://acme-prod-abc123-exec-1.eu-west-1.containers.hoody.icu/api/v1/exec/user-openapi/spec?dir=api&format=json"

SDK

await client.exec.openapi.serve({ dir: "api", format: "json" });

Response

200

{
  "openapi": "3.0.0",
  "info": {
    "title": "User API",
    "version": "1.0.0"
  },
  "paths": {
    "/api/users": {
      "get": {
        "summary": "List users"
      }
    }
  }
}

400

{
  "error": "Invalid format",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {}
}

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

500

{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {}
}

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

Generates an OpenAPI specification from user scripts and returns it together with generation metadata.

This endpoint takes no parameters.

Request Body

This endpoint accepts a JSON request body. Specific field shapes are defined by the implementation.

cURL

curl -X POST "https://acme-prod-abc123-exec-1.eu-west-1.containers.hoody.icu/api/v1/exec/user-openapi/generate" \
  -H "Content-Type: application/json" \
  -d '{}'

SDK

await client.exec.openapi.generate({});

Response

200

{
  "success": true,
  "data": {
    "openapi": "3.0.0",
    "info": {
      "title": "User API",
      "version": "1.0.0"
    },
    "paths": {}
  },
  "meta": {
    "pathCount": 8,
    "scanDirectory": "scripts",
    "generatedAt": "2025-01-15T10:30:00.000Z"
  }
}

400

{
  "error": "Invalid request payload",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {}
}

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

500

{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {}
}

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

Merges multiple OpenAPI specifications into a single combined specification.

This endpoint takes no parameters.

Request Body

This endpoint accepts a JSON request body. Specific field shapes are defined by the implementation.

cURL

curl -X POST "https://acme-prod-abc123-exec-1.eu-west-1.containers.hoody.icu/api/v1/exec/user-openapi/merge" \
  -H "Content-Type: application/json" \
  -d '{}'

SDK

await client.exec.openapi.merge({});

Response

200

{
  "success": true,
  "data": {
    "openapi": "3.0.0",
    "info": {
      "title": "Merged API",
      "version": "1.0.0"
    },
    "paths": {}
  }
}

400

{
  "error": "Invalid request payload",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {}
}

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

500

{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {}
}

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

Validates a single script’s schema file and returns any validation errors. Use this endpoint to check whether a schema is well-formed before generating a spec.

This endpoint takes no parameters.

Request Body

This endpoint accepts a JSON request body. Specific field shapes are defined by the implementation.

cURL

curl -X POST "https://acme-prod-abc123-exec-1.eu-west-1.containers.hoody.icu/api/v1/exec/user-openapi/validate" \
  -H "Content-Type: application/json" \
  -d '{}'

SDK

await client.exec.openapi.validateSchema({});

Response

200

{
  "success": true,
  "data": {
    "valid": true
  },
  "errors": []
}

400

{
  "error": "Invalid request payload",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {}
}

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

500

{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {}
}