API Reference

Every HTTP endpoint, request and response schema, and error code exposed by Sohri Skill Runtime. For the short contract summary see the API contract; the source schema is docs/openapi.json.

Basics

Item	Value
Base URL (local)	http://localhost:59213
Docker Compose host port	9213 → container 59213
Content type	application/json for all requests and responses
Authentication	None (intended for in-cluster calls)
Swagger UI	/skill_runtime/docs (/ and /docs redirect here)
ReDoc	/skill_runtime/redoc
OpenAPI JSON	/skill_runtime/openapi.json

Endpoint summary

Method	Path	Tag	operationId	Description
GET	/health/live	system	liveness_endpoint	Process liveness
GET	/health/ready	system	readiness_endpoint	Whether the Skill Engine URL is configured
GET	/v1/overview	skill_runtime	overview_endpoint	API overview
GET	/v1/version	skill_runtime	version_endpoint	Build and version information
POST	/v1/skills/execute	skill_runtime	execute_skill_endpoint	Execute a Skill

---

Execute a Skill

POST /v1/skills/execute

Forwards one generic Skill call from Graph Builder to Sohri Skill Engine. The Runtime has no Skill-specific input or output models and never interprets or modifies arguments.

Request body — SkillExecutionRequest

Field	Type	Required	Default	Description
skill_id	string	yes	—	Public kebab-case Skill ID. 1–100 characters, pattern ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$
arguments	object	no	{}	Skill input, forwarded unchanged as the Engine's input
context	object	no	{}	Caller context. Accepted for Graph Builder compatibility but not forwarded to the Engine

Requests with any undeclared field are rejected (additionalProperties: false).

{
  "skill_id": "sample-skill",
  "arguments": {
    "query": "example"
  },
  "context": {
    "session_id": "optional"
  }
}

Mapping to Skill Engine

The Runtime POSTs the following body to the configured SKILL_ENGINE_EXECUTE_URL.

Runtime request	Engine request	Conversion
skill_id	skill	- → _ (e.g. sample-skill → sample_skill)
arguments	input	Unchanged
context	—	Not forwarded

{
  "skill": "sample_skill",
  "input": {
    "query": "example"
  }
}

The Engine must return a JSON object of the form {"skill": "<snake_case id>", "result": <any>}. The Runtime checks that the returned skill matches the converted request ID.

Execution POSTs are never retried automatically or cached. Callers decide whether to retry based on the error's retryable flag.

Success response — 200 SkillExecutionResponse

Field	Type	Description
skill_id	string	The public kebab-case Skill ID from the request
success	boolean	Always true
result	any	The Engine's result value, unchanged
metadata.provider	string	Always "sohri-skill-engine"
metadata.elapsed_ms	integer ≥ 0	Engine call duration measured by the Runtime (ms)

{
  "skill_id": "sample-skill",
  "success": true,
  "result": {
    "answer": "example result"
  },
  "metadata": {
    "provider": "sohri-skill-engine",
    "elapsed_ms": 12
  }
}

Example call

curl -X POST http://localhost:59213/v1/skills/execute \
  -H 'Content-Type: application/json' \
  -d '{"skill_id":"sample-skill","arguments":{"query":"example"}}'

---

System endpoints

GET /health/live

Confirms the process can serve requests. Intended for the Kubernetes liveness probe.

{ "status": "ok", "version": "0.1.2" }

GET /health/ready

Reports whether the Skill Engine execution URL is configured. It does not try to reach the Engine, so skill_engine: true does not mean the Engine is available.

{ "status": "ready", "skill_engine": true }

GET /v1/overview

Returns the Runtime description, version, and list of public endpoints.

{
  "message": "Generic Sohri Graph Builder to Skill Engine execution proxy.",
  "version": "0.1.2",
  "endpoints": [
    "/health/live",
    "/health/ready",
    "/v1/overview",
    "/v1/version",
    "/v1/skills/execute"
  ]
}

GET /v1/version

Returns the build and semantic version information from version.py.

{
  "version": "0.1.2",
  "build_date": "2026-08-19",
  "description": "Generic Sohri Graph Builder to Skill Engine execution proxy",
  "api_name": "sohri_skill_runtime",
  "major": 0,
  "minor": 1,
  "patch": 2
}

---

Errors

Common error format — ErrorResponse

Every failure response uses the same shape.

Field	Type	Description
success	boolean	Always false
error.code	string	Machine-readable error code
error.message	string	Human-readable message (the Runtime's own messages are in Korean)
error.retryable	boolean	Hint for whether the same request may be retried

{
  "success": false,
  "error": {
    "code": "UPSTREAM_UNAVAILABLE",
    "message": "Skill Engine에 연결할 수 없습니다.",
    "retryable": true
  }
}

Validation error format

The OpenAPI schema documents the 422 response as FastAPI's default HTTPValidationError, but the actual response uses the common error format above (INVALID_ARGUMENT).

Error codes

HTTP	code	retryable	When
422	INVALID_ARGUMENT	false	Request body failed validation. message joins location: reason entries with ;
502	UPSTREAM_UNAVAILABLE	true	Engine connection failed or timed out (SKILL_REQUEST_TIMEOUT_SECONDS)
502	UPSTREAM_HTTP_ERROR	Depends on status	Engine returned 4xx/5xx with no structured error
502	The Engine's code	Engine value, else depends on status	Engine returned an error carrying code and message
502	INVALID_UPSTREAM_RESPONSE	false	Engine response is not a JSON object, lacks skill/result, or has a mismatched skill

For Engine HTTP errors, retryable takes the retryable value from the Engine's response body when present; otherwise it is true when the Engine status is 429, 500, 502, 503, or 504. Engine errors are always returned as 502, whatever the Engine's original status.

Validation error example:

{
  "success": false,
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "body.skill_id: String should match pattern '^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$'; body.extra: Extra inputs are not permitted",
    "retryable": false
  }
}

---

Configuration

Read from environment variables (prefix SKILL_) or .env.

Variable	Default	Description
SKILL_ENGINE_EXECUTE_URL	http://sohri-skill-engine:8000/v1/skills/execute	Skill Engine execution endpoint
SKILL_REQUEST_TIMEOUT_SECONDS	8.0	Engine call timeout (greater than 0, at most 60)
SKILL_HOST	0.0.0.0	Bind address
SKILL_PORT	59213	Listen port
SKILL_LOG_LEVEL	info	Log level
SKILL_ENVIRONMENT	local	Environment name