Skip to content

API Contract

The base URL is http://localhost:59213 and every response is JSON.

Execute a Skill

POST /v1/skills/execute

Request:

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

skill_id is lowercase kebab-case. The Runtime converts it to snake_case and forwards arguments unchanged as the Skill Engine's input.

Response:

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

result contains the value returned by Skill Engine, unchanged.

Errors

{
  "success": false,
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "body.skill_id: Field required",
    "retryable": false
  }
}

Main Runtime errors:

  • INVALID_ARGUMENT: the Runtime request is malformed
  • UPSTREAM_HTTP_ERROR: Skill Engine returned an HTTP error
  • UPSTREAM_UNAVAILABLE: could not connect to Skill Engine
  • INVALID_UPSTREAM_RESPONSE: the Skill Engine response is malformed or its Skill ID does not match

When Skill Engine returns a structured error, its code and message are passed through.

The full endpoint, schema, and error-code reference is in the API reference.