Kosa API

OpenAPI 3.1 specification

OpenAPI 3.1 specification

The Kosa tools API is available at https://api.getkosa.ai. Access requires an early-access Kosa account. API keys are issued to early-access firms.

Authentication

Send either an OAuth bearer token with the kosa.tools.invoke scope or an issued Kosa API key in the authorization header:

Authorization: Bearer <key-or-token>

OAuth clients use PKCE S256 and can discover the complete flow from:

• Protected resource metadata: https://api.getkosa.ai/.well-known/oauth-protected-resource
• Authorization server metadata: https://api.getkosa.ai/.well-known/oauth-authorization-server
• Dynamic client registration: https://api.getkosa.ai/oauth/register

List tools

GET /tools/list

There is no request body. The response is a JSON object with a tools array. Each tool contains name (string), title (string), description (string), and annotations (object). Tools that persist an output also include persistOutput: true.

curl https://api.getkosa.ai/tools/list \
  -H "Authorization: Bearer $KOSA_API_KEY"

{
  "tools": [
    {
      "name": "query-deals",
      "title": "Query deals",
      "description": "...",
      "annotations": {
        "readOnlyHint": true,
        "destructiveHint": false,
        "idempotentHint": true,
        "openWorldHint": false
      }
    }
  ]
}

Execute a tool

POST /tools/execute

The JSON request body has two fields:

curl https://api.getkosa.ai/tools/execute \
  -X POST \
  -H "Authorization: Bearer $KOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"query-deals","input":{"limit":10}}'

Most tools return their tool-specific JSON object directly. A tool marked persistOutput: true returns this envelope and stores the result for the output routes:

{
  "output_id": "output-id",
  "content": "...",
  "format": "markdown",
  "metadata": {}
}

Get a stored output

GET /tools/outputs/:id

The id path parameter is a string. There is no request body. The response contains id (string), skillName (string), outputContent (string), outputFormat (string), parameters (JSON value), feedbackRating (string or null), and generatedAt (timestamp string or null).

curl https://api.getkosa.ai/tools/outputs/output-id \
  -H "Authorization: Bearer $KOSA_API_KEY"

Submit output feedback

POST /tools/outputs/:id/feedback

The id path parameter is a string. The JSON request body has these fields:

curl https://api.getkosa.ai/tools/outputs/output-id/feedback \
  -X POST \
  -H "Authorization: Bearer $KOSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rating":"helpful","text":"The source context was useful."}'

A successful update returns:

{"success":true}

Export a stored output

GET /tools/outputs/:id/export

The id path parameter is a string. There is no request body. A successful response is the stored output content as text/markdown with an attachment filename based on the tool name and generation date.

curl https://api.getkosa.ai/tools/outputs/output-id/export \
  -H "Authorization: Bearer $KOSA_API_KEY" \
  -o kosa-output.md

Errors

Authentication failures return HTTP 401 with {"error":"AUTH_INVALID"}. A request with an explicit origin outside the allowed origins returns HTTP 403 with {"error":"ORIGIN_FORBIDDEN"}.

Tool execution errors use error and message strings. Input-validation responses may add details; handler failures may add traceId. The handler maps tool errors to HTTP 400, 401, 403, 404, 409, 429, 500, or 503 according to the error code.

{
  "error": "INPUT_VALIDATION",
  "message": "...",
  "details": "..."
}

The stored-output get and feedback routes return HTTP 404 with {"error":"NOT_FOUND","message":"Output not found."} when the authenticated firm cannot access that output. The export route returns HTTP 404 with {"error":"Skill output not found"}.