POST/api/v1/tools

Tools

Create Tool

Creates a user tool from a catalog tool type. apiRequest configs are strictly validated for safe URLs, headers, parameters, authentication, size, and shape.

Request

Endpoint

POST/api/v1/tools

Authentication

x-api-keyorAuthorization: Bearer

Body Parameters

Name	Type	Description
`tool_id`required	ObjectId	Tool type id from GET /api/v1/tool-types.
`name`required	string	Tool name. Max 128 characters and no control characters.
`description`required	string	When and why the assistant should use the tool.
`when_to_call`	string	When the assistant can call this tool. beforeCallonCallafterCall
`function`	object	Per-type configuration. apiRequest requires request_url and request_http_method.

Request Body Example

body.json

{
  "tool_id": "68d02cea2e27432ed86d838a",
  "name": "Get order status",
  "description": "Use this when a caller asks for the status of an order.",
  "when_to_call": "onCall",
  "function": {
    "request_url": "https://api.example.com/orders/{order_id}",
    "request_http_method": "GET",
    "authentication": {
      "type": "none"
    },
    "parameters": [
      {
        "name": "order_id",
        "type": "string",
        "required": true,
        "description": "Order identifier"
      }
    ]
  }
}

Notes

Restricted tool types knowledgebase and chainedfunction cannot be created through this API.

SSRF protection blocks private, loopback, link-local, and cloud-metadata request URLs.

Response Example

response.json

{
  "success": true,
  "data": {
    "id": "66aa2b3c4d5e6f7a8b9c0d11",
    "name": "Get order status",
    "description": "Use this when a caller asks for the status of an order.",
    "when_to_call": "onCall",
    "type": "apiRequest",
    "function": {
      "request_url": "https://api.example.com/orders/{order_id}",
      "request_http_method": "GET",
      "authentication": {
        "type": "none"
      }
    },
    "created_at": "2026-05-01T10:00:00.000Z",
    "updated_at": "2026-05-01T10:00:00.000Z"
  }
}

Status Codes

HTTP	Meaning	Description
201	Created	Resource was created.
400	Bad request	Malformed input, invalid ObjectId, or no updatable fields.
401	Unauthorized	Missing, invalid, inactive, or origin-restricted API key.
403	Forbidden	The requested operation is not available for this resource or tool type.
404	Not found	Resource was not found inside the authenticated user's scope.
415	Unsupported media type	Content-Type header is missing or is not application/json.
422	Validation error	JSON body failed schema or business validation.
429	Rate limited	Per-IP or per-key request budget was exceeded.

Security Model

User-scoped by default

This endpoint only sees resources owned by the user attached to the API key. If another user's id is supplied, the API responds as if the resource does not exist.

curl -X POST "https://docs.vomyra.com/api/v1/tools" \ -H "x-api-key: <api-key>" \ -H "Content-Type: application/json" \ -d '{ "tool_id": "68d02cea2e27432ed86d838a", "name": "Get order status", "description": "Use this when a caller asks for the status of an order.", "when_to_call": "onCall", "function": { "request_url": "https://api.example.com/orders/{order_id}", "request_http_method": "GET", "authentication": { "type": "none" }, "parameters": [ { "name": "order_id", "type": "string", "required": true, "description": "Order identifier" } ] } }'

Name

Type

Description

tool_idrequired

ObjectId

Tool type id from GET /api/v1/tool-types.

namerequired

string

Tool name. Max 128 characters and no control characters.

descriptionrequired

string

When and why the assistant should use the tool.

when_to_call

string

When the assistant can call this tool.

beforeCallonCallafterCall

function

object

Per-type configuration. apiRequest requires request_url and request_http_method.

{ "tool_id": "68d02cea2e27432ed86d838a", "name": "Get order status", "description": "Use this when a caller asks for the status of an order.", "when_to_call": "onCall", "function": { "request_url": "https://api.example.com/orders/{order_id}", "request_http_method": "GET", "authentication": { "type": "none" }, "parameters": [ { "name": "order_id", "type": "string", "required": true, "description": "Order identifier" } ] } }

{ "success": true, "data": { "id": "66aa2b3c4d5e6f7a8b9c0d11", "name": "Get order status", "description": "Use this when a caller asks for the status of an order.", "when_to_call": "onCall", "type": "apiRequest", "function": { "request_url": "https://api.example.com/orders/{order_id}", "request_http_method": "GET", "authentication": { "type": "none" } }, "created_at": "2026-05-01T10:00:00.000Z", "updated_at": "2026-05-01T10:00:00.000Z" } }

HTTP

Meaning

Description

201

Created

Resource was created.

400

Bad request

Malformed input, invalid ObjectId, or no updatable fields.

401

Unauthorized

Missing, invalid, inactive, or origin-restricted API key.

403

Forbidden

The requested operation is not available for this resource or tool type.

404

Not found

Resource was not found inside the authenticated user's scope.

415

Unsupported media type

Content-Type header is missing or is not application/json.

422

Validation error

JSON body failed schema or business validation.

429

Rate limited

Per-IP or per-key request budget was exceeded.