Skip to main content

Toolkits

Endpoints for managing the toolkits bound to an Assistant. A toolkit is a named group of tools (see the Toolkit API); binding one to an Assistant lets that Assistant call its tools.

Every route is gated by ai.verify (AI enabled on the tenant AND the caller having AI access). The write routes (POST/DELETE) additionally require permission.assistant.write on the looked-up Assistant.

A binding is the join row between an Assistant and a Toolkit; it is addressed in the URL by the toolkit's id.

GET /api/assistants/{id}/toolkits​

List the toolkits bound to an Assistant.

Authentication: Required (AI access via ai.verify)

Response:

A HAL collection (rel inf:assistant-toolkits) of the bindings. Each row is embedded as inf:assistant-toolkit and itself embeds inf:toolkit — the bound toolkit, scoped to what the caller can read.

List an assistant’s toolkitsGET /api/assistants/admin:order-desk-assistant/toolkits
GET /api/assistants/{id}/toolkits returns the toolkit bindings as a HAL collection (rel inf:assistant-toolkits), each row embedding inf:toolkit (the read_access-scoped toolkit).
Response · 200
{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/assistants/admin%3Aorder-desk-assistant/toolkits"
    }
  },
  "start": 0,
  "count": 1,
  "total": 1,
  "_embedded": {
    "inf:assistant-toolkit": [
      {
        "_links": {
          "self": {
            "href": "https://informer.example.com/api/assistants/admin%3Aorder-desk-assistant/toolkits/00000000-0000-4000-8000-000000000001"
          }
        },
        "id": "00000000-0000-4000-8000-000000000002",
        "assistantId": "00000000-0000-4000-8000-000000000003",
        "toolkitId": "00000000-0000-4000-8000-000000000001",
        "createdAt": "2026-01-15T16:20:00.000Z",
        "updatedAt": "2026-01-15T16:20:00.000Z",
        "tenant": "acme",
        "_embedded": {
          "inf:toolkit": {
            "_links": {
              "self": {
                "href": "https://informer.example.com/api/toolkits/admin%3Aorder-tools"
              },
              "inf:toolkit-share": {
                "href": "https://informer.example.com/api/toolkits/admin%3Aorder-tools/shares/{principalId}",
                "templated": true
              },
              "inf:favorite": {
                "href": "https://informer.example.com/api/toolkits/admin%3Aorder-tools/favorite"
              },
              "inf:toolkit-owner": {
                "href": "https://informer.example.com/api/toolkits/admin%3Aorder-tools/owner"
              },
              "inf:toolkit-shares": {
                "href": "https://informer.example.com/api/toolkits/admin%3Aorder-tools/shares"
              },
              "inf:toolkit-tools": {
                "href": "https://informer.example.com/api/toolkits/admin%3Aorder-tools/tools"
              },
              "inf:toolkit-discover": {
                "href": "https://informer.example.com/api/toolkits/admin%3Aorder-tools/discover"
              }
            },
            "naturalId": "admin:order-tools",
            "allowUserInstances": true,
            "executionLocation": "server",
            "canManageTools": true,
            "permissions": {
              "write": true,
              "edit": true,
              "delete": true,
              "share": true,
              "assignTags": true,
              "changeOwner": true
            },
            "id": "00000000-0000-4000-8000-000000000001",
            "name": "Order Tools",
            "slug": "order-tools",
            "type": "custom",
            "description": "Helpers for the order desk.",
            "instructions": null,
            "ownerId": "admin",
            "shared": false,
            "folderId": null,
            "config": null,
            "integrationId": null,
            "source": null,
            "sourceId": null,
            "createdAt": "2026-01-15T16:20:00.000Z",
            "updatedAt": "2026-01-15T16:20:00.000Z",
            "tenant": "acme",
            "integration": null,
            "_embedded": {
              "inf:driver": {
                "_links": {
                  "self": {
                    "href": "https://informer.example.com/api/toolkits/admin%3Aorder-tools/driver"
                  }
                },
                "id": "custom",
                "name": "Integration Toolkit",
                "description": "Create API tools that call external services via an Integration",
                "image": "/images/icons/toolkit-server.svg",
                "viewComponent": "customToolkitView",
                "executionLocation": "server",
                "allowUserInstances": true,
                "canManageTools": true,
                "supportsIntegration": true,
                "editorComponent": {}
              }
            }
          }
        }
      }
    ]
  }
}
Captured from the API examples test suite; ids and timestamps are normalized.

POST /api/assistants/{id}/toolkits​

Bind a toolkit to the Assistant.

Authentication: Required (AI access + permission.assistant.write)

Request Body:

FieldTypeRequiredDescription
toolkitIdstringYesThe toolkit's id or natural id.

The binding is an idempotent upsert on UNIQUE(tenant, assistantId, toolkitId), so re-posting the same toolkit returns the existing binding instead of erroring. Returns 201 with a Location header pointing at the new binding.

Attach a toolkit to an assistantPOST /api/assistants/admin:order-desk-assistant/toolkits
POST /api/assistants/{id}/toolkits binds a toolkit to the assistant. Payload is { toolkitId } (the toolkit’s id or natural id). It is an idempotent upsert on UNIQUE(tenant, assistantId, toolkitId), so re-posting the same toolkit returns the existing binding rather than erroring. Requires assistant:write. Returns 201 with a Location header at the new binding.
Request body
{
  "toolkitId": "admin:order-tools"
}
Response · 201
{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/assistants/admin%3Aorder-desk-assistant/toolkits/00000000-0000-4000-8000-000000000001"
    }
  },
  "id": "00000000-0000-4000-8000-000000000002",
  "tenant": "acme",
  "assistantId": "00000000-0000-4000-8000-000000000003",
  "toolkitId": "00000000-0000-4000-8000-000000000001",
  "createdAt": "2026-01-15T16:20:00.000Z",
  "updatedAt": "2026-01-15T16:20:00.000Z"
}
Captured from the API examples test suite; ids and timestamps are normalized.

GET /api/assistants/{id}/toolkits/{toolkitId}​

Get a single binding.

Authentication: Required (AI access via ai.verify)

Returns the binding (embedding inf:toolkit). Responds 404 if the toolkit is not bound to this Assistant.

Get a single toolkit bindingGET /api/assistants/admin:order-desk-assistant/toolkits/00000000-0000-4000-8000-000000000001
GET /api/assistants/{id}/toolkits/{toolkitId} returns one binding (embedding the toolkit). 404 if the toolkit is not bound to this assistant.
Response · 200
{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/assistants/admin%3Aorder-desk-assistant/toolkits/00000000-0000-4000-8000-000000000001"
    }
  },
  "id": "00000000-0000-4000-8000-000000000002",
  "assistantId": "00000000-0000-4000-8000-000000000003",
  "toolkitId": "00000000-0000-4000-8000-000000000001",
  "createdAt": "2026-01-15T16:20:00.000Z",
  "updatedAt": "2026-01-15T16:20:00.000Z",
  "tenant": "acme",
  "_embedded": {
    "inf:toolkit": {
      "_links": {
        "self": {
          "href": "https://informer.example.com/api/toolkits/admin%3Aorder-tools"
        },
        "inf:toolkit-share": {
          "href": "https://informer.example.com/api/toolkits/admin%3Aorder-tools/shares/{principalId}",
          "templated": true
        },
        "inf:favorite": {
          "href": "https://informer.example.com/api/toolkits/admin%3Aorder-tools/favorite"
        },
        "inf:toolkit-owner": {
          "href": "https://informer.example.com/api/toolkits/admin%3Aorder-tools/owner"
        },
        "inf:toolkit-shares": {
          "href": "https://informer.example.com/api/toolkits/admin%3Aorder-tools/shares"
        },
        "inf:toolkit-tools": {
          "href": "https://informer.example.com/api/toolkits/admin%3Aorder-tools/tools"
        },
        "inf:toolkit-discover": {
          "href": "https://informer.example.com/api/toolkits/admin%3Aorder-tools/discover"
        }
      },
      "naturalId": "admin:order-tools",
      "allowUserInstances": true,
      "executionLocation": "server",
      "canManageTools": true,
      "permissions": {
        "write": true,
        "edit": true,
        "delete": true,
        "share": true,
        "assignTags": true,
        "changeOwner": true
      },
      "id": "00000000-0000-4000-8000-000000000001",
      "name": "Order Tools",
      "slug": "order-tools",
      "type": "custom",
      "description": "Helpers for the order desk.",
      "instructions": null,
      "ownerId": "admin",
      "shared": false,
      "folderId": null,
      "config": null,
      "integrationId": null,
      "source": null,
      "sourceId": null,
      "createdAt": "2026-01-15T16:20:00.000Z",
      "updatedAt": "2026-01-15T16:20:00.000Z",
      "tenant": "acme",
      "integration": null,
      "_embedded": {
        "inf:driver": {
          "_links": {
            "self": {
              "href": "https://informer.example.com/api/toolkits/admin%3Aorder-tools/driver"
            }
          },
          "id": "custom",
          "name": "Integration Toolkit",
          "description": "Create API tools that call external services via an Integration",
          "image": "/images/icons/toolkit-server.svg",
          "viewComponent": "customToolkitView",
          "executionLocation": "server",
          "allowUserInstances": true,
          "canManageTools": true,
          "supportsIntegration": true,
          "editorComponent": {}
        }
      }
    }
  }
}
Captured from the API examples test suite; ids and timestamps are normalized.

DELETE /api/assistants/{id}/toolkits/{toolkitId}​

Detach a toolkit from the Assistant.

Authentication: Required (AI access + permission.assistant.write)

Removes the binding and responds 200 with an empty body (Informer convention). Detach resolves the join row directly, so it does not require read access on the toolkit — you can revoke a binding even after the toolkit share that created it has been pulled.

Detach a toolkitDELETE /api/assistants/admin:order-desk-assistant/toolkits/00000000-0000-4000-8000-000000000001
DELETE /api/assistants/{id}/toolkits/{toolkitId} removes the binding and returns 200 with an empty body (Informer convention). It resolves the join row directly, so detaching does NOT require read access on the toolkit. Requires assistant:write.
Response · 200 · no body
Captured from the API examples test suite; ids and timestamps are normalized.