Bulk Save Tag Definitions

Declare, in one request, several of the knowledge base's tag definitions. POST on this path defines exactly one tag; this is the same write over a list, and every slot the body names is written to the declaration it carries while slots it does not name are left alone. Updating an existing definition requires naming its current name in originalDisplayName; that is the only form that edits one in place. Without it the entry is a create, and a requested tagSlot another name already holds is refused in errors — it is neither overwritten nor relocated to a different slot, so an explicitly requested slot always means that slot or an error. A create whose displayName already exists is refused in errors. Per-definition failures are reported in errors and still answer 200. This writes the vocabulary, not one document's tag values — set those with PATCH /api/v2/knowledge/{knowledgeBaseId}/documents/{documentId}. A workspace API key is rejected with 403; use a personal API key.

PUT/api/v2/knowledge/{knowledgeBaseId}/tags

Authorization

apiKey
X-API-Key<token>

Your Sim API key, personal or workspace-scoped. Generate one under Settings, then API Keys. Operations that reject workspace keys say so in their own description.

In: header

Path Parameters

knowledgeBaseId*string

Unique knowledge base identifier.

Length1 <= length

Request Body

application/json

Workspace scope and the tag definitions to create or update.

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://www.sim.ai/api/v2/knowledge/string/tags" \  -H "X-API-Key: YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",    "definitions": [      {        "tagSlot": "tag1",        "displayName": "category",        "fieldType": "text"      }    ]  }'
{
  "data": {
    "created": [
      {
        "id": "string",
        "displayName": "category",
        "tagSlot": "tag1",
        "fieldType": "text"
      }
    ],
    "updated": [
      {
        "id": "string",
        "displayName": "category",
        "tagSlot": "tag1",
        "fieldType": "text"
      }
    ],
    "errors": [
      "string"
    ]
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request"
  }
}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key required"
  }
}
{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient workspace permissions",
    "details": {
      "code": "INSUFFICIENT_WORKSPACE_ROLE"
    }
  }
}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Not found"
  }
}
{
  "error": {
    "code": "PAYLOAD_TOO_LARGE",
    "message": "Request body is too large"
  }
}
{
  "error": {
    "code": "UNSUPPORTED_MEDIA_TYPE",
    "message": "Request body must be sent as application/json"
  }
}
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "API rate limit exceeded",
    "details": {
      "retryAfter": "2026-01-01T00:00:30.000Z"
    }
  }
}
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  }
}
{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable"
  }
}