Technical Task Router

DEPLOYED

Prediction

Technical

HROUT

Technical Task Router API

Submit a nested task routing request to get model recommendations.

$0.50 / 1k requests

Prediction Endpoint

POST

https://api.hokus.ai/api/v1/models/30/predict

Inference Provider:

hokusai

Authentication

All API requests require authentication using an API key

Sign in, open API keys, create a key, then copy the returned hk_ value into the Authorization header for every request.

Header Format

Authorization: Bearer hk_live_your_api_key_here

Get API Key

Request Schema

Organized for progressive enhancement, from a minimal task to richer execution data.

Document-style reference for the v2 nested task routing API. Send a task description with optional routing, workflow, and context constraints; receive a recommended workflow strategy alongside lower-cost, faster, and more-reliable alternatives.

Minimal request

Full request body. The required inputs.task.description and inputs.task.task_type are enough to receive a routing recommendation.

JavaScript

{
  "inputs": {
    "task": {
      "description": "Implement password reset flow",
      "task_type": "feature"
    }
  }
}

Field	Type	Required	Description	Constraints
description	string	Required	Natural-language task description.	-
task_type	string	Required	High-level task category.	`feature, bugfix, refactor, research, maintenance`
language	string	Optional	Primary implementation language.	-
framework	string	Optional	Primary framework or stack.	-
repo_type	string	Optional	Repository type or project shape.	-

Sample request body

Copy this full request body as a starting point for your integration.

JavaScript

{
  "inputs": {
    "task": {
      "description": "Refactor billing webhook retry handling",
      "task_type": "refactor",
      "language": "python",
      "framework": "fastapi",
      "repo_type": "monorepo"
    },
    "routing": {
      "available_models": [
        "claude-sonnet-4-6",
        "gpt-5"
      ],
      "max_cost_usd": 25,
      "objective": "highest_reliability"
    },
    "workflow": {
      "stages": [
        "plan",
        "code",
        "review"
      ]
    },
    "context": {
      "domain": "payments",
      "repo_size_bucket": "large",
      "requires_tests": true,
      "risk_level": "medium",
      "file_count": 6,
      "estimated_complexity": "medium",
      "security_sensitive": true
    }
  }
}

Start with a single task description. Add additional context over time to improve routing precision.

Response Schema

Expected response format from the API

Example Response

JavaScript

{
  "model_id": "30",
  "predictions": {
    "recommended_strategy": {
      "objective": "highest_reliability",
      "planner_model": "claude-sonnet-4-6",
      "coder_model": "gpt-5",
      "reviewer_model": "claude-sonnet-4-6",
      "stages": [
        "plan",
        "code",
        "review"
      ],
      "estimated_success_under_budget": 0.82,
      "estimated_cost_usd": 4.8,
      "estimated_duration_seconds": 1800,
      "confidence": 0.71,
      "rationale": "Selected claude-sonnet-4-6 for planning and review with gpt-5 for coding on a reliability-optimized refactor with moderate budget."
    },
    "alternatives": [
      {
        "objective": "lowest_cost",
        "planner_model": "gpt-5",
        "coder_model": "gpt-5",
        "reviewer_model": "gpt-5",
        "stages": [
          "plan",
          "code",
          "review"
        ],
        "estimated_success_under_budget": 0.75,
        "estimated_cost_usd": 2.1,
        "estimated_duration_seconds": 1200,
        "confidence": 0.65,
        "rationale": "All-gpt-5 strategy minimizes cost at lower estimated reliability."
      }
    ],
    "tradeoffs": {
      "lowest_cost": {
        "objective": "lowest_cost",
        "planner_model": "gpt-5",
        "coder_model": "gpt-5",
        "reviewer_model": "gpt-5",
        "stages": [
          "plan",
          "code",
          "review"
        ],
        "estimated_success_under_budget": 0.75,
        "estimated_cost_usd": 2.1,
        "estimated_duration_seconds": 1200,
        "confidence": 0.65,
        "rationale": "All-gpt-5 strategy minimizes cost at lower estimated reliability."
      },
      "fastest_completion": null,
      "highest_reliability": {
        "objective": "highest_reliability",
        "planner_model": "claude-sonnet-4-6",
        "coder_model": "gpt-5",
        "reviewer_model": "claude-sonnet-4-6",
        "stages": [
          "plan",
          "code",
          "review"
        ],
        "estimated_success_under_budget": 0.82,
        "estimated_cost_usd": 4.8,
        "estimated_duration_seconds": 1800,
        "confidence": 0.71,
        "rationale": "Selected claude-sonnet-4-6 for planning and review with gpt-5 for coding on a reliability-optimized refactor with moderate budget."
      }
    },
    "nearest_neighbors": {
      "count": 40,
      "success_under_budget_rate": 0.78,
      "mean_cost_usd": 4.4,
      "mean_duration_seconds": 1650
    }
  },
  "metadata": {
    "api_version": "2.0",
    "inference_method": "mlflow_pyfunc",
    "model_uri": "models:/Technical Task Router@production",
    "model_version": "6",
    "schema": "technical_task_router_inputs/v2",
    "request_id": "req_model30_8f2a1c"
  },
  "timestamp": "2026-05-28T00:33:21.100874Z",
  "inference_log_id": "ilog_model30_8f2a1c"
}

Response Fields

Field	Type	Description
model_id	string	Identifier of the model that produced the response ('30').
predictions.recommended_strategy	object	The primary recommended workflow strategy.
predictions.alternatives	array	Alternative strategy recommendations.
predictions.tradeoffs	object	Best strategy per objective, or null if no viable strategy exists.
predictions.nearest_neighbors	object	Historical performance data from similar tasks.
metadata.api_version	string	API contract version.
metadata.inference_method	string	Serving method used to produce the prediction.
metadata.model_uri	string	MLflow model URI that served the request.
metadata.model_version	string	Served model version.
metadata.schema	string	Input schema identifier the request was validated against.
metadata.request_id	string	Unique identifier for the request.
timestamp	string	ISO 8601 timestamp of the response.
inference_log_id	string	Identifier of the inference log row, when logging is enabled.

Code Examples

Copy-paste ready code examples in multiple languages

cURL

curl -X POST "https://api.hokus.ai/api/v1/models/30/predict" \
  -H "Authorization: Bearer hk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "inputs": {
    "task": {
      "description": "Refactor billing webhook retry handling",
      "task_type": "refactor",
      "language": "python",
      "framework": "fastapi",
      "repo_type": "monorepo"
    },
    "routing": {
      "available_models": [
        "claude-sonnet-4-6",
        "gpt-5"
      ],
      "max_cost_usd": 25,
      "objective": "highest_reliability"
    },
    "workflow": {
      "stages": [
        "plan",
        "code",
        "review"
      ]
    },
    "context": {
      "domain": "payments",
      "repo_size_bucket": "large",
      "requires_tests": true,
      "risk_level": "medium",
      "file_count": 6,
      "estimated_complexity": "medium",
      "security_sensitive": true
    }
  }
}'

Error Codes

Common error responses and how to resolve them

Code	Error	Description	Resolution
401	Unauthorized	Missing or invalid API key.	Include a valid API key in the Authorization header.
404	Not Found	Model not found.	Verify that model 30 is available and the model ID is correct.
422	Validation Error	The request body did not satisfy the nested input schema.	Commonly caused by a missing `inputs.task.description` or `inputs.task.task_type`, a missing outer `inputs` object, or sending the old flat benchmark-row payload. Send the nested `inputs.task` object.
503	Service Unavailable	Model artifact, load, or inference is temporarily unavailable.	Retry with backoff; contact support if the failure persists.

Technical Task Router

Prediction Endpoint

Header Format

Minimal request

Required: TaskrequiredDescribe the work that needs to be routed.

Recommended: Routing ConstraintsrecommendedSet budget, latency, model preferences, and routing objective.

Optional: Task ContextoptionalAdd descriptors that improve routing precision.

Optional: Workflow InformationoptionalDescribe the implementation surface and lifecycle.

Advanced: ProvenanceadvancedInclude integration identifiers and idempotency metadata.

Sample request body

Example Response

Response Fields