Skip to main content

Tools API

All endpoints verified working via curl. Document updated only after curl confirmation.

All endpoints accept either a session cookie (connect.sid) or a Bearer API key. Write operations (POST/PATCH/DELETE) require owner, admin, or editor role. This covers the Tool shell CRUD only — see tools-versions.md, tools-aliases.md, and tools-execute.md for the rest of the Tool Catalog (Phase 4) domain.

POST /api/v1/tools​

Creates a new tool shell (no versions/aliases yet — commit a version separately). name must match ^[a-zA-Z0-9_-]{1,64}$ (kept LLM-function-name-safe for OpenAI/Anthropic/Gemini tool-calling compatibility).

curl -X POST $ACRUXCORE_BASE_URL/tools \
  -H "Authorization: Bearer $ACRUXCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"get_weather","description":"Fetch current weather for a city."}'

Response (status 201):

{
  "id": "8662ca24-69f2-4431-a7f4-82e9abc77ff1",
  "name": "get_weather",
  "description": "Fetch current weather for a city.",
  "teamId": "66e0b84e-04fb-4811-8c62-2f1018474d02",
  "createdBy": "67c79920-dda0-4916-9505-8abba3d4ea90",
  "createdAt": "2026-07-12T04:22:58.156Z"
}

Response (status 400) — name fails the safe-name pattern:

{"error":{"code":"VALIDATION_ERROR","message":"name must match ^[a-zA-Z0-9_-]{1,64}$"}}

GET /api/v1/tools​

Returns a paginated list of active (non-deleted) tools for the current team. Supports ?search=, ?page=, ?limit=.

curl $ACRUXCORE_BASE_URL/tools \
  -H "Authorization: Bearer $ACRUXCORE_API_KEY"

Response (status 200):

{
  "data": [
    {
      "id": "8662ca24-69f2-4431-a7f4-82e9abc77ff1",
      "name": "get_weather",
      "description": "Fetch current weather for a city.",
      "teamId": "66e0b84e-04fb-4811-8c62-2f1018474d02",
      "createdBy": "67c79920-dda0-4916-9505-8abba3d4ea90",
      "createdAt": "2026-07-12T04:22:58.156Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

GET /api/v1/tools/:id​

Fetches a single active tool by ID.

curl $ACRUXCORE_BASE_URL/tools/8662ca24-69f2-4431-a7f4-82e9abc77ff1 \
  -H "Authorization: Bearer $ACRUXCORE_API_KEY"

Response (status 200):

{
  "id": "8662ca24-69f2-4431-a7f4-82e9abc77ff1",
  "name": "get_weather",
  "description": "Fetch current weather for a city.",
  "teamId": "66e0b84e-04fb-4811-8c62-2f1018474d02",
  "createdBy": "67c79920-dda0-4916-9505-8abba3d4ea90",
  "createdAt": "2026-07-12T04:22:58.156Z"
}

Response (status 404) — tool not found, deleted, or belongs to another team:

{"error":{"code":"NOT_FOUND","message":"Tool not found."}}

PATCH /api/v1/tools/:id​

Partially updates a tool's name and/or description. At least one field is required.

curl -X PATCH $ACRUXCORE_BASE_URL/tools/8662ca24-69f2-4431-a7f4-82e9abc77ff1 \
  -H "Authorization: Bearer $ACRUXCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description":"Fetch current weather for a city (v2)."}'

Response (status 200):

{
  "id": "8662ca24-69f2-4431-a7f4-82e9abc77ff1",
  "name": "get_weather",
  "description": "Fetch current weather for a city (v2).",
  "teamId": "66e0b84e-04fb-4811-8c62-2f1018474d02",
  "createdBy": "67c79920-dda0-4916-9505-8abba3d4ea90",
  "createdAt": "2026-07-12T04:22:58.156Z"
}

Response (status 400) — neither name nor description provided:

{"error":{"code":"VALIDATION_ERROR","message":"At least one of name or description must be provided."}}

DELETE /api/v1/tools/:id​

Soft-deletes a tool (deleted_at = now()). Version and alias rows are preserved but the tool no longer appears in list/get, and a subsequent GET returns 404.

curl -X DELETE $ACRUXCORE_BASE_URL/tools/8662ca24-69f2-4431-a7f4-82e9abc77ff1 \
  -H "Authorization: Bearer $ACRUXCORE_API_KEY"

Response (status 204) — no body.

Subsequent GET returns 404:

curl $ACRUXCORE_BASE_URL/tools/8662ca24-69f2-4431-a7f4-82e9abc77ff1 \
  -H "Authorization: Bearer $ACRUXCORE_API_KEY"

Response (status 404):

{"error":{"code":"NOT_FOUND","message":"Tool not found."}}