Register a tool manifest

POST

/v1/tools

const url = 'https://example.com/v1/tools';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"id":"example","description":"example","version":"example","input":{},"output":{},"needs":[{"name":"example","optional":true}],"effects":[{"kind":"reads","resource":"example","notes":"example"}],"transport":"auto","mcpEndpoint":"example","metadata":{},"mutating":true,"sandbox":"none","limits":{"memMB":1,"cpuMs":1},"network":{"kind":"none"},"needsSpec":{"env":{"additionalProperty":{}},"secrets":{"additionalProperty":{}},"config":{"additionalProperty":{}},"capabilities":["example"],"bindings":["example"]},"codeArtifactRef":{"kind":"oci","imageRef":"example","modulePath":"example","artifactVersion":"example"},"spec":{"kind":"http","method":"GET","urlTemplate":"example","headers":[{"name":"example","value":"example"}],"authorization":{"kind":"bearer","secretRef":{"envName":"example","name":"example"}},"requestBody":{"kind":"json-input"},"timeoutMs":1,"parseJson":true,"successStatus":{"min":1,"max":1}},"projectId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://example.com/v1/tools \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "id": "example", "description": "example", "version": "example", "input": {}, "output": {}, "needs": [ { "name": "example", "optional": true } ], "effects": [ { "kind": "reads", "resource": "example", "notes": "example" } ], "transport": "auto", "mcpEndpoint": "example", "metadata": {}, "mutating": true, "sandbox": "none", "limits": { "memMB": 1, "cpuMs": 1 }, "network": { "kind": "none" }, "needsSpec": { "env": { "additionalProperty": {} }, "secrets": { "additionalProperty": {} }, "config": { "additionalProperty": {} }, "capabilities": [ "example" ], "bindings": [ "example" ] }, "codeArtifactRef": { "kind": "oci", "imageRef": "example", "modulePath": "example", "artifactVersion": "example" }, "spec": { "kind": "http", "method": "GET", "urlTemplate": "example", "headers": [ { "name": "example", "value": "example" } ], "authorization": { "kind": "bearer", "secretRef": { "envName": "example", "name": "example" } }, "requestBody": { "kind": "json-input" }, "timeoutMs": 1, "parseJson": true, "successStatus": { "min": 1, "max": 1 } }, "projectId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }'

Body is a ToolManifest (Tool minus its runtime handler). Server validates via @kindgi/tools.validateToolManifest. Metadata only: the handler is not uploaded through this route and must already be available to the runtime.

Authorizations

bearerAuth

Parameters

Header Parameters

Idempotency-Key

string

>= 1 characters

Caller-supplied idempotency key. Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1).

Request Body^required

application/json

ToolManifest — Tool minus its runtime handler. Validated server-side via @kindgi/tools.validateToolManifest. Metadata-only registration: the handler is not uploaded and must already be available to the runtime.

object

required

ToolId — dotted namespace (e.g. acme.verify-citation).

string

>= 1 characters

description

required

string

>= 1 characters

version

string

/^\d+\.\d+\.\d+$/

input

required

JSON Schema (Draft 2020-12) for the tool input.

object

key

additional properties

any

output

required

JSON Schema (Draft 2020-12) for the tool output.

object

key

additional properties

any

needs

Array<object>

object

name

required

string

>= 1 characters

optional

boolean

effects

Array<object>

object

kind

required

string

Allowed values: reads writes deletes network spawns-run emits-event external-side-effect sensitive-data-egress

resource

string

notes

string

transport

string

Allowed values: auto native mcp

mcpEndpoint

string

metadata

object

key

additional properties

any

mutating

Semantic marker: true when this tool causes observable side effects (writes state, calls external APIs with mutations, sends messages). Read-only tools set false. Absent defaults to true. Consumed by the HITL default classifier — a read-only tool passes straight through, a mutating tool asks on first use.

boolean

sandbox

Isolation posture the runtime enforces around the handler. Optional additive field.

string

Allowed values: none context-isolated strict

limits

Sandbox-enforced resource caps at dispatch. Optional additive field.

object

memMB

required

integer

>= 1

cpuMs

required

integer

>= 1

network

One of:

object
object

Network egress policy. Optional additive field. Discriminated on kind.

object

kind

required

string

Allowed values: none unrestricted

Network egress policy. Optional additive field. Discriminated on kind.

object

kind

required

string

Allowed value: allowlist

hosts

required

Array<string>

needsSpec

Typed discriminated needs (env / secrets / config / capabilities / bindings). Optional additive field.

object

env

object

key

additional properties

object

secrets

object

key

additional properties

object

config

object

key

additional properties

object

capabilities

Array<string>

bindings

Array<string>

codeArtifactRef

One of:

object
object

object

kind

required

Allowed value: oci

imageRef

required

string

>= 1 characters

modulePath

required

string

>= 1 characters

artifactVersion

required

string

>= 1 characters

spec

One of:

object

Declarative HTTP-invocation spec. Attached to ToolManifest.spec under the discriminant kind: 'http'. The runtime Tool.handler is synthesized by the ‘http’ spec synthesizer to perform URL-template substitution, secret-ref resolution via ToolContext.resolveSecret, and the outbound fetch. All fields serialize cleanly to JSON.

object

kind

required

Allowed value: http

method

required

string

Allowed values: GET POST PUT PATCH DELETE

urlTemplate

required

URL template with {param} placeholders substituted from the tool’s input at invoke time.

string

>= 1 characters

headers

Array<object>

object

name

required

string

>= 1 characters

value

required

string

authorization

One of:

object
object

object

kind

required

Allowed value: bearer

secretRef

required

object

envName

required

string

>= 1 characters

name

required

string

>= 1 characters

requestBody

One of:

object

kind

required

Allowed value: json-input

timeoutMs

Wall-clock timeout in ms. Default 30000.

integer

>= 1

parseJson

When true (default), the response body is parsed as JSON before returning to the invoker.

boolean

successStatus

object

min

required

integer

>= 100 <= 599

max

required

integer

>= 100 <= 599

projectId

required

Project this belongs to (its content scope). Required: missing, or not a project in the caller’s tenant → 400 bad-input.

string format: uuid

Responses

201

Tool registered.

application/json

object

toolId

required

string

Example^generated

{
  "toolId": "example"
}

400

Validation failed (see details.issues).

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Missing / malformed / expired / revoked bearer token.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

409

Tool already registered at that id.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

500

Server error (unmapped domain code or framework crash).

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

Register a tool manifest

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Responses

201

Examplegenerated

400

Examplegenerated

401

Examplegenerated

409

Examplegenerated

500

Examplegenerated

Request Body^required

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated