ROroarkhq
Tool

Create a tool

Changed on

Creates a tool and declares its first version. A tool only recorded from calls under the same name is adopted; one already declared returns 409. Give it a runtime for a hosted agent to call your endpoint. Header values are returned on read, so keep secrets out of them.

post/v1/tool

Request

  • Base URL
    https://api.roark.ai
  • URL
    https://api.roark.ai/v1/tool
  • Auth
    HTTP bearer

Request body

namestring required
descriptionstring required

When the agent should use the tool

agentIdstring uuid nullable
invocationCriteriastring nullable
expectedResultstring nullable

Example request

{
  "name": "book_appointment",
  "inputs": [
    {
      "name": "date"
    }
  ],
  "runtime": {
    "request": {
      "headers": [
        {
          "name": "X-Api-Version",
          "value": "2026-10-01"
        }
      ]
    }
  }
}

Response

The tool

Example response

{
  "data": {
    "name": "book_appointment",
    "inputs": [
      {
        "name": "date",
        "description": "ISO date"
      }
    ],
    "runtime": {
      "request": {
        "url": "https://api.example.com/bookings",
        "headers": [
          {
            "name": "X-Api-Version",
            "value": "2026-10-01"
          }
        ]
      }
    }
  }
}

Changes