Skip to main content

Tool Versions 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. Committing a version requires owner, admin, or editor role; reads require any authenticated role.

A version's executor is a discriminated union: {"type":"client"} (the customer's own app runs the tool — nothing to validate) or a declarative {"type":"http", ...} executor that the platform itself can call (see tools-execute.md). For an http executor, commit-time validation deep-checks requestTransform/responseTransform JS syntax, {{secret.NAME}} references, and that url resolves to a public (non-private/loopback) address.

The first version committed for a tool (versionNumber === 1) auto-creates production and staging aliases pointing at it; later commits do not move any alias — use tools-aliases.md's promote endpoint for that.

POST /api/v1/tools/:id/versions​

curl -X POST $ACRUXCORE_BASE_URL/tools/8662ca24-69f2-4431-a7f4-82e9abc77ff1/versions \
  -H "Authorization: Bearer $ACRUXCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "v1 - calls httpbin GET",
    "parametersSchema": {"type":"object","properties":{"city":{"type":"string"}},"required":["city"]},
    "executor": {
      "type": "http",
      "url": "https://httpbin.org/get",
      "method": "GET",
      "headers": [],
      "query": [{"name":"city","value":"placeholder"}],
      "argMapping": []
    }
  }'

Response (status 201) — first commit: includes auto-created aliases:

{
  "id": "b40e86ed-9dfd-44c4-bf86-038e4964be22",
  "toolId": "8662ca24-69f2-4431-a7f4-82e9abc77ff1",
  "versionNumber": 1,
  "description": "v1 - calls httpbin GET",
  "parametersSchema": {"type":"object","required":["city"],"properties":{"city":{"type":"string"}}},
  "executor": {"url":"https://httpbin.org/get","type":"http","query":[{"name":"city","value":"placeholder"}],"method":"GET","headers":[],"argMapping":[]},
  "createdBy": "67c79920-dda0-4916-9505-8abba3d4ea90",
  "createdAt": "2026-07-12T04:23:06.724Z",
  "aliases": [
    {"id":"eda4a0d8-e3fe-40d7-927d-69977db6f537","alias":"production","versionId":"b40e86ed-9dfd-44c4-bf86-038e4964be22","versionNumber":1,"updatedAt":"2026-07-12T04:23:06.734Z"},
    {"id":"0114e5d1-c386-402e-a059-e061d8a21f6e","alias":"staging","versionId":"b40e86ed-9dfd-44c4-bf86-038e4964be22","versionNumber":1,"updatedAt":"2026-07-12T04:23:06.734Z"}
  ]
}

A subsequent commit (v2) — no aliases field in the response:

curl -X POST $ACRUXCORE_BASE_URL/tools/8662ca24-69f2-4431-a7f4-82e9abc77ff1/versions \
  -H "Authorization: Bearer $ACRUXCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "v2 - POST variant",
    "parametersSchema": {"type":"object","properties":{"city":{"type":"string"}},"required":["city"]},
    "executor": {"type":"http","url":"https://httpbin.org/post","method":"POST","headers":[],"query":[],"argMapping":[]}
  }'

Response (status 201):

{
  "id": "f196ec83-36d3-4826-a33b-25bac669437f",
  "toolId": "8662ca24-69f2-4431-a7f4-82e9abc77ff1",
  "versionNumber": 2,
  "description": "v2 - POST variant",
  "parametersSchema": {"type":"object","required":["city"],"properties":{"city":{"type":"string"}}},
  "executor": {"url":"https://httpbin.org/post","type":"http","query":[],"method":"POST","headers":[],"argMapping":[]},
  "createdBy": "67c79920-dda0-4916-9505-8abba3d4ea90",
  "createdAt": "2026-07-12T04:23:39.529Z"
}

Response (status 400) — http executor's url is not a public address (SSRF guard, defense-in-depth):

{"error":{"code":"VALIDATION_ERROR","message":"Blocked address: 127.0.0.1"}}

Response (status 404) — tool does not exist or belongs to another team:

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

GET /api/v1/tools/:id/versions​

Lists all versions for a tool, newest first. parametersSchema/executor are omitted from list items (fetch a specific version for those).

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

Response (status 200):

{
  "data": [
    {
      "id": "b40e86ed-9dfd-44c4-bf86-038e4964be22",
      "toolId": "8662ca24-69f2-4431-a7f4-82e9abc77ff1",
      "versionNumber": 1,
      "description": "v1 - calls httpbin GET",
      "createdBy": "67c79920-dda0-4916-9505-8abba3d4ea90",
      "createdAt": "2026-07-12T04:23:06.724Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

GET /api/v1/tools/:id/versions/:version_number​

Fetches a specific version, including its full parametersSchema and executor.

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

Response (status 200):

{
  "id": "b40e86ed-9dfd-44c4-bf86-038e4964be22",
  "toolId": "8662ca24-69f2-4431-a7f4-82e9abc77ff1",
  "versionNumber": 1,
  "description": "v1 - calls httpbin GET",
  "parametersSchema": {"type":"object","required":["city"],"properties":{"city":{"type":"string"}}},
  "executor": {"url":"https://httpbin.org/get","type":"http","query":[{"name":"city","value":"placeholder"}],"method":"GET","headers":[],"argMapping":[]},
  "createdBy": "67c79920-dda0-4916-9505-8abba3d4ea90",
  "createdAt": "2026-07-12T04:23:06.724Z"
}

Response (status 404) — version number does not exist for this tool:

{"error":{"code":"NOT_FOUND","message":"Version 99 not found for this tool."}}