{ "servers": [ { "url": "{protocol}://{WEAVIATE_HOSTNAME}:{PORT}/v1", "variables": { "protocol": { "default": "https", "enum": ["http", "https"] }, "WEAVIATE_HOSTNAME": { "default": "localhost", "description": "Weaviate server hostname" }, "PORT": { "default": "8080", "description": "Weaviate server port" } } } ], "consumes": [ "application/json" ], "definitions": { "UserTypeInput": { "type": "string", "enum": [ "db", "oidc" ], "description": "The type of the user. `db` users are managed by Weaviate, `oidc` users are managed by an external OIDC provider." }, "GroupType": { "type": "string", "enum": [ "oidc" ], "description": "If the group contains OIDC or database users." }, "UserTypeOutput": { "type": "string", "enum": [ "db_user", "db_env_user", "oidc" ], "description": "The type of the user. `db_user` users are created through the `users` API, `db_env_user` users are created through environment variables, and `oidc` users are managed by an external OIDC provider." }, "UserOwnInfo": { "type": "object", "properties": { "groups": { "type": "array", "description": "The groups associated with the user.", "items": { "type": "string" } }, "roles": { "type": "array", "items": { "type": "object", "description": "The roles assigned to the user.", "$ref": "#/definitions/Role" } }, "username": { "type": "string", "description": "The name (ID) of the user." } }, "required": [ "username" ] }, "DBUserInfo": { "type": "object", "properties": { "roles": { "type": "array", "description": "The roles associated with the user.", "items": { "type": "string" } }, "userId": { "type": "string", "description": "The name (ID) of the user." }, "dbUserType": { "type": "string", "enum": [ "db_user", "db_env_user" ], "description": "Type of the returned user." }, "active": { "type": "boolean", "description": "Activity status of the returned user." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Date and time in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ." }, "apiKeyFirstLetters": { "type": [ "string", "null" ], "maxLength": 3, "description": "First 3 letters of the associated API key." }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Date and time in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ." }, "namespace": { "type": "string", "description": "The namespace this user is bound to. Only populated for callers with global-operator privileges; omitted otherwise." } }, "required": [ "userId", "dbUserType", "roles", "active" ] }, "UserApiKey": { "type": "object", "properties": { "apikey": { "type": "string", "description": "The API key associated with the user." } }, "required": [ "apikey" ] }, "Role": { "type": "object", "properties": { "name": { "type": "string", "description": "The name (ID) of the role." }, "permissions": { "type": "array", "items": { "type": "object", "description": "The list of permissions assigned to this role (level, action, resource).", "$ref": "#/definitions/Permission" } } }, "required": [ "name", "permissions" ] }, "Permission": { "type": "object", "description": "Permissions attached to a role.", "properties": { "backups": { "type": "object", "description": "Resources applicable for backup actions.", "properties": { "collection": { "type": "string", "default": "*", "description": "A string that specifies which collections this permission applies to. Can be an exact collection name or a regex pattern. The default value `*` applies the permission to all collections." } } }, "data": { "type": "object", "description": "Resources applicable for data actions.", "properties": { "collection": { "type": "string", "default": "*", "description": "A string that specifies which collections this permission applies to. Can be an exact collection name or a regex pattern. The default value `*` applies the permission to all collections." }, "tenant": { "type": "string", "default": "*", "description": "A string that specifies which tenants this permission applies to. Can be an exact tenant name or a regex pattern. The default value `*` applies the permission to all tenants." }, "object": { "type": "string", "default": "*", "description": "A string that specifies which objects this permission applies to. Can be an exact object ID or a regex pattern. The default value `*` applies the permission to all objects." } } }, "nodes": { "type": "object", "description": "Resources applicable for cluster actions.", "properties": { "verbosity": { "type": "string", "default": "minimal", "enum": [ "verbose", "minimal" ], "description": "Whether to allow (verbose) returning shards and stats data in the response." }, "collection": { "type": "string", "default": "*", "description": "A string that specifies which collections this permission applies to. Can be an exact collection name or a regex pattern. The default value `*` applies the permission to all collections." } } }, "users": { "type": "object", "description": "Resources applicable for user actions.", "properties": { "users": { "type": "string", "default": "*", "description": "A string that specifies which users this permission applies to. Can be an exact user name or a regex pattern. The default value `*` applies the permission to all users." } } }, "groups": { "type": "object", "description": "Resources applicable for group actions.", "properties": { "group": { "type": "string", "default": "*", "description": "A string that specifies which groups this permission applies to. Can be an exact group name or a regex pattern. The default value `*` applies the permission to all groups." }, "groupType": { "$ref": "#/definitions/GroupType" } } }, "tenants": { "type": "object", "description": "Resources applicable for tenant actions.", "properties": { "collection": { "type": "string", "default": "*", "description": "A string that specifies which collections this permission applies to. Can be an exact collection name or a regex pattern. The default value `*` applies the permission to all collections." }, "tenant": { "type": "string", "default": "*", "description": "A string that specifies which tenants this permission applies to. Can be an exact tenant name or a regex pattern. The default value `*` applies the permission to all tenants." } } }, "roles": { "type": "object", "description": "Resources applicable for role actions.", "properties": { "role": { "type": "string", "default": "*", "description": "A string that specifies which roles this permission applies to. Can be an exact role name or a regex pattern. The default value `*` applies the permission to all roles." }, "scope": { "enum": [ "all", "match" ], "type": "string", "default": "match", "description": "Set the scope for the manage role permission." } } }, "collections": { "type": "object", "description": "Resources applicable for collection and/or tenant actions.", "properties": { "collection": { "type": "string", "default": "*", "description": "A string that specifies which collections this permission applies to. Can be an exact collection name or a regex pattern. The default value `*` applies the permission to all collections." } } }, "replicate": { "type": "object", "description": "resources applicable for replicate actions", "properties": { "collection": { "type": "string", "default": "*", "description": "string or regex. if a specific collection name, if left empty it will be ALL or *" }, "shard": { "type": "string", "default": "*", "description": "string or regex. if a specific shard name, if left empty it will be ALL or *" } } }, "aliases": { "type": "object", "description": "Resource definition for alias-related actions and permissions. Used to specify which aliases and collections can be accessed or modified.", "properties": { "collection": { "type": "string", "default": "*", "description": "A string that specifies which collections this permission applies to. Can be an exact collection name or a regex pattern. The default value `*` applies the permission to all collections." }, "alias": { "type": "string", "default": "*", "description": "A string that specifies which aliases this permission applies to. Can be an exact alias name or a regex pattern. The default value `*` applies the permission to all aliases." } } }, "namespaces": { "type": "object", "description": "Resources applicable for namespace actions.", "properties": { "namespace": { "type": "string", "default": "*", "description": "A string that specifies which namespaces this permission applies to. Can be an exact namespace name or a regex pattern. The default value `*` applies the permission to all namespaces." } } }, "action": { "type": "string", "description": "Allowed actions in weaviate.", "enum": [ "manage_backups", "read_cluster", "create_data", "read_data", "update_data", "delete_data", "read_nodes", "create_roles", "read_roles", "update_roles", "delete_roles", "create_collections", "read_collections", "update_collections", "delete_collections", "assign_and_revoke_users", "create_users", "read_users", "update_users", "delete_users", "create_tenants", "read_tenants", "update_tenants", "delete_tenants", "create_replicate", "read_replicate", "update_replicate", "delete_replicate", "create_aliases", "read_aliases", "update_aliases", "delete_aliases", "assign_and_revoke_groups", "read_groups", "create_mcp", "read_mcp", "update_mcp", "manage_namespaces" ] } }, "required": [ "action" ] }, "RolesListResponse": { "type": "array", "description": "List of roles.", "items": { "$ref": "#/definitions/Role" } }, "Link": { "type": "object", "properties": { "href": { "type": "string", "description": "Target of the link." }, "rel": { "type": "string", "description": "Relationship if both resources are related, e.g. 'next', 'previous', 'parent', etc." }, "name": { "type": "string", "description": "Human readable name of the resource group." }, "documentationHref": { "type": "string", "description": "Weaviate documentation about this resource group." } } }, "Principal": { "type": "object", "properties": { "username": { "type": "string", "description": "The username that was extracted either from the authentication information" }, "groups": { "type": "array", "items": { "type": "string" } }, "userType": { "$ref": "#/definitions/UserTypeInput" }, "namespace": { "type": "string", "description": "The namespace this principal is bound to. Empty for global principals (e.g. static API keys)." }, "isGlobalOperator": { "type": "boolean", "description": "True for principals that operate across all namespaces (e.g. static API keys). Authoritative marker for operator-level principals; do not infer from an empty namespace." } } }, "C11yWordsResponse": { "description": "An array of available words and contexts.", "properties": { "concatenatedWord": { "description": "Weighted results for all words", "type": "object", "properties": { "concatenatedWord": { "type": "string" }, "singleWords": { "type": "array", "items": { "format": "string" } }, "concatenatedVector": { "$ref": "#/definitions/C11yVector" }, "concatenatedNearestNeighbors": { "$ref": "#/definitions/C11yNearestNeighbors" } } }, "individualWords": { "description": "Weighted results for per individual word", "type": "array", "items": { "type": "object", "properties": { "word": { "type": "string" }, "present": { "type": "boolean" }, "info": { "type": "object", "properties": { "vector": { "$ref": "#/definitions/C11yVector" }, "nearestNeighbors": { "$ref": "#/definitions/C11yNearestNeighbors" } } } } } } } }, "C11yExtension": { "description": "A resource describing an extension to the contextinoary, containing both the identifier and the definition of the extension", "properties": { "concept": { "description": "The new concept you want to extend. Must be an all-lowercase single word, or a space delimited compound word. Examples: 'foobarium', 'my custom concept'", "type": "string", "example": "foobarium" }, "definition": { "description": "A list of space-delimited words or a sentence describing what the custom concept is about. Avoid using the custom concept itself. An Example definition for the custom concept 'foobarium': would be 'a naturally occurring element which can only be seen by programmers'", "type": "string" }, "weight": { "description": "Weight of the definition of the new concept where 1='override existing definition entirely' and 0='ignore custom definition'. Note that if the custom concept is not present in the contextionary yet, the weight cannot be less than 1.", "type": "number", "format": "float" } } }, "C11yNearestNeighbors": { "description": "C11y function to show the nearest neighbors to a word.", "type": "array", "items": { "type": "object", "properties": { "word": { "type": "string" }, "distance": { "type": "number", "format": "float" } } } }, "C11yVector": { "description": "A vector representation of the object in the Contextionary. If provided at object creation, this wil take precedence over any vectorizer setting.", "type": "array", "items": { "type": "number", "format": "float" } }, "Vector": { "description": "A vector representation of the object. If provided at object creation, this wil take precedence over any vectorizer setting.", "type": "object" }, "Vectors": { "description": "A map of named vectors for multi-vector representations.", "type": "object", "additionalProperties": { "$ref": "#/definitions/Vector" } }, "Deprecation": { "type": "object", "properties": { "id": { "type": "string", "description": "The id that uniquely identifies this particular deprecation (mostly used internally)." }, "status": { "type": "string", "description": "Whether the problematic API functionality is deprecated (planned to be removed) or already removed." }, "apiType": { "type": "string", "description": "Describes which API is affected, usually one of: REST, GraphQL and gRPC." }, "msg": { "type": "string", "description": "What this deprecation is about." }, "mitigation": { "type": "string", "description": "User-required object to not be affected by the (planned) removal." }, "sinceVersion": { "type": "string", "description": "The deprecation was introduced in this version." }, "plannedRemovalVersion": { "type": "string", "description": "A best-effort guess of which upcoming version will remove the feature entirely." }, "removedIn": { "type": "string", "description": "If the feature has already been removed, it was removed in this version.", "x-nullable": true }, "removedTime": { "type": "string", "format": "date-time", "description": "If the feature has already been removed, it was removed at this timestamp.", "x-nullable": true }, "sinceTime": { "type": "string", "format": "date-time", "description": "The deprecation was introduced at this timestamp." }, "locations": { "type": "array", "description": "The locations within the specified API affected by this deprecation.", "items": { "type": "string" } } } }, "ErrorResponse": { "description": "An error response returned by Weaviate endpoints.", "properties": { "error": { "items": { "properties": { "message": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "IndexStatusResponse": { "type": "object", "properties": { "collection": { "type": "string" }, "properties": { "type": "array", "items": { "$ref": "#/definitions/PropertyIndexStatus" } } } }, "PropertyIndexStatus": { "type": "object", "properties": { "name": { "type": "string" }, "dataType": { "type": "string" }, "description": { "type": "string" }, "indexes": { "type": "array", "items": { "$ref": "#/definitions/IndexStatus" } } } }, "IndexStatus": { "type": "object", "properties": { "type": { "type": "string", "description": "Canonical inverted-index type. Always one of `filterable`, `searchable`, `rangeFilters` — never the `rangeable` write-path alias.", "enum": [ "filterable", "searchable", "rangeFilters" ] }, "status": { "type": "string", "enum": [ "ready", "indexing", "pending", "failed", "cancelled" ] }, "progress": { "type": "number", "format": "float" }, "taskId": { "type": "string", "description": "ID of the reindex task driving this index entry. Present on every task-driven entry (`pending`, `indexing`, `failed`, `cancelled`, and the finalize-window override); absent on a plain `ready` entry. A coupled searchable+filterable tokenization migration reports the same `taskId` on both affected entries." }, "tokenization": { "type": "string" }, "targetTokenization": { "type": "string" }, "algorithm": { "type": "string", "enum": [ "wand", "blockmax" ], "description": "BM25 algorithm currently backing this searchable index. 'wand' is the legacy map-based bucket strategy; 'blockmax' is the Block Max WAND inverted strategy. Only populated for `type=searchable` entries. Not populated for filterable or rangeable indexes." }, "targetAlgorithm": { "type": "string", "enum": [ "wand", "blockmax" ], "description": "BM25 algorithm this searchable index is being rebuilt onto. Populated only while an in-flight rebuild is changing the algorithm; mirrors `targetTokenization` for the change-tokenization verb. Today the only supported transition is wand -> blockmax." } } }, "IndexUpsertRequest": { "type": "object", "description": "Desired index configuration for `PUT /v1/schema/{className}/properties/{propertyName}/index/{indexType}`. The server diffs the body against the current state and either creates the index, migrates its configuration, or returns a NO_OP. Only fields relevant to the target index type are honored: `tokenization` applies to `searchable`/`filterable`, `algorithm` applies to `searchable`. `rangeFilters` takes no config fields. An empty body `{}` is valid and means \"ensure the index exists with its current/default config\". At most one configuration change may be requested per call (a body implying both a tokenization and an algorithm change is rejected).", "properties": { "tokenization": { "type": "string", "description": "Target tokenization for a `searchable` or `filterable` index. Required when creating a `searchable` index; optional otherwise (omitted = keep the current value). On `filterable` creation it must be omitted or equal the property's current tokenization." }, "algorithm": { "type": "string", "description": "Target BM25 algorithm for a `searchable` index. Only `blockmax` is a valid target (input aliases `block-max`, `block_max`, `blockmaxwand`, `bmw` are accepted case-insensitively). From WAND this triggers the Map → BlockMax migration; on an already-`blockmax` index it is a NO_OP. `wand` is rejected (deprecated); downgrade is intentionally not supported." } } }, "IndexUpdateResponse": { "type": "object", "properties": { "taskId": { "type": "string" }, "status": { "type": "string" } } }, "UsageLimitExceededResponse": { "description": "Returned with HTTP 429 when a configured Weaviate usage limit (objects/collections/tenants/shards) is exceeded. The structured fields (`errorCode`, `limit`, `value`) are stable contract; the `message` text is operator-overridable via the `USAGE_LIMITS_ERROR_MESSAGE` template.", "type": "object", "properties": { "errorCode": { "type": "string", "description": "Machine-stable identifier. Always `USAGE_LIMIT_EXCEEDED` for this response.", "enum": [ "USAGE_LIMIT_EXCEEDED" ] }, "limit": { "type": "string", "description": "Which limit was hit.", "enum": [ "objects", "collections", "tenants", "shards" ] }, "value": { "type": "integer", "format": "int64", "description": "The configured threshold value (the cap, not the current count)." }, "message": { "type": "string", "description": "Human-readable message rendered from the `USAGE_LIMITS_ERROR_MESSAGE` template with `{limit}` and `{value}` placeholders substituted." } } }, "RestrictionViolationResponse": { "description": "Returned with HTTP 422 from class create/update endpoints. For restriction violations (operator-disallowed config via ALLOWED_VECTOR_INDEX_TYPES or ALLOWED_COMPRESSION_TYPES) the structured fields (`errorCode`, `restriction`, `value`, `allowed`, `message`) are populated; the `message` text is rendered from the operator-overridable `RESTRICTIONS_ERROR_MESSAGE` template. For unrelated 422 errors the `error` array is populated (matching the legacy ErrorResponse shape) and the structured fields are omitted.", "type": "object", "properties": { "error": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" } } }, "description": "Legacy ErrorResponse-style error list, populated for non-restriction 422 errors." }, "errorCode": { "type": "string", "description": "Machine-stable identifier. Set to `CONFIG_NOT_ALLOWED` for restriction violations; omitted otherwise.", "enum": [ "CONFIG_NOT_ALLOWED" ] }, "restriction": { "type": "string", "description": "Which restriction was violated.", "enum": [ "vector_index_type", "compression" ] }, "value": { "type": "string", "description": "The disallowed value the client submitted." }, "allowed": { "type": "array", "items": { "type": "string" }, "description": "The operator-configured allow-list." }, "message": { "type": "string", "description": "Human-readable message rendered from the `RESTRICTIONS_ERROR_MESSAGE` template with `{restriction}`, `{value}`, `{allowed}` placeholders substituted." } } }, "ExportCreateRequest": { "description": "Request to create a new export operation", "type": "object", "required": [ "id", "file_format" ], "properties": { "id": { "type": "string", "description": "Unique identifier for this export. Must be URL-safe." }, "file_format": { "type": "string", "description": "Output file format for the export.", "enum": [ "parquet" ] }, "include": { "type": "array", "items": { "type": "string" }, "description": "List of collection names to include in the export. Cannot be used with 'exclude'." }, "exclude": { "type": "array", "items": { "type": "string" }, "description": "List of collection names to exclude from the export. Cannot be used with 'include'." } } }, "ExportCreateResponse": { "description": "Response from creating an export operation", "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for this export" }, "backend": { "type": "string", "description": "The backend storage system used" }, "path": { "type": "string", "description": "Full path where the export is being written" }, "status": { "type": "string", "description": "Current status of the export", "enum": [ "STARTED" ] }, "startedAt": { "type": "string", "format": "date-time", "description": "When the export started" }, "classes": { "type": "array", "items": { "type": "string" }, "description": "List of collections being exported" } } }, "ExportStatusResponse": { "description": "Current status of an export operation", "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for this export" }, "backend": { "type": "string", "description": "The backend storage system used" }, "path": { "type": "string", "description": "Full path where the export is stored" }, "status": { "type": "string", "description": "Current status of the export", "enum": [ "STARTED", "TRANSFERRING", "SUCCESS", "FAILED", "CANCELED" ] }, "startedAt": { "type": "string", "format": "date-time", "description": "When the export started" }, "completedAt": { "type": "string", "format": "date-time", "description": "When the export completed (successfully, with failure, or was canceled)" }, "tookInMs": { "type": "integer", "format": "int64", "description": "Duration of the export in milliseconds" }, "classes": { "type": "array", "items": { "type": "string" }, "description": "List of collections in this export" }, "shardStatus": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "$ref": "#/definitions/ShardProgress" } }, "description": "Per-shard progress: className -> shardName -> status" }, "error": { "type": "string", "description": "Error message if export failed" } } }, "ShardProgress": { "description": "Progress information for exporting a single shard", "type": "object", "properties": { "status": { "type": "string", "description": "Status of this shard's export", "enum": [ "TRANSFERRING", "SUCCESS", "FAILED", "SKIPPED" ] }, "objectsExported": { "type": "integer", "format": "int64", "description": "Number of objects exported from this shard" }, "error": { "type": "string", "description": "Error message if this shard's export failed" }, "skipReason": { "type": "string", "description": "Reason why this shard was skipped (e.g. tenant status)" } } }, "GraphQLError": { "description": "An error response caused by a GraphQL query.", "properties": { "locations": { "items": { "properties": { "column": { "format": "int64", "type": "integer" }, "line": { "format": "int64", "type": "integer" } }, "type": "object" }, "type": "array" }, "message": { "type": "string" }, "path": { "items": { "type": "string" }, "type": "array" } } }, "GraphQLQuery": { "description": "GraphQL query based on: http://facebook.github.io/graphql/.", "properties": { "operationName": { "description": "The name of the operation if multiple exist in the query.", "type": "string" }, "query": { "description": "Query based on GraphQL syntax.", "type": "string" }, "variables": { "description": "Additional variables for the query.", "type": "object" } }, "type": "object" }, "GraphQLQueries": { "description": "A list of GraphQL queries.", "items": { "$ref": "#/definitions/GraphQLQuery" }, "type": "array" }, "GraphQLResponse": { "description": "GraphQL based response: http://facebook.github.io/graphql/.", "properties": { "data": { "additionalProperties": { "$ref": "#/definitions/JsonObject" }, "description": "GraphQL data object.", "type": "object" }, "errors": { "description": "Array with errors.", "items": { "$ref": "#/definitions/GraphQLError" }, "x-omitempty": true, "type": "array" } } }, "GraphQLResponses": { "description": "A list of GraphQL responses.", "items": { "$ref": "#/definitions/GraphQLResponse" }, "type": "array" }, "InvertedIndexConfig": { "description": "Configure the inverted index built into Weaviate. See [Reference: Inverted index](https://docs.weaviate.io/weaviate/config-refs/indexing/inverted-index#inverted-index-parameters) for details.", "properties": { "cleanupIntervalSeconds": { "description": "Asynchronous index clean up happens every n seconds (default: 60).", "format": "int", "type": "number" }, "bm25": { "$ref": "#/definitions/BM25Config" }, "stopwords": { "$ref": "#/definitions/StopwordConfig" }, "indexTimestamps": { "description": "Index each object by its internal timestamps (default: `false`).", "type": "boolean" }, "indexNullState": { "description": "Index each object with the null state (default: `false`).", "type": "boolean" }, "indexPropertyLength": { "description": "Index length of properties (default: `false`).", "type": "boolean" }, "usingBlockMaxWAND": { "description": "Using BlockMax WAND for query execution (default: `false`, will be `true` for new collections created after 1.30).", "type": "boolean" }, "tokenizerUserDict": { "description": "User-defined dictionary for tokenization.", "type": "array", "x-omitempty": true, "items": { "$ref": "#/definitions/TokenizerUserDictConfig" } }, "stopwordPresets": { "description": "User-defined named stopword lists. Each key is a preset name that can be referenced by a property's textAnalyzer.stopwordPreset field. The value is an array of stopword strings. Preset names must not be empty or whitespace-only; each list must contain at least one word; individual words must not be empty or whitespace-only.", "type": "object", "x-omitempty": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "ReplicationConfig": { "description": "Configure how replication is executed in a cluster", "properties": { "factor": { "description": "Number of times a collection (class) is replicated (default: 1).", "type": "integer" }, "asyncConfig": { "description": "Configuration parameters for asynchronous replication.", "$ref": "#/definitions/ReplicationAsyncConfig", "x-omitempty": true }, "deletionStrategy": { "description": "Conflict resolution strategy for deleted objects.", "type": "string", "enum": [ "NoAutomatedResolution", "DeleteOnConflict", "TimeBasedResolution" ], "x-omitempty": true } }, "type": "object" }, "BM25Config": { "description": "Tuning parameters for the BM25 algorithm.", "properties": { "k1": { "description": "Calibrates term-weight scaling based on the term frequency within a document (default: 1.2).", "format": "float", "type": "number" }, "b": { "description": "Calibrates term-weight scaling based on the document length (default: 0.75).", "format": "float", "type": "number" } }, "type": "object" }, "StopwordConfig": { "description": "Fine-grained control over stopword list usage.", "properties": { "preset": { "description": "Pre-existing list of common words by language (default: `en`). Options: [`en`, `none`].", "type": "string" }, "additions": { "description": "Stopwords to be considered additionally (default: []). Can be any array of custom strings.", "type": "array", "items": { "type": "string" } }, "removals": { "description": "Stopwords to be removed from consideration (default: []). Can be any array of custom strings.", "type": "array", "items": { "type": "string" } } }, "type": "object" }, "TokenizerUserDictConfig": { "description": "A list of pairs of strings that should be replaced with another string during tokenization.", "type": "object", "properties": { "tokenizer": { "description": "The tokenizer to which the user dictionary should be applied. Currently, only the `kagame` ja and kr tokenizers supports user dictionaries.", "type": "string" }, "replacements": { "type": "array", "items": { "type": "object", "properties": { "source": { "description": "The string to be replaced.", "type": "string" }, "target": { "description": "The string to replace with.", "type": "string" } }, "required": [ "source", "target" ] } } } }, "TokenizeRequest": { "description": "Request body for the generic tokenize endpoint.", "type": "object", "required": [ "text", "tokenization" ], "properties": { "text": { "description": "The text to tokenize.", "type": "string" }, "tokenization": { "description": "The tokenization method to apply.", "type": "string", "enum": [ "word", "lowercase", "whitespace", "field", "trigram", "gse", "kagome_kr", "kagome_ja", "gse_ch" ] }, "analyzerConfig": { "description": "Optional text analyzer configuration (e.g. ASCII folding).", "$ref": "#/definitions/TextAnalyzerConfig" }, "stopwords": { "description": "Optional fallback stopword configuration. Used when analyzerConfig.stopwordPreset is not set. Shape matches InvertedIndexConfig.stopwords on a collection. When analyzerConfig.stopwordPreset is not set and this field is omitted, word tokenization defaults to preset 'en'. Mutually exclusive with stopwordPresets — pass one or the other, not both.", "$ref": "#/definitions/StopwordConfig" }, "stopwordPresets": { "description": "Optional user-defined named stopword presets. Shape matches InvertedIndexConfig.stopwordPresets on a collection: each key is a preset name, each value is a plain list of stopwords. A preset name that matches a built-in ('en', 'none') fully replaces the built-in. Preset names must not be empty or whitespace-only; each word list must contain at least one word; individual words must not be empty or whitespace-only. Mutually exclusive with stopwords — pass one or the other, not both.", "type": "object", "x-omitempty": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }, "TokenizeResponse": { "description": "Response from the tokenize endpoints. Returns `indexed` text and text used at `query` time", "type": "object", "properties": { "indexed": { "description": "The tokens as they would be stored in the inverted index.", "type": "array", "items": { "type": "string" } }, "query": { "description": "The tokens as they would be used for query matching (e.g., after stopword removal).", "type": "array", "items": { "type": "string" } } } }, "PropertyTokenizeRequest": { "description": "Request body for the property-specific tokenize endpoint.", "type": "object", "required": [ "text" ], "properties": { "text": { "description": "The text to tokenize using the property's configured tokenization.", "type": "string" } } }, "MultiTenancyConfig": { "description": "Configuration related to multi-tenancy within a collection (class)", "properties": { "enabled": { "description": "Whether or not multi-tenancy is enabled for this collection (class) (default: `false`).", "type": "boolean", "x-omitempty": false }, "autoTenantCreation": { "description": "Nonexistent tenants should (not) be created implicitly (default: `false`).", "type": "boolean", "x-omitempty": false }, "autoTenantActivation": { "description": "Existing tenants should (not) be turned HOT implicitly when they are accessed and in another activity status (default: `false`).", "type": "boolean", "x-omitempty": false } } }, "ObjectTtlConfig": { "description": "Configuration of objects' time-to-live", "properties": { "enabled": { "description": "Whether or not object ttl is enabled for this collection (default: `false`).", "type": "boolean", "x-omitempty": false }, "defaultTtl": { "description": "Interval (in seconds) to be added to `deleteOn` value, denoting object's expiration time. Has to be positive for `deleteOn` set to `_creationTimeUnix` or `_lastUpdateTimeUnix`, any for custom property (default: `0`).", "type": "integer", "x-omitempty": false }, "deleteOn": { "description": "Name of the property holding base time to compute object's expiration time (ttl = value of deleteOn property + defaultTtl). Can be set to `_creationTimeUnix`, `_lastUpdateTimeUnix` or custom property of `date` datatype.", "type": "string", "x-omitempty": false }, "filterExpiredObjects": { "description": "Whether remove from resultset expired, but not yet deleted by background process objects (default: `false`).", "type": "boolean", "x-omitempty": false } } }, "JsonObject": { "description": "JSON object value.", "type": "object" }, "Meta": { "description": "Contains meta information of the current Weaviate instance.", "properties": { "hostname": { "description": "The url of the host.", "format": "url", "type": "string" }, "version": { "description": "The Weaviate server version.", "type": "string" }, "modules": { "description": "Module-specific meta information.", "type": "object" }, "grpcMaxMessageSize": { "description": "Max message size for GRPC connection in bytes.", "type": "integer" } }, "type": "object" }, "MultipleRef": { "description": "Multiple instances of references to other objects.", "items": { "$ref": "#/definitions/SingleRef" }, "type": "array" }, "ReplicationReplicateReplicaRequest": { "description": "Specifies the parameters required to initiate a shard replica movement operation between two nodes for a given collection and shard. This request defines the source and target node, the collection and type of transfer.", "properties": { "sourceNode": { "description": "The name of the Weaviate node currently hosting the shard replica that needs to be moved or copied.", "type": "string" }, "targetNode": { "description": "The name of the Weaviate node where the new shard replica will be created as part of the movement or copy operation.", "type": "string" }, "collection": { "description": "The name of the collection to which the target shard belongs.", "type": "string" }, "shard": { "description": "The name of the shard whose replica is to be moved or copied.", "type": "string" }, "type": { "description": "Specifies the type of replication operation to perform. `COPY` creates a new replica on the target node while keeping the source replica. `MOVE` creates a new replica on the target node and then removes the source replica upon successful completion. Defaults to `COPY` if omitted.", "type": "string", "enum": [ "COPY", "MOVE" ], "default": "COPY" } }, "type": "object", "required": [ "sourceNode", "targetNode", "collection", "shard" ] }, "ReplicationReplicateReplicaResponse": { "description": "Contains the unique identifier for a successfully initiated asynchronous replica movement operation. This ID can be used to track the progress of the operation.", "properties": { "id": { "description": "The unique identifier (ID) assigned to the registered replication operation.", "format": "uuid", "type": "string" } }, "type": "object", "required": [ "id" ] }, "ReplicationShardingStateResponse": { "description": "Provides the detailed sharding state for one or more collections, including the distribution of shards and their replicas across the cluster nodes.", "properties": { "shardingState": { "$ref": "#/definitions/ReplicationShardingState" } }, "type": "object" }, "ReplicationScalePlan": { "type": "object", "description": "Defines a complete plan for scaling replication within a collection. Each shard entry specifies nodes to remove and nodes to add. Added nodes may either be initialized empty (null) or created by replicating data from a source node specified as a string. If a source node is also marked for removal in the same shard, it represents a move operation and can only be used once as a source for that shard. If a source node is not marked for removal, it represents a copy operation and can be used as the source for multiple additions in that shard. Nodes listed in 'removeNodes' cannot also appear as targets in 'addNodes' for the same shard, and the same node cannot be specified for both addition and removal in a single shard.", "properties": { "planId": { "type": "string", "format": "uuid", "description": "A unique identifier for this replication scaling plan, useful for tracking and auditing purposes.", "x-nullable": false }, "collection": { "type": "string", "description": "The name of the collection to which this replication scaling plan applies.", "x-nullable": false }, "shardScaleActions": { "type": "object", "description": "A mapping of shard names to their corresponding scaling actions. Each key corresponds to a shard name, and its value defines which nodes should be removed and which should be added for that shard. If a source node listed for an addition is also in 'removeNodes' for the same shard, that addition is treated as a move operation. Such a node can appear only once as a source in that shard. Otherwise, if the source node is not being removed, it represents a copy operation and can be referenced multiple times as a source for additions.", "additionalProperties": { "type": "object", "description": "Scaling actions for a single shard, including which nodes to remove and which to add. Nodes listed in 'removeNodes' cannot appear as targets in 'addNodes' for the same shard. If a source node is also marked for removal, it is treated as a move operation and can only appear once as a source node in that shard. A source node that is not being removed can appear multiple times as a source node for additions in that shard (copy operations).", "properties": { "removeNodes": { "type": "array", "items": { "type": "string" }, "description": "List of node identifiers from which replicas of this shard should be removed. Nodes listed here must not appear in 'addNodes' for the same shard, and cannot be used as a source node for any addition in this shard except in the implicit move case, where they appear as both a source and a node to remove." }, "addNodes": { "type": "object", "description": "A mapping of target node identifiers to their addition configuration. Each key represents a target node where a new replica will be added. The value may be null, which means an empty replica will be created, or a string specifying the source node from which shard data will be copied. If the source node is also marked for removal in the same shard, this addition is treated as a move operation, and that source node can only appear once as a source node for that shard. If the source node is not being removed, it can be used as the source for multiple additions (copy operations).", "additionalProperties": { "type": [ "string", "null" ], "description": "Defines how the new replica should be created. If null, an empty shard is created. If a string, it specifies the source node from which data for this shard should be replicated." } } } } } }, "required": [ "planId", "collection", "shardScaleActions" ] }, "ReplicationScaleApplyResponse": { "type": "object", "description": "Response for the POST /replication/scale endpoint containing the list of initiated shard copy operation IDs.", "properties": { "operationIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "List of shard copy operation IDs created during scaling." }, "planId": { "type": "string", "format": "uuid", "description": "The unique identifier of the replication scaling plan that generated these operations.", "x-nullable": false }, "collection": { "type": "string", "description": "The name of the collection associated with this replication scaling plan.", "x-nullable": false } }, "required": [ "operationIds", "planId", "collection" ] }, "ReplicationShardReplicas": { "description": "Represents a shard and lists the nodes that currently host its replicas.", "type": "object", "properties": { "shard": { "type": "string" }, "replicas": { "type": "array", "items": { "type": "string" } } } }, "ReplicationShardingState": { "description": "Details the sharding layout for a specific collection, mapping each shard to its set of replicas across the cluster.", "type": "object", "properties": { "collection": { "description": "The name of the collection.", "type": "string" }, "shards": { "description": "An array detailing each shard within the collection and the nodes hosting its replicas.", "type": "array", "items": { "$ref": "#/definitions/ReplicationShardReplicas" } } } }, "ReplicationReplicateDetailsReplicaStatusError": { "description": "Represents an error encountered during a replication operation, including its timestamp and a human-readable message.", "type": "object", "properties": { "whenErroredUnixMs": { "description": "The unix timestamp in ms when the error occurred. This is an approximate time and so should not be used for precise timing.", "format": "int64", "type": "integer" }, "message": { "description": "A human-readable message describing the error.", "type": "string" } } }, "ReplicationReplicateDetailsReplicaStatus": { "description": "Represents the current or historical status of a shard replica involved in a replication operation, including its operational state and any associated errors.", "type": "object", "properties": { "state": { "description": "The current operational state of the replica during the replication process.", "type": "string", "enum": [ "REGISTERED", "HYDRATING", "FINALIZING", "INTEGRATING", "DEHYDRATING", "READY", "CANCELLED" ] }, "whenStartedUnixMs": { "description": "The UNIX timestamp in ms when this state was first entered. This is an approximate time and so should not be used for precise timing.", "format": "int64", "type": "integer" }, "errors": { "description": "A list of error messages encountered by this replica during the replication operation, if any.", "type": "array", "items": { "$ref": "#/definitions/ReplicationReplicateDetailsReplicaStatusError" } } } }, "ReplicationReplicateDetailsReplicaResponse": { "description": "Provides a comprehensive overview of a specific replication operation, detailing its unique ID, the involved collection, shard, source and target nodes, transfer type, current status, and optionally, its status history.", "properties": { "id": { "description": "The unique identifier (ID) of this specific replication operation.", "format": "uuid", "type": "string" }, "shard": { "description": "The name of the shard involved in this replication operation.", "type": "string" }, "collection": { "description": "The name of the collection to which the shard being replicated belongs.", "type": "string" }, "sourceNode": { "description": "The identifier of the node from which the replica is being moved or copied (the source node).", "type": "string" }, "targetNode": { "description": "The identifier of the node to which the replica is being moved or copied (the target node).", "type": "string" }, "type": { "description": "Indicates whether the operation is a `COPY` (source replica remains) or a `MOVE` (source replica is removed after successful transfer).", "type": "string", "enum": [ "COPY", "MOVE" ] }, "uncancelable": { "description": "Whether the replica operation can't be cancelled.", "type": "boolean" }, "scheduledForCancel": { "description": "Whether the replica operation is scheduled for cancellation.", "type": "boolean" }, "scheduledForDelete": { "description": "Whether the replica operation is scheduled for deletion.", "type": "boolean" }, "status": { "description": "An object detailing the current operational state of the replica movement and any errors encountered.", "type": "object", "$ref": "#/definitions/ReplicationReplicateDetailsReplicaStatus" }, "statusHistory": { "description": "An array detailing the historical sequence of statuses the replication operation has transitioned through, if requested and available.", "type": "array", "items": { "$ref": "#/definitions/ReplicationReplicateDetailsReplicaStatus" } }, "whenStartedUnixMs": { "description": "The UNIX timestamp in ms when the replication operation was initiated. This is an approximate time and so should not be used for precise timing.", "format": "int64", "type": "integer" } }, "required": [ "id", "shard", "sourceNode", "targetNode", "collection", "status", "type" ] }, "ReplicationReplicateForceDeleteRequest": { "description": "Specifies the parameters available when force deleting replication operations.", "properties": { "id": { "description": "The unique identifier (ID) of the replication operation to be forcefully deleted.", "format": "uuid", "type": "string" }, "collection": { "description": "The name of the collection to which the shard being replicated belongs.", "type": "string" }, "shard": { "description": "The identifier of the shard involved in the replication operations.", "type": "string" }, "node": { "description": "The name of the target node where the replication operations are registered.", "type": "string" }, "dryRun": { "description": "If true, the operation will not actually delete anything but will return the expected outcome of the deletion.", "type": "boolean", "default": false } }, "type": "object" }, "ReplicationReplicateForceDeleteResponse": { "description": "Provides the UUIDs that were successfully force deleted as part of the replication operation. If dryRun is true, this will return the expected outcome without actually deleting anything.", "properties": { "deleted": { "description": "The unique identifiers (IDs) of the replication operations that were forcefully deleted.", "type": "array", "items": { "format": "uuid", "type": "string" } }, "dryRun": { "description": "Indicates whether the operation was a dry run (true) or an actual deletion (false).", "type": "boolean" } }, "type": "object" }, "PeerUpdate": { "description": "A single peer in the network.", "properties": { "id": { "description": "The session ID of the peer.", "type": "string", "format": "uuid" }, "name": { "description": "Human readable name.", "type": "string" }, "uri": { "description": "The location where the peer is exposed to the internet.", "type": "string", "format": "uri" }, "schemaHash": { "description": "The latest known hash of the peer's schema.", "type": "string" } } }, "VectorWeights": { "description": "Allow custom overrides of vector weights as math expressions. E.g. `pancake`: `7` will set the weight for the word pancake to 7 in the vectorization, whereas `w * 3` would triple the originally calculated word. This is an open object, with OpenAPI Specification 3.0 this will be more detailed. See Weaviate docs for more info. In the future this will become a key/value (string/string) object.", "type": "object" }, "PropertySchema": { "description": "Names and values of an individual property. A returned response may also contain additional metadata, such as from classification or feature projection.", "type": "object" }, "Schema": { "description": "Definitions of semantic schemas (also see: https://github.com/weaviate/weaviate-semantic-schemas).", "properties": { "classes": { "description": "Semantic classes that are available.", "items": { "$ref": "#/definitions/Class" }, "type": "array" }, "maintainer": { "description": "Email of the maintainer.", "format": "email", "type": "string" }, "name": { "description": "Name of the schema.", "type": "string" } }, "type": "object" }, "Class": { "properties": { "class": { "description": "Name of the collection (formerly 'class') (required). Multiple words should be concatenated in CamelCase, e.g. `ArticleAuthor`.", "type": "string" }, "vectorConfig": { "description": "Configure named vectors. Either use this field or `vectorizer`, `vectorIndexType`, and `vectorIndexConfig` fields. Available from `v1.24.0`.", "type": "object", "additionalProperties": { "$ref": "#/definitions/VectorConfig" } }, "vectorIndexType": { "description": "Name of the vector index type to use for the collection (e.g. `hnsw` or `flat`).", "type": "string" }, "vectorIndexConfig": { "description": "Vector-index config, that is specific to the type of index selected in vectorIndexType", "type": "object" }, "shardingConfig": { "description": "Manage how the index should be sharded and distributed in the cluster", "type": "object" }, "replicationConfig": { "$ref": "#/definitions/ReplicationConfig" }, "invertedIndexConfig": { "$ref": "#/definitions/InvertedIndexConfig" }, "multiTenancyConfig": { "$ref": "#/definitions/MultiTenancyConfig" }, "objectTtlConfig": { "$ref": "#/definitions/ObjectTtlConfig" }, "vectorizer": { "description": "Specify how the vectors for this collection should be determined. The options are either `none` - this means you have to import a vector with each object yourself - or the name of a module that provides vectorization capabilities, such as `text2vec-weaviate`. If left empty, it will use the globally configured default ([`DEFAULT_VECTORIZER_MODULE`](https://docs.weaviate.io/deploy/configuration/env-vars)) which can itself either be `none` or a specific module.", "type": "string" }, "moduleConfig": { "description": "Configuration specific to modules in a collection context.", "type": "object" }, "description": { "description": "Description of the collection for metadata purposes.", "type": "string" }, "properties": { "description": "Define properties of the collection.", "items": { "$ref": "#/definitions/Property" }, "type": "array" } }, "type": "object" }, "Property": { "properties": { "dataType": { "description": "Data type of the property (required). If it starts with a capital (for example Person), may be a reference to another type.", "items": { "type": "string" }, "type": "array" }, "description": { "description": "Description of the property.", "type": "string" }, "moduleConfig": { "description": "Configuration specific to modules in a collection context.", "type": "object" }, "name": { "description": "The name of the property (required). Multiple words should be concatenated in camelCase, e.g. `nameOfAuthor`.", "type": "string" }, "indexInverted": { "description": "(Deprecated). Whether to include this property in the inverted index. If `false`, this property cannot be used in `where` filters, `bm25` or `hybrid` search. \n\nUnrelated to vectorization behavior (deprecated as of v1.19; use indexFilterable or/and indexSearchable instead)", "type": "boolean", "x-nullable": true }, "bucketGeneration": { "description": "Internal RAFT-replicated counter bumped by semantic runtime-reindex migrations (e.g. change-tokenization, enable-filterable, enable-searchable). Used by the data path to resolve the property's inverted-index bucket name; a single RAFT commit flipping the schema flag AND bumping this counter atomically cuts the cluster from the old bucket to the new one. Defaults to 0. Internal use; clients should not set this.", "type": "integer", "format": "int64" }, "searchableBlockmax": { "description": "Internal RAFT-replicated per-property flag: true iff this property's searchable (BM25) bucket is on the blockmax (StrategyInverted) index. Stamped at migration cutover. Absent/null means \"not stamped\" and is resolved against the class-wide UsingBlockMaxWAND flag. Internal use; clients must not set this.", "type": "boolean", "x-nullable": true }, "indexFilterable": { "description": "Whether to include this property in the filterable, Roaring Bitmap index. If `false`, this property cannot be used in `where` filters. \n\nNote: Unrelated to vectorization behavior.", "type": "boolean", "x-nullable": true }, "indexSearchable": { "description": "Optional. Should this property be indexed in the inverted index. Defaults to true. Applicable only to properties of data type text and text[]. If you choose false, you will not be able to use this property in bm25 or hybrid search. This property has no affect on vectorization decisions done by modules", "type": "boolean", "x-nullable": true }, "indexRangeFilters": { "description": "Whether to include this property in the filterable, range-based Roaring Bitmap index. Provides better performance for range queries compared to filterable index in large datasets. Applicable only to properties of data type int, number, date.", "type": "boolean", "x-nullable": true }, "tokenization": { "description": "Determines how a property is indexed. This setting applies to `text` and `text[]` data types. The following tokenization methods are available:\n\n- `word` (default): Splits the text on any non-alphanumeric characters and lowercases the tokens.\n- `lowercase`: Splits the text on whitespace and lowercases the tokens.\n- `whitespace`: Splits the text on whitespace. This tokenization is case-sensitive.\n- `field`: Indexes the entire property value as a single token after trimming whitespace.\n- `trigram`: Splits the property into rolling trigrams (three-character sequences).\n- `gse`: Uses the `gse` tokenizer, suitable for Chinese language text. [See `gse` docs](https://pkg.go.dev/github.com/go-ego/gse#section-readme).\n- `kagome_ja`: Uses the `Kagome` tokenizer with a Japanese (IPA) dictionary. [See `kagome` docs](https://github.com/ikawaha/kagome).\n- `kagome_kr`: Uses the `Kagome` tokenizer with a Korean dictionary. [See `kagome` docs](https://github.com/ikawaha/kagome).\n\nSee [Reference: Tokenization](https://docs.weaviate.io/weaviate/config-refs/collections#tokenization) for details.", "type": "string", "enum": [ "word", "lowercase", "whitespace", "field", "trigram", "gse", "kagome_kr", "kagome_ja", "gse_ch" ] }, "nestedProperties": { "description": "The properties of the nested object(s). Applies to object and object[] data types.", "items": { "$ref": "#/definitions/NestedProperty" }, "type": "array", "x-omitempty": true }, "disableDuplicatedReferences": { "description": "If set to false, allows multiple references to the same target object within this property. Setting it to true will enforce uniqueness of references within this property. By default, this is set to true.", "type": "boolean", "x-nullable": true, "default": true }, "textAnalyzer": { "$ref": "#/definitions/TextAnalyzerConfig" } }, "type": "object" }, "TextAnalyzerConfig": { "description": "Text analysis options for a property. These settings are immutable after the property is created. Applies only to text and text[] data types that use an inverted index (searchable or filterable).", "properties": { "asciiFold": { "description": "If true, accent/diacritic marks are folded to their base characters during indexing and search. For example, 'école' matches 'ecole'. Defaults to false.", "type": "boolean" }, "asciiFoldIgnore": { "description": "If provided, specifies a list of characters that should be excluded from ascii folding. For example, if ['é'] is provided, then 'é' will not be folded to 'e' during indexing and search. This list is immutable after the property is created.", "type": "array", "x-omitempty": true, "items": { "type": "string" } }, "stopwordPreset": { "description": "Stopword preset name. Overrides the collection-level invertedIndexConfig.stopwords for this property. Only applies to properties using 'word' tokenization. Can be a built-in preset ('en', 'none') or a user-defined preset from invertedIndexConfig.stopwordPresets.", "type": "string", "x-omitempty": true } }, "x-omitempty": true, "type": "object" }, "VectorConfig": { "properties": { "vectorizer": { "description": "Configuration of a specific vectorizer used by this vector", "type": "object" }, "vectorIndexType": { "description": "Name of the vector index to use, eg. (HNSW)", "type": "string" }, "vectorIndexConfig": { "description": "Vector-index config, that is specific to the type of index selected in vectorIndexType", "type": "object" } }, "type": "object" }, "NestedProperty": { "properties": { "dataType": { "items": { "type": "string" }, "type": "array" }, "description": { "type": "string" }, "name": { "type": "string" }, "indexFilterable": { "type": "boolean", "x-nullable": true }, "indexSearchable": { "type": "boolean", "x-nullable": true }, "indexRangeFilters": { "type": "boolean", "x-nullable": true }, "tokenization": { "type": "string", "enum": [ "word", "lowercase", "whitespace", "field", "trigram", "gse", "kagome_kr", "kagome_ja", "gse_ch" ] }, "nestedProperties": { "description": "The properties of the nested object(s). Applies to object and object[] data types.", "items": { "$ref": "#/definitions/NestedProperty" }, "type": "array", "x-omitempty": true }, "textAnalyzer": { "$ref": "#/definitions/TextAnalyzerConfig" } }, "type": "object" }, "ShardStatusList": { "description": "The status of all the shards of a Class", "items": { "$ref": "#/definitions/ShardStatusGetResponse" }, "type": "array" }, "ShardStatusGetResponse": { "description": "Response body of shard status get request", "properties": { "name": { "description": "Name of the shard", "type": "string" }, "status": { "description": "Status of the shard", "type": "string" }, "vectorQueueSize": { "description": "Size of the vector queue of the shard", "type": "integer", "x-omitempty": false } } }, "ShardStatus": { "description": "The status of a single shard", "properties": { "status": { "description": "Status of the shard", "type": "string" } } }, "BackupCreateStatusResponse": { "description": "The definition of a backup create metadata", "properties": { "id": { "description": "The ID of the backup. Must be URL-safe and work as a filesystem path, only lowercase, numbers, underscore, minus characters allowed.", "type": "string" }, "backend": { "description": "Backup backend name e.g. filesystem, gcs, s3.", "type": "string" }, "path": { "description": "Destination path of backup files valid for the selected backend.", "type": "string" }, "error": { "description": "error message if creation failed", "type": "string" }, "status": { "description": "phase of backup creation process", "type": "string", "default": "STARTED", "enum": [ "STARTED", "TRANSFERRING", "TRANSFERRED", "FINALIZING", "SUCCESS", "FAILED", "CANCELLING", "CANCELED" ] }, "startedAt": { "description": "Timestamp when the backup process started", "type": "string", "format": "date-time" }, "completedAt": { "description": "Timestamp when the backup process completed (successfully or with failure)", "type": "string", "format": "date-time" }, "size": { "description": "Size of the backup in Gibs", "type": "number", "format": "float64" }, "incremental_base_backup_id": { "description": "The ID of the base backup this incremental backup was built on; empty if the backup is not incremental.", "type": "string" } } }, "BackupRestoreStatusResponse": { "description": "The definition of a backup restore metadata.", "properties": { "id": { "description": "The ID of the backup. Must be URL-safe and work as a filesystem path, only lowercase, numbers, underscore, minus characters allowed.", "type": "string" }, "backend": { "description": "Backup backend name e.g. filesystem, gcs, s3.", "type": "string" }, "path": { "description": "Destination path of backup files valid for the selected backup backend, contains bucket and path.", "type": "string" }, "error": { "description": "Error message if backup restoration failed.", "type": "string" }, "status": { "description": "Phase of backup restoration process.", "type": "string", "default": "STARTED", "enum": [ "STARTED", "TRANSFERRING", "TRANSFERRED", "FINALIZING", "SUCCESS", "FAILED", "CANCELLING", "CANCELED" ] } } }, "BackupConfig": { "description": "Backup custom configuration.", "type": "object", "properties": { "Endpoint": { "type": "string", "description": "Name of the endpoint, e.g. s3.amazonaws.com." }, "Bucket": { "type": "string", "description": "Name of the bucket, container, volume, etc." }, "Path": { "type": "string", "description": "Path or key within the bucket." }, "CPUPercentage": { "description": "Desired CPU core utilization ranging from 1%-80%", "type": "integer", "default": 50, "minimum": 1, "maximum": 80, "x-nullable": false }, "ChunkSize": { "description": "Deprecated, has no effect.", "type": "integer", "x-nullable": false, "x-deprecated": true }, "CompressionLevel": { "description": "compression level used by compression algorithm", "type": "string", "default": "DefaultCompression", "x-nullable": false, "enum": [ "DefaultCompression", "BestSpeed", "BestCompression", "ZstdDefaultCompression", "ZstdBestSpeed", "ZstdBestCompression", "NoCompression" ] } } }, "RestoreConfig": { "description": "Backup custom configuration", "type": "object", "properties": { "Endpoint": { "type": "string", "description": "name of the endpoint, e.g. s3.amazonaws.com" }, "Bucket": { "type": "string", "description": "Name of the bucket, container, volume, etc" }, "Path": { "type": "string", "description": "Path within the bucket" }, "CPUPercentage": { "description": "Desired CPU core utilization ranging from 1%-80%", "type": "integer", "default": 50, "minimum": 1, "maximum": 80, "x-nullable": false }, "rolesOptions": { "description": "How roles should be restored", "type": "string", "enum": [ "noRestore", "all" ], "default": "noRestore" }, "usersOptions": { "description": "How users should be restored", "type": "string", "enum": [ "noRestore", "all" ], "default": "noRestore" } } }, "BackupCreateRequest": { "description": "Request body for creating a backup for a set of collections.", "properties": { "id": { "description": "The ID of the backup (required). Must be URL-safe and work as a filesystem path, only lowercase, numbers, underscore, minus characters allowed.", "type": "string" }, "config": { "description": "Custom configuration for the backup creation process", "type": "object", "$ref": "#/definitions/BackupConfig" }, "include": { "description": "List of collections to include in the backup creation process. If not set, all collections are included. Cannot be used together with `exclude`. Permits wildcards, e.g. `*` or `prefix*`.", "type": "array", "items": { "type": "string" } }, "exclude": { "description": "List of collections to exclude from the backup creation process. If not set, all collections are included. Cannot be used together with `include`. Permits wildcards, e.g. `*` or `prefix*`.", "type": "array", "items": { "type": "string" } }, "includeUsers": { "description": "List of dynamic DB users to include in the backup. Permits `*` and `?` wildcards, e.g. `*` or `prefix*`. When omitted, the whole dynamic-user store is captured as part of the cluster snapshot and no per-user permission check is applied; when set, only matching users are captured and each is authorized individually.", "type": "array", "items": { "type": "string" } }, "incremental_base_backup_id": { "description": "The ID of an existing backup to use as the base for a file-based incremental backup. If set, only files that have changed since the base backup will be included in the new backup.", "type": "string", "x-nullable": true, "default": null } } }, "BackupCreateResponse": { "description": "The definition of a backup create response body", "properties": { "id": { "description": "The ID of the backup. Must be URL-safe and work as a filesystem path, only lowercase, numbers, underscore, minus characters allowed.", "type": "string" }, "classes": { "description": "The list of collections (classes) for which the backup creation process was started.", "type": "array", "items": { "type": "string" } }, "backend": { "description": "Backup backend name e.g. filesystem, gcs, s3.", "type": "string" }, "bucket": { "description": "Name of the bucket, container, volume, etc", "type": "string" }, "path": { "description": "Path within bucket of backup", "type": "string" }, "error": { "description": "error message if creation failed", "type": "string" }, "status": { "description": "phase of backup creation process", "type": "string", "default": "STARTED", "enum": [ "STARTED", "TRANSFERRING", "TRANSFERRED", "FINALIZING", "SUCCESS", "FAILED", "CANCELLING", "CANCELED" ] } } }, "BackupListResponse": { "description": "The definition of a backup create response body.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "The ID of the backup. Must be URL-safe and work as a filesystem path, only lowercase, numbers, underscore, minus characters allowed.", "type": "string" }, "classes": { "description": "The list of collections (classes) for which the backup process was started.", "type": "array", "items": { "type": "string" } }, "status": { "description": "Status of backup process.", "type": "string", "enum": [ "STARTED", "TRANSFERRING", "TRANSFERRED", "FINALIZING", "SUCCESS", "FAILED", "CANCELLING", "CANCELED" ] }, "startedAt": { "description": "Timestamp when the backup process started", "type": "string", "format": "date-time" }, "completedAt": { "description": "Timestamp when the backup process completed (successfully or with failure)", "type": "string", "format": "date-time" }, "size": { "description": "Size of the backup in Gibs", "type": "number", "format": "float64" }, "incremental_base_backup_id": { "description": "The ID of the base backup this incremental backup was built on; empty if the backup is not incremental.", "type": "string" } } } }, "BackupRestoreRequest": { "description": "Request body for restoring a backup for a set of collections (classes).", "properties": { "config": { "description": "Custom configuration for the backup restoration process.", "type": "object", "$ref": "#/definitions/RestoreConfig" }, "include": { "description": "List of collections (classes) to include in the backup restoration process.", "type": "array", "items": { "type": "string" } }, "exclude": { "description": "List of collections (classes) to exclude from the backup restoration process.", "type": "array", "items": { "type": "string" } }, "node_mapping": { "description": "Allows overriding the node names stored in the backup with different ones. Useful when restoring backups to a different environment.", "type": "object", "additionalProperties": { "type": "string" } }, "overwriteAlias": { "description": "Allows ovewriting the collection alias if there is a conflict", "type": "boolean" } } }, "BackupRestoreResponse": { "description": "The definition of a backup restore response body.", "properties": { "id": { "description": "The ID of the backup. Must be URL-safe and work as a filesystem path, only lowercase, numbers, underscore, minus characters allowed.", "type": "string" }, "classes": { "description": "The list of collections (classes) for which the backup restoration process was started.", "type": "array", "items": { "type": "string" } }, "backend": { "description": "Backup backend name e.g. filesystem, gcs, s3.", "type": "string" }, "path": { "description": "Destination path of backup files valid for the selected backend.", "type": "string" }, "error": { "description": "Error message if backup restoration failed.", "type": "string" }, "status": { "description": "Phase of backup restoration process.", "type": "string", "default": "STARTED", "enum": [ "STARTED", "TRANSFERRING", "TRANSFERRED", "FINALIZING", "SUCCESS", "FAILED", "CANCELLING", "CANCELED" ] } } }, "NodeStats": { "description": "The summary of Weaviate's statistics.", "properties": { "shardCount": { "description": "The count of Weaviate's shards. To see this value, set `output` to `verbose`.", "format": "int", "type": "number", "x-omitempty": false }, "objectCount": { "description": "The total number of objects in DB.", "format": "int64", "type": "number", "x-omitempty": false } } }, "BatchStats": { "description": "The summary of a nodes batch queue congestion status.", "properties": { "queueLength": { "description": "How many objects are currently in the batch queue.", "format": "int", "type": "number", "x-omitempty": true, "x-nullable": true }, "ratePerSecond": { "description": "How many objects are approximately processed from the batch queue per second.", "format": "int", "type": "number", "x-omitempty": false } } }, "NodeShardStatus": { "description": "The definition of a node shard status response body", "properties": { "name": { "description": "The name of the shard.", "type": "string", "x-omitempty": false }, "class": { "description": "The name of shard's collection (class).", "type": "string", "x-omitempty": false }, "objectCount": { "description": "The number of objects in shard.", "format": "int64", "type": "number", "x-omitempty": false }, "vectorIndexingStatus": { "description": "The status of the vector indexing process.", "type": "string", "x-omitempty": false }, "compressed": { "description": "The status of vector compression/quantization.", "type": "boolean", "x-omitempty": false }, "vectorQueueLength": { "description": "The length of the vector indexing queue.", "format": "int64", "type": "number", "x-omitempty": false }, "loaded": { "description": "The load status of the shard.", "type": "boolean", "x-omitempty": false }, "asyncReplicationStatus": { "description": "The status of the async replication.", "type": "array", "items": { "$ref": "#/definitions/AsyncReplicationStatus" } }, "numberOfReplicas": { "description": "Number of replicas for the shard.", "type": [ "integer", "null" ], "format": "int64", "x-omitempty": true }, "replicationFactor": { "description": "Minimum number of replicas for the shard.", "type": [ "integer", "null" ], "format": "int64", "x-omitempty": true } } }, "AsyncReplicationStatus": { "description": "The status of the async replication.", "properties": { "objectsPropagated": { "description": "The number of objects propagated in the most recent iteration.", "type": "number", "format": "uint64" }, "startDiffTimeUnixMillis": { "description": "The start time of the most recent iteration.", "type": "number", "format": "int64" }, "targetNode": { "description": "The target node of the replication, if set, otherwise empty.", "type": "string" } } }, "ReplicationAsyncConfig": { "description": "Configuration for asynchronous replication.", "type": "object", "properties": { "hashtreeHeight": { "description": "Height of the hashtree used for diffing.", "type": "integer", "format": "int64", "x-nullable": true, "x-omitempty": true }, "frequency": { "description": "Base frequency in milliseconds at which async replication runs diff calculations.", "type": "integer", "format": "int64", "x-nullable": true, "x-omitempty": true }, "frequencyWhilePropagating": { "description": "Frequency in milliseconds at which async replication runs while propagation is active.", "type": "integer", "format": "int64", "x-nullable": true, "x-omitempty": true }, "loggingFrequency": { "description": "Interval in seconds at which async replication logs its status.", "type": "integer", "format": "int64", "x-nullable": true, "x-omitempty": true }, "diffBatchSize": { "description": "Maximum number of object keys included in a single diff batch.", "type": "integer", "format": "int64", "x-nullable": true, "x-omitempty": true }, "diffPerNodeTimeout": { "description": "Timeout in seconds for computing a diff against a single node.", "type": "integer", "format": "int64", "x-nullable": true, "x-omitempty": true }, "prePropagationTimeout": { "description": "Overall timeout in seconds for the pre-propagation phase.", "type": "integer", "format": "int64", "x-nullable": true, "x-omitempty": true }, "propagationTimeout": { "description": "Timeout in seconds for propagating batch of changes to a node.", "type": "integer", "format": "int64", "x-nullable": true, "x-omitempty": true }, "propagationLimit": { "description": "Maximum number of objects to propagate in a single async replication run.", "type": "integer", "format": "int64", "x-nullable": true, "x-omitempty": true }, "propagationDelay": { "description": "Delay in milliseconds before newly added or updated objects are propagated.", "type": "integer", "format": "int64", "x-nullable": true, "x-omitempty": true }, "propagationConcurrency": { "description": "Maximum number of concurrent propagation workers.", "type": "integer", "format": "int64", "x-nullable": true, "x-omitempty": true }, "propagationBatchSize": { "description": "Number of objects to include in a single propagation batch.", "type": "integer", "format": "int64", "x-nullable": true, "x-omitempty": true } } }, "NodeStatus": { "description": "The definition of a backup node status response body", "properties": { "name": { "description": "The name of the node.", "type": "string" }, "status": { "description": "Node's status.", "type": "string", "default": "HEALTHY", "enum": [ "HEALTHY", "UNHEALTHY", "UNAVAILABLE", "TIMEOUT" ] }, "version": { "description": "The version of Weaviate.", "type": "string" }, "gitHash": { "description": "The gitHash of Weaviate.", "type": "string" }, "stats": { "description": "Weaviate overall statistics.", "type": "object", "$ref": "#/definitions/NodeStats" }, "batchStats": { "description": "Weaviate batch statistics.", "type": "object", "$ref": "#/definitions/BatchStats" }, "shards": { "description": "The list of the shards with it's statistics.", "type": "array", "items": { "$ref": "#/definitions/NodeShardStatus" } }, "operationalMode": { "description": "Which mode of operation the node is running in.", "type": "string", "enum": [ "ReadWrite", "WriteOnly", "ReadOnly", "ScaleOut" ] } } }, "NodesStatusResponse": { "description": "The status of all of the Weaviate nodes", "type": "object", "properties": { "nodes": { "type": "array", "items": { "$ref": "#/definitions/NodeStatus" } } } }, "DistributedTask": { "description": "Distributed task metadata.", "type": "object", "properties": { "id": { "description": "The ID of the task.", "type": "string" }, "version": { "description": "The version of the task.", "type": "integer" }, "status": { "description": "The status of the task.", "type": "string" }, "startedAt": { "description": "The time when the task was created.", "type": "string", "format": "date-time" }, "finishedAt": { "description": "The time when the task was finished.", "type": "string", "format": "date-time" }, "finishedNodes": { "description": "The nodes that finished the task.", "type": "array", "items": { "type": "string" } }, "error": { "description": "The high level reason why the task failed.", "type": "string", "x-omitempty": true }, "payload": { "description": "The payload of the task.", "type": "object" }, "units": { "description": "Units of the task. Only present for tasks that use unit tracking.", "type": "array", "x-omitempty": true, "items": { "$ref": "#/definitions/DistributedTaskUnit" } } } }, "DistributedTaskUnit": { "description": "A unit of a distributed task.", "type": "object", "properties": { "id": { "description": "The ID of the unit.", "type": "string" }, "nodeId": { "description": "The node that owns this unit.", "type": "string" }, "status": { "description": "The status of the unit.", "type": "string" }, "progress": { "description": "The progress of the unit (0.0 to 1.0).", "type": "number", "format": "float" }, "error": { "description": "The error message if the unit failed.", "type": "string", "x-omitempty": true }, "updatedAt": { "description": "The time when the unit was last updated.", "type": "string", "format": "date-time" }, "finishedAt": { "description": "The time when the unit finished.", "type": "string", "format": "date-time" } } }, "DistributedTasks": { "description": "Active distributed tasks by namespace.", "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/definitions/DistributedTask" } } }, "RaftStatistics": { "description": "The definition of Raft statistics.", "properties": { "appliedIndex": { "type": "string" }, "commitIndex": { "type": "string" }, "fsmPending": { "type": "string" }, "lastContact": { "type": "string" }, "lastLogIndex": { "type": "string" }, "lastLogTerm": { "type": "string" }, "lastSnapshotIndex": { "type": "string" }, "lastSnapshotTerm": { "type": "string" }, "latestConfiguration": { "description": "Weaviate Raft nodes.", "type": "object" }, "latestConfigurationIndex": { "type": "string" }, "numPeers": { "type": "string" }, "protocolVersion": { "type": "string" }, "protocolVersionMax": { "type": "string" }, "protocolVersionMin": { "type": "string" }, "snapshotVersionMax": { "type": "string" }, "snapshotVersionMin": { "type": "string" }, "state": { "type": "string" }, "term": { "type": "string" } } }, "Statistics": { "description": "The definition of node statistics.", "properties": { "name": { "description": "The name of the node.", "type": "string" }, "status": { "description": "Node's status.", "type": "string", "default": "HEALTHY", "enum": [ "HEALTHY", "UNHEALTHY", "UNAVAILABLE", "TIMEOUT" ] }, "bootstrapped": { "type": "boolean" }, "dbLoaded": { "type": "boolean" }, "initialLastAppliedIndex": { "type": "number", "format": "uint64" }, "lastAppliedIndex": { "type": "number" }, "isVoter": { "type": "boolean" }, "leaderId": { "type": "object" }, "leaderAddress": { "type": "object" }, "open": { "type": "boolean" }, "ready": { "type": "boolean" }, "candidates": { "type": "object" }, "raft": { "description": "Weaviate Raft statistics.", "type": "object", "$ref": "#/definitions/RaftStatistics" } } }, "ClusterStatisticsResponse": { "description": "The cluster statistics of all of the Weaviate nodes", "type": "object", "properties": { "statistics": { "type": "array", "items": { "$ref": "#/definitions/Statistics" } }, "synchronized": { "type": "boolean", "x-omitempty": false } } }, "SingleRef": { "description": "Either set beacon (direct reference) or set collection (class) and schema (concept reference)", "properties": { "class": { "description": "If using a concept reference (rather than a direct reference), specify the desired collection (class) name here.", "format": "uri", "type": "string" }, "schema": { "description": "If using a concept reference (rather than a direct reference), specify the desired properties here", "$ref": "#/definitions/PropertySchema" }, "beacon": { "description": "If using a direct reference, specify the URI to point to the cross-reference here. Should be in the form of weaviate://localhost/ for the example of a local cross-reference to an object", "format": "uri", "type": "string" }, "href": { "description": "If using a direct reference, this read-only fields provides a link to the referenced resource. If 'origin' is globally configured, an absolute URI is shown - a relative URI otherwise.", "format": "uri", "type": "string" }, "classification": { "description": "Additional Meta information about classifications if the item was part of one", "$ref": "#/definitions/ReferenceMetaClassification" } } }, "AdditionalProperties": { "description": "(Response only) Additional meta information about a single object.", "type": "object", "additionalProperties": { "type": "object" } }, "ReferenceMetaClassification": { "description": "This meta field contains additional info about the classified reference property", "properties": { "overallCount": { "description": "overall neighbors checked as part of the classification. In most cases this will equal k, but could be lower than k - for example if not enough data was present", "type": "number", "format": "int64" }, "winningCount": { "description": "size of the winning group, a number between 1..k", "type": "number", "format": "int64" }, "losingCount": { "description": "size of the losing group, can be 0 if the winning group size equals k", "type": "number", "format": "int64" }, "closestOverallDistance": { "description": "The lowest distance of any neighbor, regardless of whether they were in the winning or losing group", "type": "number", "format": "float32" }, "winningDistance": { "description": "deprecated - do not use, to be removed in 0.23.0", "type": "number", "format": "float32" }, "meanWinningDistance": { "description": "Mean distance of all neighbors from the winning group", "type": "number", "format": "float32" }, "closestWinningDistance": { "description": "Closest distance of a neighbor from the winning group", "type": "number", "format": "float32" }, "closestLosingDistance": { "description": "The lowest distance of a neighbor in the losing group. Optional. If k equals the size of the winning group, there is no losing group", "type": "number", "format": "float32", "x-nullable": true }, "losingDistance": { "description": "deprecated - do not use, to be removed in 0.23.0", "type": "number", "format": "float32", "x-nullable": true }, "meanLosingDistance": { "description": "Mean distance of all neighbors from the losing group. Optional. If k equals the size of the winning group, there is no losing group.", "type": "number", "format": "float32", "x-nullable": true } } }, "BatchReference": { "properties": { "from": { "description": "Long-form beacon-style URI to identify the source of the cross-reference, including the property name. Should be in the form of `weaviate://localhost/objects///`, where `` and `` must represent the cross-reference property of the source class to be used.", "format": "uri", "type": "string", "example": "weaviate://localhost/Zoo/a5d09582-4239-4702-81c9-92a6e0122bb4/hasAnimals" }, "to": { "description": "Short-form URI to point to the cross-reference. Should be in the form of `weaviate://localhost/` for the example of a local cross-reference to an object.", "example": "weaviate://localhost/97525810-a9a5-4eb0-858a-71449aeb007f", "format": "uri", "type": "string" }, "tenant": { "type": "string", "description": "Name of the reference tenant." } } }, "BatchReferenceResponse": { "allOf": [ { "$ref": "#/definitions/BatchReference" }, { "properties": { "result": { "description": "Results for this specific reference.", "format": "object", "properties": { "status": { "type": "string", "default": "SUCCESS", "enum": [ "SUCCESS", "FAILED" ] }, "errors": { "$ref": "#/definitions/ErrorResponse" } } } } } ], "type": "object" }, "GeoCoordinates": { "properties": { "latitude": { "description": "The latitude of the point on earth in decimal form.", "format": "float", "type": "number", "x-nullable": true }, "longitude": { "description": "The longitude of the point on earth in decimal form.", "format": "float", "type": "number", "x-nullable": true } } }, "PhoneNumber": { "properties": { "input": { "description": "The raw input as the phone number is present in your raw data set. It will be parsed into the standardized formats if valid.", "type": "string" }, "internationalFormatted": { "description": "Read-only. Parsed result in the international format (e.g. `+49 123 456789`).", "type": "string" }, "defaultCountry": { "description": "Optional. The ISO 3166-1 alpha-2 country code. This is used to figure out the correct `countryCode` and international format if only a national number (e.g. `0123 4567`) is provided.", "type": "string" }, "countryCode": { "description": "Read-only. The numerical country code (e.g. `49`).", "format": "uint64", "type": "number" }, "national": { "description": "Read-only. The numerical representation of the national part.", "format": "uint64", "type": "number" }, "nationalFormatted": { "description": "Read-only. Parsed result in the national format (e.g. `0123 456789`).", "type": "string" }, "valid": { "description": "Read-only. Indicates whether the parsed number is a valid phone number.", "type": "boolean" } } }, "Object": { "properties": { "class": { "description": "Name of the collection (class) the object belongs to.", "type": "string" }, "vectorWeights": { "$ref": "#/definitions/VectorWeights" }, "properties": { "$ref": "#/definitions/PropertySchema" }, "id": { "description": "The UUID of the object.", "format": "uuid", "type": "string" }, "creationTimeUnix": { "description": "(Response only) Timestamp of creation of this object in milliseconds since epoch UTC.", "format": "int64", "type": "integer" }, "lastUpdateTimeUnix": { "description": "(Response only) Timestamp of the last object update in milliseconds since epoch UTC.", "format": "int64", "type": "integer" }, "vector": { "description": "This field returns vectors associated with the object. C11yVector, Vector or Vectors values are possible.", "$ref": "#/definitions/C11yVector" }, "vectors": { "description": "This field returns vectors associated with the object.", "$ref": "#/definitions/Vectors" }, "tenant": { "description": "The name of the tenant the object belongs to.", "type": "string" }, "additional": { "$ref": "#/definitions/AdditionalProperties" } }, "type": "object" }, "ObjectsGetResponse": { "allOf": [ { "$ref": "#/definitions/Object" }, { "properties": { "deprecations": { "type": "array", "items": { "$ref": "#/definitions/Deprecation" } } } }, { "properties": { "result": { "description": "Results for this specific object.", "format": "object", "properties": { "status": { "type": "string", "default": "SUCCESS", "enum": [ "SUCCESS", "FAILED" ] }, "errors": { "$ref": "#/definitions/ErrorResponse" } } } } } ], "type": "object" }, "BatchDelete": { "type": "object", "properties": { "match": { "description": "Outlines how to find the objects to be deleted.", "type": "object", "properties": { "class": { "description": "The name of the collection (class) from which to delete objects.", "type": "string", "example": "City" }, "where": { "description": "Filter to limit the objects to be deleted.", "type": "object", "$ref": "#/definitions/WhereFilter" } } }, "output": { "description": "Controls the verbosity of the output, possible values are: `minimal`, `verbose`. Defaults to `minimal`.", "type": "string", "default": "minimal" }, "deletionTimeUnixMilli": { "description": "Timestamp of deletion in milliseconds since epoch UTC.", "format": "int64", "type": "integer", "x-nullable": true }, "dryRun": { "description": "If true, the call will show which objects would be matched using the specified filter without deleting any objects. \n\nDepending on the configured verbosity, you will either receive a count of affected objects, or a list of IDs.", "type": "boolean", "default": false } } }, "BatchDeleteResponse": { "description": "Delete Objects response.", "type": "object", "properties": { "match": { "description": "Outlines how to find the objects to be deleted.", "type": "object", "properties": { "class": { "description": "The name of the collection (class) from which to delete objects.", "type": "string", "example": "City" }, "where": { "description": "Filter to limit the objects to be deleted.", "type": "object", "$ref": "#/definitions/WhereFilter" } } }, "output": { "description": "Controls the verbosity of the output, possible values are: `minimal`, `verbose`. Defaults to `minimal`.", "type": "string", "default": "minimal" }, "deletionTimeUnixMilli": { "description": "Timestamp of deletion in milliseconds since epoch UTC.", "format": "int64", "type": "integer", "x-nullable": true }, "dryRun": { "description": "If true, objects will not be deleted yet, but merely listed. Defaults to false.", "type": "boolean", "default": false }, "results": { "type": "object", "properties": { "matches": { "description": "How many objects were matched by the filter.", "type": "number", "format": "int64", "x-omitempty": false }, "limit": { "description": "The most amount of objects that can be deleted in a single query, equals [`QUERY_MAXIMUM_RESULTS`](https://docs.weaviate.io/deploy/configuration/env-vars#QUERY_MAXIMUM_RESULTS).", "type": "number", "format": "int64", "x-omitempty": false }, "successful": { "description": "How many objects were successfully deleted in this round.", "type": "number", "format": "int64", "x-omitempty": false }, "failed": { "description": "How many objects should have been deleted but could not be deleted.", "type": "number", "format": "int64", "x-omitempty": false }, "objects": { "description": "With output set to `minimal` only objects with error occurred will the be described. Successfully deleted objects would be omitted. Output set to `verbose` will list all of the objects with their respective statuses.", "type": "array", "items": { "description": "Results for this specific Object.", "format": "object", "properties": { "id": { "description": "The UUID of the object.", "format": "uuid", "type": "string" }, "status": { "type": "string", "default": "SUCCESS", "enum": [ "SUCCESS", "DRYRUN", "FAILED" ] }, "errors": { "$ref": "#/definitions/ErrorResponse" } } } } } } } }, "ObjectsListResponse": { "description": "List of objects.", "properties": { "objects": { "description": "The actual list of objects.", "items": { "$ref": "#/definitions/Object" }, "type": "array" }, "deprecations": { "type": "array", "items": { "$ref": "#/definitions/Deprecation" } }, "totalResults": { "description": "The total number of objects for the query. The number of items in a response may be smaller due to paging.", "format": "int64", "type": "integer" } }, "type": "object" }, "Classification": { "description": "Manage classifications, trigger them and view status of past classifications.", "properties": { "id": { "description": "ID to uniquely identify this classification run.", "format": "uuid", "type": "string", "example": "ee722219-b8ec-4db1-8f8d-5150bb1a9e0c" }, "class": { "description": "The name of the collection (class) which is used in this classification.", "type": "string", "example": "City" }, "classifyProperties": { "description": "Which ref-property to set as part of the classification.", "type": "array", "items": { "type": "string" }, "example": [ "inCountry" ] }, "basedOnProperties": { "description": "Base the text-based classification on these fields (of type text).", "type": "array", "items": { "type": "string" }, "example": [ "description" ] }, "status": { "description": "Status of this classification.", "type": "string", "enum": [ "running", "completed", "failed" ], "example": "running" }, "meta": { "description": "Additional meta information about the classification.", "type": "object", "$ref": "#/definitions/ClassificationMeta" }, "type": { "description": "Which algorithm to use for classifications.", "type": "string" }, "settings": { "description": "Classification-type specific settings.", "type": "object" }, "error": { "description": "Error message if status == failed.", "type": "string", "default": "", "example": "classify xzy: something went wrong" }, "filters": { "type": "object", "properties": { "sourceWhere": { "description": "Limit the objects to be classified.", "type": "object", "$ref": "#/definitions/WhereFilter" }, "trainingSetWhere": { "description": "Limit the training objects to be considered during the classification. Can only be used on types with explicit training sets, such as 'knn'.", "type": "object", "$ref": "#/definitions/WhereFilter" }, "targetWhere": { "description": "Limit the possible sources when using an algorithm which doesn't really on training data, e.g. 'contextual'. When using an algorithm with a training set, such as 'knn', limit the training set instead.", "type": "object", "$ref": "#/definitions/WhereFilter" } } } }, "type": "object" }, "ClassificationMeta": { "description": "Additional information to a specific classification.", "properties": { "started": { "description": "Time when this classification was started.", "type": "string", "format": "date-time", "example": "2017-07-21T17:32:28Z" }, "completed": { "description": "Time when this classification finished.", "type": "string", "format": "date-time", "example": "2017-07-21T17:32:28Z" }, "count": { "description": "Number of objects which were taken into consideration for classification.", "type": "integer", "example": 147 }, "countSucceeded": { "description": "Number of objects successfully classified.", "type": "integer", "example": 140 }, "countFailed": { "description": "Number of objects which could not be classified - see error message for details.", "type": "integer", "example": 7 } }, "type": "object" }, "WhereFilter": { "description": "Filter search results using a where filter.", "properties": { "operands": { "description": "Combine multiple where filters, requires 'And' or 'Or' operator.", "type": "array", "items": { "$ref": "#/definitions/WhereFilter" } }, "operator": { "description": "Operator to use.", "type": "string", "enum": [ "And", "Or", "Equal", "Like", "NotEqual", "GreaterThan", "GreaterThanEqual", "LessThan", "LessThanEqual", "WithinGeoRange", "IsNull", "ContainsAny", "ContainsAll", "ContainsNone", "Not" ], "example": "GreaterThanEqual" }, "path": { "description": "Path to the property currently being filtered.", "type": "array", "items": { "type": "string" }, "example": [ "inCity", "city", "name" ] }, "valueInt": { "description": "value as integer", "type": "integer", "format": "int64", "example": 2000, "x-nullable": true }, "valueNumber": { "description": "value as number/float", "type": "number", "format": "float64", "example": 3.14, "x-nullable": true }, "valueBoolean": { "description": "value as boolean", "type": "boolean", "example": false, "x-nullable": true }, "valueString": { "description": "value as text (deprecated as of v1.19; alias for valueText)", "type": "string", "example": "my search term", "x-nullable": true }, "valueText": { "description": "value as text", "type": "string", "example": "my search term", "x-nullable": true }, "valueDate": { "description": "value as date (as string)", "type": "string", "example": "TODO", "x-nullable": true }, "valueIntArray": { "description": "value as integer", "type": "array", "items": { "type": "integer", "format": "int64" }, "example": "[100, 200]", "x-nullable": true, "x-omitempty": true }, "valueNumberArray": { "description": "value as number/float", "type": "array", "items": { "type": "number", "format": "float64" }, "example": [ 3.14 ], "x-nullable": true, "x-omitempty": true }, "valueBooleanArray": { "description": "value as boolean", "type": "array", "items": { "type": "boolean" }, "example": [ true, false ], "x-nullable": true, "x-omitempty": true }, "valueStringArray": { "description": "value as text (deprecated as of v1.19; alias for valueText)", "type": "array", "items": { "type": "string" }, "example": [ "my search term" ], "x-nullable": true, "x-omitempty": true }, "valueTextArray": { "description": "value as text", "type": "array", "items": { "type": "string" }, "example": [ "my search term" ], "x-nullable": true, "x-omitempty": true }, "valueDateArray": { "description": "value as date (as string)", "type": "array", "items": { "type": "string" }, "example": "TODO", "x-nullable": true, "x-omitempty": true }, "valueGeoRange": { "description": "value as geo coordinates and distance", "type": "object", "$ref": "#/definitions/WhereFilterGeoRange", "x-nullable": true } }, "type": "object" }, "WhereFilterGeoRange": { "type": "object", "description": "Filter within a distance of a georange.", "properties": { "geoCoordinates": { "$ref": "#/definitions/GeoCoordinates", "x-nullable": false }, "distance": { "type": "object", "properties": { "max": { "type": "number", "format": "float64" } } } } }, "Tenant": { "type": "object", "description": "Attributes representing a single tenant within Weaviate.", "properties": { "name": { "description": "The name of the tenant (required).", "type": "string" }, "activityStatus": { "description": "The activity status of the tenant, which determines if it is queryable and where its data is stored.\n\nAvailable Statuses:\n- `ACTIVE`: The tenant is fully operational and ready for queries. Data is stored on local, hot storage.\n- `INACTIVE`: The tenant is not queryable. Data is stored locally.\n- `OFFLOADED`: The tenant is inactive and its data is stored in a remote cloud backend.\n\nUsage Rules:\n- On Create: This field is optional and defaults to `ACTIVE`. Allowed values are `ACTIVE` and `INACTIVE`.\n- On Update: This field is required. Allowed values are `ACTIVE`, `INACTIVE`, and `OFFLOADED`.\n\nRead-Only Statuses:\nThe following statuses are set by the server and indicate a tenant is transitioning between states:\n- `OFFLOADING`\n- `ONLOADING`\n\nNote on Deprecated Names:\nFor backward compatibility, deprecated names are still accepted and are mapped to their modern equivalents: `HOT` (now `ACTIVE`), `COLD` (now `INACTIVE`), `FROZEN` (now `OFFLOADED`), `FREEZING` (now `OFFLOADING`), `UNFREEZING` (now `ONLOADING`).", "type": "string", "enum": [ "ACTIVE", "INACTIVE", "OFFLOADED", "OFFLOADING", "ONLOADING", "HOT", "COLD", "FROZEN", "FREEZING", "UNFREEZING" ] } } }, "Alias": { "type": "object", "description": "Represents the mapping between an alias name and a collection. An alias provides an alternative name for accessing a collection.", "properties": { "alias": { "description": "The unique name of the alias that serves as an alternative identifier for the collection.", "type": "string" }, "class": { "description": "The name of the collection (class) to which this alias is mapped.", "type": "string" } } }, "AliasResponse": { "description": "Response object containing a list of alias mappings.", "type": "object", "properties": { "aliases": { "description": "Array of alias objects, each containing an alias-to-collection mapping.", "type": "array", "items": { "$ref": "#/definitions/Alias" } } } }, "Namespace": { "type": "object", "description": "A cluster-level namespace used to group resources under a common administrative unit. Namespace names must contain only lowercase letters, digits, and hyphens, must start and end with a letter or digit, must be 3-36 characters long, and must not be a reserved name.", "properties": { "name": { "description": "The unique name of the namespace.", "type": "string" }, "home_node": { "description": "The cluster node where this namespace's shards are placed. Set at create time and updatable later. Updating it only affects future placement decisions; existing live shards are not moved.", "type": "string" }, "state": { "description": "Lifecycle state. \"active\" namespaces accept all operations. \"suspended\" namespaces reject new classes, aliases, users, roles, and role assignments, and their users can no longer authenticate; everything the namespace already owns is retained. \"resuming\" namespaces are on their way back to \"active\" and are still restricted the same way. \"deleting\" namespaces are being removed: new classes, aliases, and users can no longer be created in the namespace, and the namespace itself disappears once removal completes.", "type": "string", "enum": [ "active", "suspended", "resuming", "deleting" ] } } }, "NamespaceCreateRequest": { "type": "object", "description": "Optional body for namespace creation. When `home_node` is omitted, the cluster picks one automatically.", "properties": { "home_node": { "description": "Optional. Cluster node to place this namespace's shards on. Must be a current storage candidate. When omitted, the cluster picks one.", "type": "string" } } }, "NamespaceUpdateRequest": { "type": "object", "description": "Update payload for an existing namespace.", "required": [ "home_node" ], "properties": { "home_node": { "description": "Cluster node to use for future placements in this namespace. Must be a current storage candidate. Existing live shards are not moved.", "type": "string" } } }, "NamespaceListResponse": { "description": "Response object containing a list of namespaces.", "type": "array", "items": { "$ref": "#/definitions/Namespace" } }, "SearchCommon": { "description": "Fields shared by every REST search request (near-text, and — when built — hybrid, bm25, near-object). Unknown fields are ignored (platform parity with the other endpoints). Reserved fields are accepted by the schema but rejected by the server with 422 until the corresponding feature ships.", "type": "object", "properties": { "where": { "description": "A conditional filter to limit the objects that are searched.", "$ref": "#/definitions/WhereFilter" }, "limit": { "description": "The maximum number of objects to return. Omitted or `0` falls back to the server default (`QUERY_DEFAULTS_LIMIT`); a value above `QUERY_MAXIMUM_RESULTS` is rejected.", "type": "integer", "format": "int64", "x-nullable": true }, "offset": { "description": "The number of objects to skip before returning results. Used with `limit` for pagination.", "type": "integer", "format": "int64", "x-nullable": true }, "autoLimit": { "description": "Cut results off at the first steep drop in score (autocut). The value is the number of score jumps to allow before cutting.", "type": "integer", "format": "int64", "x-nullable": true }, "returnProperties": { "description": "The properties to return. A dot-path selects one hop across a reference (e.g. `hasAuthor.name`). Omitted returns all non-reference, non-blob properties; an empty array returns no properties.", "type": "array", "items": { "type": "string" } }, "returnMetadata": { "description": "The retrieval metadata to return under each result's `metadata` key. The object `id` is always returned as each result's `id` field. Omitted or empty returns no `metadata` block.", "type": "array", "items": { "type": "string", "enum": [ "distance", "certainty", "score", "explainScore", "creationTime", "lastUpdateTime" ] } }, "tenant": { "description": "The tenant to search in a multi-tenant collection.", "type": "string" }, "consistencyLevel": { "description": "The consistency level for the read.", "type": "string", "enum": [ "ONE", "QUORUM", "ALL" ] }, "singlePrompt": { "description": "Reserved for per-object retrieval-augmented generation. Returns 422 (not yet supported).", "type": "string", "x-nullable": true }, "groupedTask": { "description": "Reserved for grouped retrieval-augmented generation. Returns 422 (not yet supported).", "type": "string", "x-nullable": true }, "groupBy": { "description": "Reserved for grouped search. Returns 422 (not yet supported).", "type": "string", "x-nullable": true }, "numberOfGroups": { "description": "Reserved for grouped search. Returns 422 (not yet supported).", "type": "integer", "format": "int64", "x-nullable": true }, "objectsPerGroup": { "description": "Reserved for grouped search. Returns 422 (not yet supported).", "type": "integer", "format": "int64", "x-nullable": true }, "rerank": { "description": "Reserved for reranking. Returns 422 (not yet supported).", "$ref": "#/definitions/SearchRerank" } } }, "SearchRerank": { "description": "Reserved for reranking. Returns 422 (not yet supported).", "type": "object", "required": [ "property" ], "properties": { "property": { "description": "The property to rerank on.", "type": "string" }, "query": { "description": "The query to rerank with. Defaults to the search query.", "type": "string" } } }, "SearchNearTextRequest": { "description": "Request body for the near-text search endpoint. The query is vectorized server-side by the collection's vectorizer module and the closest objects are returned. Extends the shared search fields (`SearchCommon`) with the near-text-specific `query`, `certainty`, `distance` and `targetVector`.", "allOf": [ { "$ref": "#/definitions/SearchCommon" }, { "type": "object", "required": [ "query" ], "properties": { "query": { "description": "The concept(s) to search for, as an array of strings. Multiple entries perform a multi-concept search. A single concept is a one-element array, e.g. `[\"space opera\"]`.", "type": "array", "items": { "type": "string" } }, "certainty": { "description": "Minimum normalized certainty of a match. Only for cosine-distance vector indexes. Mutually exclusive with `distance`.", "type": "number", "format": "float64", "x-nullable": true }, "distance": { "description": "Maximum vector distance of a match. Mutually exclusive with `certainty`.", "type": "number", "format": "float64", "x-nullable": true }, "targetVector": { "description": "The named vector to search. Required when the collection has more than one named vector.", "type": "string" } } } ] }, "SearchResponse": { "description": "The result of a REST search: the matched objects as `{id, properties, references, metadata}` envelopes, plus the server-side processing time. Shared by all REST search endpoints.", "type": "object", "required": [ "results", "tookMs" ], "properties": { "results": { "description": "The matched objects, ordered by relevance.", "type": "array", "items": { "$ref": "#/definitions/SearchResultObject" }, "x-omitempty": false }, "tookMs": { "description": "Server-side processing time in milliseconds.", "type": "integer", "format": "int64", "x-omitempty": false } } }, "SearchResultMetadata": { "description": "The retrieval metadata of a single search hit, populated according to `returnMetadata`. Every field is optional and only present when it was requested and is computable for the search.", "type": "object", "properties": { "distance": { "description": "The vector distance between the hit and the query.", "type": "number", "format": "float", "x-nullable": true }, "certainty": { "description": "The normalized certainty of the hit. Only computable on cosine-distance vector indexes.", "type": "number", "format": "double", "x-nullable": true }, "score": { "description": "The relevance score of the hit.", "type": "number", "format": "float", "x-nullable": true }, "explainScore": { "description": "An explanation of how the score was computed.", "type": "string", "x-nullable": true }, "creationTime": { "description": "The object's creation time, as epoch milliseconds.", "type": "integer", "format": "int64", "x-nullable": true }, "lastUpdateTime": { "description": "The object's last-update time, as epoch milliseconds.", "type": "integer", "format": "int64", "x-nullable": true } } }, "SearchResultObject": { "description": "A single search hit: the object's `id` (always returned), the selected non-reference properties under `properties`, the selected cross-references under `references`, and the requested retrieval metadata under `metadata`.", "type": "object", "required": [ "id", "properties" ], "properties": { "id": { "description": "The object's UUID. Always returned.", "type": "string", "format": "uuid" }, "properties": { "description": "The selected non-reference properties of the object; nested (object / object[]) properties are pruned to the selected nested fields. Always present — `{}` when the request selects no properties.", "type": "object", "additionalProperties": { "$ref": "#/definitions/JsonObject" }, "x-omitempty": false }, "references": { "description": "The selected cross-references: reference name to the array of referenced objects, each carrying the selected one-hop properties. Omitted when the request selects no references.", "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/definitions/JsonObject" } } }, "metadata": { "$ref": "#/definitions/SearchResultMetadata", "x-nullable": true } } } }, "externalDocs": { "url": "https://github.com/weaviate/weaviate" }, "info": { "contact": { "email": "hello@weaviate.io", "name": "Weaviate", "url": "https://github.com/weaviate" }, "description": "# Introduction\n Weaviate is an open source, AI-native vector database that helps developers create intuitive and reliable AI-powered applications. \n ### Base Path \nThe base path for the Weaviate server is structured as `[YOUR-WEAVIATE-HOST]:[PORT]/v1`. As an example, if you wish to access the `schema` endpoint on a local instance, you would navigate to `http://localhost:8080/v1/schema`. Ensure you replace `[YOUR-WEAVIATE-HOST]` and `[PORT]` with your actual server host and port number respectively. \n ### Questions? \nIf you have any comments or questions, please feel free to reach out to us at the community forum [https://forum.weaviate.io/](https://forum.weaviate.io/). \n### Issues? \nIf you find a bug or want to file a feature request, please open an issue on our GitHub repository for [Weaviate](https://github.com/weaviate/weaviate). \n### Need more documentation? \nFor a quickstart, code examples, concepts and more, please visit our [documentation page](https://docs.weaviate.io/weaviate).", "title": "Weaviate REST API", "version": "1.39.0" }, "parameters": { "CommonAfterParameterQuery": { "description": "A threshold UUID of the objects to retrieve after, using an UUID-based ordering. This object is not part of the set. \n\nMust be used with collection name (`class`), typically in conjunction with `limit`. \n\nNote `after` cannot be used with `offset` or `sort`. \n\nFor a null value similar to offset=0, set an empty string in the request, i.e. `after=` or `after`.", "in": "query", "name": "after", "required": false, "type": "string" }, "CommonOffsetParameterQuery": { "description": "The starting index of the result window. Note `offset` will retrieve `offset+limit` results and return `limit` results from the object with index `offset` onwards. Limited by the value of `QUERY_MAXIMUM_RESULTS`. \n\nShould be used in conjunction with `limit`. \n\nCannot be used with `after`.", "format": "int64", "in": "query", "name": "offset", "required": false, "type": "integer", "default": 0 }, "CommonLimitParameterQuery": { "description": "The maximum number of items to be returned per page. The default is 25 unless set otherwise as an environment variable.", "format": "int64", "in": "query", "name": "limit", "required": false, "type": "integer" }, "CommonIncludeParameterQuery": { "description": "Include additional information, such as classification information. Allowed values include: `classification`, `vector` and `interpretation`.", "in": "query", "name": "include", "required": false, "type": "string" }, "CommonConsistencyLevelParameterQuery": { "description": "Determines how many replicas must acknowledge a request before it is considered successful.", "in": "query", "name": "consistency_level", "required": false, "type": "string" }, "CommonTenantParameterQuery": { "description": "Specifies the tenant in a request targeting a multi-tenant collection (class).", "in": "query", "name": "tenant", "required": false, "type": "string" }, "CommonNodeNameParameterQuery": { "description": "The target node which should fulfill the request.", "in": "query", "name": "node_name", "required": false, "type": "string" }, "CommonSortParameterQuery": { "description": "Name(s) of the property to sort by - e.g. `city`, or `country,city`.", "in": "query", "name": "sort", "required": false, "type": "string" }, "CommonOrderParameterQuery": { "description": "Order parameter to tell how to order (asc or desc) data within given field. Should be used in conjunction with `sort` parameter. If providing multiple `sort` values, provide multiple `order` values in corresponding order, e.g.: `sort=author_name,title&order=desc,asc`.", "in": "query", "name": "order", "required": false, "type": "string" }, "CommonClassParameterQuery": { "description": "The collection from which to query objects. \n\nNote that if the collection name (`class`) is not provided, the response will not include any objects.", "in": "query", "name": "class", "required": false, "type": "string" }, "CommonOutputVerbosityParameterQuery": { "description": "Controls the verbosity of the output, possible values are: `minimal`, `verbose`. Defaults to `minimal`.", "in": "query", "name": "output", "required": false, "type": "string", "default": "minimal" } }, "paths": { "/": { "get": { "description": "Get links to other endpoints to help discover the REST API.", "summary": "List available endpoints", "operationId": "weaviate.root", "responses": { "200": { "description": "Weaviate is alive and ready.", "schema": { "type": "object", "properties": { "links": { "type": "array", "items": { "$ref": "#/definitions/Link" } } } } } }, "tags": ["root"] } }, "/.well-known/live": { "get": { "summary": "Check application liveness", "description": "Indicates if the Weaviate instance is running and responsive to basic HTTP requests. Primarily used for health checks, such as Kubernetes liveness probes.", "operationId": "weaviate.wellknown.liveness", "responses": { "200": { "description": "The application is alive and responding to HTTP requests." } }, "tags": ["well-known"] } }, "/.well-known/ready": { "get": { "summary": "Check application readiness", "description": "Indicates if the Weaviate instance has completed its startup routines and is prepared to accept user traffic (data import, queries, etc.). Used for readiness checks, such as Kubernetes readiness probes.", "operationId": "weaviate.wellknown.readiness", "responses": { "200": { "description": "The application is ready to serve traffic." }, "503": { "description": "The application is not ready to serve traffic. Traffic should be directed to other available replicas if applicable." } }, "tags": ["well-known"] } }, "/.well-known/openid-configuration": { "get": { "summary": "Get OIDC configuration", "description": "Provides OpenID Connect (OIDC) discovery information if OIDC authentication is configured for Weaviate. Returns details like the token issuer URL, client ID, and required scopes.", "responses": { "200": { "description": "OIDC configuration details returned successfully.", "schema": { "type": "object", "properties": { "href": { "description": "The OIDC issuer URL to redirect to for authentication.", "type": "string" }, "clientId": { "description": "The OAuth Client ID configured for Weaviate.", "type": "string" }, "scopes": { "description": "The required OAuth scopes for authentication.", "type": "array", "items": { "type": "string" }, "x-omitempty": true } } } }, "404": { "description": "OIDC provider is not configured for this Weaviate instance." }, "500": { "description": "An internal server error occurred while retrieving OIDC configuration. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "tags": [ "well-known" ], "x-available-in-mqtt": false, "x-available-in-websocket": false } }, "/replication/replicate": { "post": { "summary": "Initiate a replica movement", "description": "Begins an asynchronous operation to move or copy a specific shard replica from its current node to a designated target node. The operation involves copying data, synchronizing, and potentially decommissioning the source replica.", "operationId": "replicate", "x-serviceIds": [ "weaviate.replication.replicate" ], "tags": [ "replication" ], "parameters": [ { "in": "body", "name": "body", "required": true, "schema": { "$ref": "#/definitions/ReplicationReplicateReplicaRequest" } } ], "responses": { "200": { "description": "Replication operation registered successfully. ID of the operation is returned.", "schema": { "$ref": "#/definitions/ReplicationReplicateReplicaResponse" } }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "501": { "description": "Replica movement operations are disabled.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } }, "delete": { "summary": "Delete all replication operations", "description": "Schedules all replication operations for deletion across all collections, shards, and nodes.", "operationId": "deleteAllReplications", "x-serviceIds": [ "weaviate.replication.deleteAllReplications" ], "tags": [ "replication" ], "responses": { "204": { "description": "Replication operation registered successfully" }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "501": { "description": "Replica movement operations are disabled.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/replication/replicate/force-delete": { "post": { "summary": "Force delete replication operations", "description": "USE AT OWN RISK! Synchronously force delete operations from the FSM. This will not perform any checks on which state the operation is in so may lead to data corruption or loss. It is recommended to first scale the number of replication engine workers to 0 before calling this endpoint to ensure no operations are in-flight.", "operationId": "forceDeleteReplications", "x-serviceIds": [ "weaviate.replication.forceDeleteReplications" ], "tags": [ "replication" ], "parameters": [ { "name": "body", "in": "body", "schema": { "$ref": "#/definitions/ReplicationReplicateForceDeleteRequest" } } ], "responses": { "200": { "description": "Replication operations force deleted successfully.", "schema": { "$ref": "#/definitions/ReplicationReplicateForceDeleteResponse" } }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/replication/replicate/{id}": { "get": { "summary": "Retrieve a replication operation", "description": "Fetches the current status and detailed information for a specific replication operation, identified by its unique ID. Optionally includes historical data of the operation's progress if requested.", "operationId": "replicationDetails", "x-serviceIds": [ "weaviate.replication.replicate.details" ], "tags": [ "replication" ], "parameters": [ { "name": "id", "in": "path", "format": "uuid", "description": "The ID of the replication operation to get details for.", "required": true, "type": "string" }, { "name": "includeHistory", "in": "query", "description": "Whether to include the history of the replication operation.", "required": false, "type": "boolean" } ], "responses": { "200": { "description": "The details of the replication operation.", "schema": { "$ref": "#/definitions/ReplicationReplicateDetailsReplicaResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Shard replica operation not found." }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "501": { "description": "Replica movement operations are disabled.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } }, "delete": { "summary": "Delete a replication operation", "description": "Removes a specific replication operation. If the operation is currently active, it will be cancelled and its resources cleaned up before the operation is deleted.", "operationId": "deleteReplication", "x-serviceIds": [ "weaviate.replication.replicate.delete" ], "tags": [ "replication" ], "parameters": [ { "name": "id", "in": "path", "format": "uuid", "description": "The ID of the replication operation to delete.", "required": true, "type": "string" } ], "responses": { "204": { "description": "Successfully deleted." }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Shard replica operation not found." }, "409": { "description": "The operation is not in a deletable state, e.g. it is a MOVE op in the DEHYDRATING state.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "501": { "description": "Replica movement operations are disabled.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/replication/replicate/list": { "get": { "summary": "List replication operations", "description": "Retrieves a list of currently registered replication operations, optionally filtered by collection, shard, or node ID.", "operationId": "listReplication", "x-serviceIds": [ "weaviate.replication.replicate.details" ], "tags": [ "replication" ], "parameters": [ { "name": "targetNode", "in": "query", "description": "The name of the target node to get details for.", "required": false, "type": "string" }, { "name": "collection", "in": "query", "description": "The name of the collection to get details for.", "required": false, "type": "string" }, { "name": "shard", "in": "query", "description": "The shard to get details for.", "required": false, "type": "string" }, { "name": "includeHistory", "in": "query", "description": "Whether to include the history of the replication operation.", "required": false, "type": "boolean" } ], "responses": { "200": { "description": "The details of the replication operations.", "schema": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/ReplicationReplicateDetailsReplicaResponse" } } }, "400": { "description": "Bad request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "501": { "description": "Replica movement operations are disabled.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/replication/replicate/{id}/cancel": { "post": { "summary": "Cancel a replication operation", "description": "Requests the cancellation of an active replication operation identified by its ID. The operation will be stopped, but its record will remain in the `CANCELLED` state (can't be resumed) and will not be automatically deleted.", "operationId": "cancelReplication", "x-serviceIds": [ "weaviate.replication.replicate.cancel" ], "tags": [ "replication" ], "parameters": [ { "name": "id", "in": "path", "format": "uuid", "description": "The ID of the replication operation to cancel.", "required": true, "type": "string" } ], "responses": { "204": { "description": "Successfully cancelled." }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Shard replica operation not found." }, "409": { "description": "The operation is not in a cancellable state, e.g. it is READY or is a MOVE op in the DEHYDRATING state.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "501": { "description": "Replica movement operations are disabled.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/replication/sharding-state": { "get": { "summary": "Get sharding state", "description": "Fetches the current sharding state, including replica locations and statuses, for all collections or a specified collection. If a shard name is provided along with a collection, the state for that specific shard is returned.", "operationId": "getCollectionShardingState", "x-serviceIds": [ "weaviate.replication.shardingstate.collection.get" ], "tags": [ "replication" ], "parameters": [ { "name": "collection", "in": "query", "description": "The collection name to get the sharding state for.", "required": false, "type": "string" }, { "name": "shard", "in": "query", "description": "The shard to get the sharding state for.", "required": false, "type": "string" } ], "responses": { "200": { "description": "Successfully retrieved sharding state.", "schema": { "$ref": "#/definitions/ReplicationShardingStateResponse" } }, "400": { "description": "Bad request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Collection or shard not found.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "501": { "description": "Replica movement operations are disabled.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/replication/scale": { "get": { "summary": "Get replication scale plan", "description": "Computes and returns a replication scale plan for a given collection and desired replication factor. The plan includes, for each shard, a list of nodes to be added and a list of nodes to be removed.", "operationId": "getReplicationScalePlan", "x-serviceIds": [ "weaviate.replication.scale.get" ], "tags": [ "replication" ], "produces": [ "application/json" ], "parameters": [ { "name": "collection", "in": "query", "description": "The collection name to get the scaling plan for.", "required": true, "type": "string" }, { "name": "replicationFactor", "in": "query", "description": "The desired replication factor to scale to. Must be a positive integer greater than zero.", "required": true, "type": "integer", "minimum": 1 } ], "responses": { "200": { "description": "Replication scale plan showing node additions and removals per shard.", "schema": { "$ref": "#/definitions/ReplicationScalePlan" } }, "400": { "description": "Bad request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Collection not found.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "501": { "description": "Replica movement operations are disabled.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } }, "post": { "summary": "Apply replication scaling plan", "description": "Apply a replication scaling plan that specifies nodes to add or remove per shard for a given collection.", "operationId": "applyReplicationScalePlan", "x-serviceIds": [ "weaviate.replication.scale.post" ], "tags": [ "replication" ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "in": "body", "name": "body", "description": "The replication scaling plan specifying the collection and its shard-level replica adjustments.", "required": true, "schema": { "$ref": "#/definitions/ReplicationScalePlan" } } ], "responses": { "200": { "description": "List of replication shard copy operation IDs initiated for the scale operation", "schema": { "$ref": "#/definitions/ReplicationScaleApplyResponse" } }, "400": { "description": "Bad request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Collection not found.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "501": { "description": "Replica movement operations are disabled.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/users/own-info": { "get": { "summary": "Get current user info", "description": "Get information about the currently authenticated user, including username and assigned roles.", "operationId": "getOwnInfo", "x-serviceIds": [ "weaviate.users.get.own-info" ], "tags": [ "users" ], "responses": { "200": { "description": "Info about the user.", "schema": { "$ref": "#/definitions/UserOwnInfo" } }, "401": { "description": "Unauthorized or invalid credentials." }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "501": { "description": "Replica movement operations are disabled.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/users/db": { "get": { "summary": "List all users", "description": "Retrieves a list of all database (`db` user type) users with their roles and status information.", "operationId": "listAllUsers", "x-serviceIds": [ "weaviate.users.db.list_all" ], "tags": [ "users" ], "parameters": [ { "description": "Whether to include the last time the users were utilized.", "in": "query", "name": "includeLastUsedTime", "required": false, "type": "boolean", "default": false } ], "responses": { "200": { "description": "Info about the users.", "schema": { "type": "array", "items": { "$ref": "#/definitions/DBUserInfo" } } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/users/db/{user_id}": { "get": { "summary": "Get user info", "description": "Retrieve detailed information about a specific database user (`db` user type), including their roles, status, and type.", "operationId": "getUserInfo", "x-serviceIds": [ "weaviate.users.db.get" ], "tags": [ "users" ], "parameters": [ { "description": "The name of the user.", "in": "path", "name": "user_id", "required": true, "type": "string" }, { "description": "Whether to include the last used time of the given user", "in": "query", "name": "includeLastUsedTime", "required": false, "type": "boolean", "default": false } ], "responses": { "200": { "description": "Info about the user.", "schema": { "$ref": "#/definitions/DBUserInfo" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "User not found." }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } }, "post": { "summary": "Create a new user", "description": "Create a new database (`db` user type) user with the specified name. Returns an API key for the newly created user.", "operationId": "createUser", "x-serviceIds": [ "weaviate.users.db.create" ], "tags": [ "users" ], "parameters": [ { "description": "The name of the user.", "in": "path", "name": "user_id", "required": true, "type": "string" }, { "in": "body", "name": "body", "required": false, "schema": { "type": "object", "properties": { "import": { "type": "boolean", "description": "EXPERIMENTAL, DONT USE. THIS WILL BE REMOVED AGAIN. - import api key from static user", "default": false }, "createTime": { "type": "string", "format": "date-time", "description": "EXPERIMENTAL, DONT USE. THIS WILL BE REMOVED AGAIN. - set the given time as creation time" } } } } ], "responses": { "201": { "description": "User created successfully and API key returned.", "schema": { "$ref": "#/definitions/UserApiKey" } }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "User not found.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "409": { "description": "A user with the specified name already exists.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } }, "delete": { "summary": "Delete a user", "description": "Delete a database user. You can't delete your current user.", "operationId": "deleteUser", "x-serviceIds": [ "weaviate.users.db.delete" ], "tags": [ "users" ], "parameters": [ { "description": "The name of the user.", "in": "path", "name": "user_id", "required": true, "type": "string" } ], "responses": { "204": { "description": "Successfully deleted." }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "User not found." }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/users/db/{user_id}/rotate-key": { "post": { "summary": "Rotate API key of a user", "description": "Revoke the current API key for the specified database user (`db` user type) and generate a new one.", "operationId": "rotateUserApiKey", "x-serviceIds": [ "weaviate.users.db.rotateApiKey" ], "tags": [ "users" ], "parameters": [ { "description": "The name of the user.", "in": "path", "name": "user_id", "required": true, "type": "string" } ], "responses": { "200": { "description": "API key successfully updated.", "schema": { "$ref": "#/definitions/UserApiKey" } }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "User not found." }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/users/db/{user_id}/activate": { "post": { "summary": "Activate a user", "description": "Activate a deactivated database user (`db` user type).", "operationId": "activateUser", "x-serviceIds": [ "weaviate.users.db.activateUser" ], "tags": [ "users" ], "parameters": [ { "description": "The name of the user.", "in": "path", "name": "user_id", "required": true, "type": "string" } ], "responses": { "200": { "description": "User successfully activated." }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "User not found." }, "409": { "description": "User already activated." }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/users/db/{user_id}/deactivate": { "post": { "summary": "Deactivate a user", "description": "Deactivate a database user (`db` user type).", "operationId": "deactivateUser", "x-serviceIds": [ "weaviate.users.db.deactivateUser" ], "tags": [ "users" ], "parameters": [ { "description": "The name of the user.", "in": "path", "name": "user_id", "required": true, "type": "string" }, { "in": "body", "name": "body", "required": false, "schema": { "type": "object", "properties": { "revoke_key": { "type": "boolean", "description": "Whether the API key should be revoked when deactivating the user.", "default": false } } } } ], "responses": { "200": { "description": "User successfully deactivated." }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "User not found." }, "409": { "description": "User already deactivated." }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/authz/roles": { "get": { "summary": "Get all roles", "description": "Get all roles and their assigned permissions.", "operationId": "getRoles", "x-serviceIds": [ "weaviate.authz.get.roles" ], "tags": [ "authz" ], "responses": { "200": { "description": "Successful response.", "schema": { "$ref": "#/definitions/RolesListResponse" } }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } }, "post": { "summary": "Create new role", "description": "Create a new role with the specified permissions.", "operationId": "createRole", "x-serviceIds": [ "weaviate.authz.create.role" ], "tags": [ "authz" ], "parameters": [ { "in": "body", "name": "body", "required": true, "schema": { "$ref": "#/definitions/Role" } } ], "responses": { "201": { "description": "Role created successfully." }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "409": { "description": "Role already exists.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/authz/roles/{id}/add-permissions": { "post": { "summary": "Add permissions to a role", "description": "Add new permissions to an existing role without affecting current permissions.", "operationId": "addPermissions", "x-serviceIds": [ "weaviate.authz.add.role.permissions" ], "tags": [ "authz" ], "parameters": [ { "description": "The name (ID) of the role being modified.", "in": "path", "name": "id", "required": true, "type": "string" }, { "in": "body", "name": "body", "required": true, "schema": { "type": "object", "properties": { "permissions": { "type": "array", "items": { "$ref": "#/definitions/Permission" }, "description": "Permissions to be added to the role." } }, "required": [ "name", "permissions" ] } } ], "responses": { "200": { "description": "Permissions added successfully." }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "No role found." }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/authz/roles/{id}/remove-permissions": { "post": { "summary": "Remove permissions from a role", "description": "Permissions can be revoked from a specified role. Removing all permissions from a role will delete the role itself.", "operationId": "removePermissions", "x-serviceIds": [ "weaviate.authz.remove.role.permissions" ], "tags": [ "authz" ], "parameters": [ { "description": "The name of the role being modified.", "in": "path", "name": "id", "required": true, "type": "string" }, { "in": "body", "name": "body", "required": true, "schema": { "type": "object", "properties": { "permissions": { "type": "array", "items": { "$ref": "#/definitions/Permission" }, "description": "Permissions to remove from the role." } }, "required": [ "permissions" ] } } ], "responses": { "200": { "description": "Permissions removed successfully." }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "No role found." }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/authz/roles/{id}": { "get": { "summary": "Get a role", "description": "Fetch a role by its name.", "operationId": "getRole", "x-serviceIds": [ "weaviate.authz.get.role" ], "tags": [ "authz" ], "parameters": [ { "description": "The name of the role.", "in": "path", "name": "id", "required": true, "type": "string" } ], "responses": { "200": { "description": "Successful response.", "schema": { "$ref": "#/definitions/Role" } }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "No role found." }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } }, "delete": { "summary": "Delete a role", "description": "Deleting a role will remove it from the system, and revoke the associated permissions from all users who had this role.", "operationId": "deleteRole", "x-serviceIds": [ "weaviate.authz.delete.role" ], "tags": [ "authz" ], "parameters": [ { "description": "The name of the role.", "in": "path", "name": "id", "required": true, "type": "string" } ], "responses": { "204": { "description": "Successfully deleted." }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/authz/roles/{id}/has-permission": { "post": { "summary": "Check whether a role possesses a permission", "description": "Check whether a role has the specified permissions.", "operationId": "hasPermission", "x-serviceIds": [ "weaviate.authz.has.role.permission" ], "tags": [ "authz" ], "parameters": [ { "description": "The name of the role.", "in": "path", "name": "id", "required": true, "type": "string" }, { "description": "The permissions to be checked.", "in": "body", "name": "body", "required": true, "schema": { "$ref": "#/definitions/Permission" } } ], "responses": { "200": { "description": "Permission check was successful.", "schema": { "type": "boolean" } }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "No role found." }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/authz/roles/{id}/users": { "get": { "deprecated": true, "summary": "Get users assigned to a role", "description": "Get all the users (`db` + `oidc`) who have been assigned a specific role. Deprecated, will be removed when v1.29 is not supported anymore.", "operationId": "getUsersForRoleDeprecated", "x-serviceIds": [ "weaviate.authz.get.roles.users" ], "tags": [ "authz" ], "parameters": [ { "description": "The name of the role.", "in": "path", "name": "id", "required": true, "type": "string" } ], "responses": { "200": { "description": "Users assigned to this role.", "schema": { "type": "array", "items": { "type": "string" } } }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "No role found." }, "410": { "description": "Endpoint not available in the current cluster configuration.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/authz/roles/{id}/user-assignments": { "get": { "summary": "Get users assigned to a role", "description": "Fetch a list of users which have the specified role.", "operationId": "getUsersForRole", "x-serviceIds": [ "weaviate.authz.get.roles.users" ], "tags": [ "authz" ], "parameters": [ { "description": "The name (ID) of the role.", "in": "path", "name": "id", "required": true, "type": "string" } ], "responses": { "200": { "description": "Users assigned to this role.", "schema": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "userType": { "$ref": "#/definitions/UserTypeOutput" } }, "required": [ "name", "userType" ] } } }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "No role found." }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/authz/roles/{id}/group-assignments": { "get": { "summary": "Get groups that have a specific role assigned", "description": "Retrieves a list of all groups that have been assigned a specific role, identified by its name.", "operationId": "getGroupsForRole", "x-serviceIds": [ "weaviate.authz.get.roles.groups" ], "tags": [ "authz" ], "parameters": [ { "description": "The unique name of the role.", "in": "path", "name": "id", "required": true, "type": "string" } ], "responses": { "200": { "description": "Successfully retrieved the list of groups that have the role assigned.", "schema": { "type": "array", "items": { "type": "object", "properties": { "groupId": { "type": "string" }, "groupType": { "$ref": "#/definitions/GroupType" } }, "required": [ "name", "groupType" ] } } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "The specified role was not found." }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/authz/users/{id}/roles": { "get": { "deprecated": true, "summary": "Get roles assigned to a user", "description": "Retrieve the roles assigned to a specific user (`db` + `oidc`). Deprecated, will be removed when 1.29 is not supported anymore", "operationId": "getRolesForUserDeprecated", "x-serviceIds": [ "weaviate.authz.get.users.roles" ], "tags": [ "authz" ], "parameters": [ { "description": "The name of the user.", "in": "path", "name": "id", "required": true, "type": "string" } ], "responses": { "200": { "description": "Roles assigned to the user.", "schema": { "$ref": "#/definitions/RolesListResponse" } }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "No roles found for specified user." }, "410": { "description": "Endpoint not available in the current cluster configuration.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/authz/users/{id}/roles/{userType}": { "get": { "summary": "Get roles assigned to a user", "description": "Get all the roles for a specific user (`db` or `oidc`).", "operationId": "getRolesForUser", "x-serviceIds": [ "weaviate.authz.get.users.roles" ], "tags": [ "authz" ], "parameters": [ { "description": "The name of the user.", "in": "path", "name": "id", "required": true, "type": "string" }, { "in": "path", "name": "userType", "required": true, "type": "string", "enum": [ "oidc", "db" ], "description": "The type of the user." }, { "in": "query", "name": "includeFullRoles", "required": false, "type": "boolean", "default": false, "description": "Whether to include detailed role information like its assigned permissions." } ], "responses": { "200": { "description": "Roles assigned to the user.", "schema": { "$ref": "#/definitions/RolesListResponse" } }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "No roles found for specified user." }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/authz/users/{id}/assign": { "post": { "summary": "Assign a role to a user", "description": "Assign one or more roles to a user. Users can have multiple roles.", "operationId": "assignRoleToUser", "x-serviceIds": [ "weaviate.authz.assign.role.user" ], "tags": [ "authz" ], "parameters": [ { "description": "The name of the user.", "in": "path", "name": "id", "required": true, "type": "string" }, { "in": "body", "name": "body", "required": true, "schema": { "type": "object", "properties": { "roles": { "type": "array", "description": "The roles that are assigned to the specified user.", "items": { "type": "string" } }, "userType": { "$ref": "#/definitions/UserTypeInput" } } } } ], "responses": { "200": { "description": "Role assigned successfully." }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Specified role or user not found.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/authz/users/{id}/revoke": { "post": { "summary": "Revoke a role from a user", "description": "Remove one or more roles from a user.", "operationId": "revokeRoleFromUser", "x-serviceIds": [ "weaviate.authz.revoke.role.user" ], "tags": [ "authz" ], "parameters": [ { "description": "The name of the user.", "in": "path", "name": "id", "required": true, "type": "string" }, { "in": "body", "name": "body", "required": true, "schema": { "type": "object", "properties": { "roles": { "type": "array", "description": "The roles to revoke from the specified user.", "items": { "type": "string" } }, "userType": { "$ref": "#/definitions/UserTypeInput" } } } } ], "responses": { "200": { "description": "Roles revoked successfully." }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Specified role or user not found.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/authz/groups/{id}/assign": { "post": { "summary": "Assign a role to a group", "description": "Assign roles to the specified group.", "operationId": "assignRoleToGroup", "x-serviceIds": [ "weaviate.authz.assign.role" ], "tags": [ "authz" ], "parameters": [ { "description": "The name of the group.", "in": "path", "name": "id", "required": true, "type": "string" }, { "in": "body", "name": "body", "required": true, "schema": { "type": "object", "properties": { "roles": { "type": "array", "description": "The roles to assign to the specified group.", "items": { "type": "string" } }, "groupType": { "$ref": "#/definitions/GroupType" } } } } ], "responses": { "200": { "description": "Roles assigned successfully." }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Role or group not found." }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/authz/groups/{id}/revoke": { "post": { "summary": "Revoke a role from a group", "description": "Revoke roles from the specified group.", "operationId": "revokeRoleFromGroup", "x-serviceIds": [ "weaviate.authz.revoke.role.group" ], "tags": [ "authz" ], "parameters": [ { "description": "The name of the group.", "in": "path", "name": "id", "required": true, "type": "string" }, { "in": "body", "name": "body", "required": true, "schema": { "type": "object", "properties": { "roles": { "type": "array", "description": "The roles to revoke from the specified group.", "items": { "type": "string" } }, "groupType": { "$ref": "#/definitions/GroupType" } } } } ], "responses": { "200": { "description": "Roles revoked successfully." }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Role or group not found." }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/authz/groups/{id}/roles/{groupType}": { "get": { "summary": "Get roles assigned to a specific group", "description": "Retrieves a list of all roles assigned to a specific group. The group must be identified by both its name (`id`) and its type (`db` or `oidc`).", "operationId": "getRolesForGroup", "x-serviceIds": [ "weaviate.authz.get.groups.roles" ], "tags": [ "authz" ], "parameters": [ { "description": "The unique name of the group.", "in": "path", "name": "id", "required": true, "type": "string" }, { "in": "path", "name": "groupType", "required": true, "type": "string", "enum": [ "oidc" ], "description": "The type of the group." }, { "in": "query", "name": "includeFullRoles", "required": false, "type": "boolean", "default": false, "description": "If true, the response will include the full role definitions with all associated permissions. If false, only role names are returned." } ], "responses": { "200": { "description": "A list of roles assigned to the specified group.", "schema": { "$ref": "#/definitions/RolesListResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "The specified group was not found." }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/authz/groups/{groupType}": { "get": { "summary": "List all groups of a specific type", "description": "Retrieves a list of all available group names for a specified group type (`oidc` or `db`).", "operationId": "getGroups", "x-serviceIds": [ "weaviate.authz.get.groups" ], "tags": [ "authz" ], "parameters": [ { "in": "path", "name": "groupType", "required": true, "type": "string", "enum": [ "oidc" ], "description": "The type of group to retrieve." } ], "responses": { "200": { "description": "A list of group names for the specified type.", "schema": { "type": "array", "items": { "type": "string" } } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/objects": { "get": { "description": "Retrieves a list of data objects. By default, objects are returned in reverse order of creation. Requires a collection name (`class`) parameter to specify which collection's objects to list, otherwise, returns an empty list.", "operationId": "objects.list", "x-serviceIds": [ "weaviate.local.query" ], "parameters": [ { "$ref": "#/parameters/CommonAfterParameterQuery" }, { "$ref": "#/parameters/CommonOffsetParameterQuery" }, { "$ref": "#/parameters/CommonLimitParameterQuery" }, { "$ref": "#/parameters/CommonIncludeParameterQuery" }, { "$ref": "#/parameters/CommonSortParameterQuery" }, { "$ref": "#/parameters/CommonOrderParameterQuery" }, { "$ref": "#/parameters/CommonClassParameterQuery" }, { "$ref": "#/parameters/CommonTenantParameterQuery" } ], "responses": { "200": { "description": "Successful response containing the list of objects. If the collection name (`class`) is not provided, the response will not include any objects.", "schema": { "$ref": "#/definitions/ObjectsListResponse" } }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Successful query result but no matching objects were found." }, "410": { "description": "Endpoint not available in the current cluster configuration.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request. Ensure the specified collection exists.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error occurred while trying to fulfill the request. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "summary": "List objects", "tags": [ "objects" ], "x-available-in-mqtt": false, "x-available-in-websocket": false }, "post": { "description": "Creates a new data object. The object's metadata and schema values are validated before creation.\n\n**Note (batch import)**:\nIf you plan on importing a large number of objects, using the `/batch/objects` endpoint is significantly more efficient than sending multiple single requests.\n\n**Note (idempotence)**:\nThis operation (POST) fails if an object with the provided ID already exists. To update an existing object, use the PUT or PATCH methods.", "operationId": "objects.create", "x-serviceIds": [ "weaviate.local.add" ], "parameters": [ { "in": "body", "name": "body", "description": "The object to be created.", "required": true, "schema": { "$ref": "#/definitions/Object" } }, { "$ref": "#/parameters/CommonConsistencyLevelParameterQuery" } ], "responses": { "200": { "description": "Object created successfully.", "schema": { "$ref": "#/definitions/Object" } }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request. Ensure the collection exists and the object properties are valid.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "429": { "description": "The configured object-count usage limit was exceeded. See `UsageLimitExceededResponse` for the limit value.", "schema": { "$ref": "#/definitions/UsageLimitExceededResponse" } }, "500": { "description": "An error occurred while trying to fulfill the request. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "summary": "Create an object", "tags": [ "objects" ], "x-available-in-mqtt": false, "x-available-in-websocket": false } }, "/objects/{id}": { "delete": { "description": "Deletes an object from the database based on its UUID. \n\n**Note**: This endpoint is deprecated and will be removed in a future version. Use the `/objects/{className}/{id}` endpoint instead.", "operationId": "objects.delete", "x-serviceIds": [ "weaviate.local.manipulate" ], "parameters": [ { "description": "Unique UUID of the object to be deleted.", "format": "uuid", "in": "path", "name": "id", "required": true, "type": "string" }, { "$ref": "#/parameters/CommonConsistencyLevelParameterQuery" }, { "$ref": "#/parameters/CommonTenantParameterQuery" } ], "responses": { "204": { "description": "Object deleted successfully." }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Object not found." }, "410": { "description": "Endpoint not available in the current cluster configuration.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error occurred while trying to fulfill the request. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "summary": "Delete an object", "tags": [ "objects" ], "x-available-in-mqtt": true, "x-available-in-websocket": true, "deprecated": true }, "get": { "description": "Get a specific object based on its UUID. Also available as Websocket bus. \n\n**Note**: This endpoint is deprecated and will be removed in a future version. Use the `/objects/{className}/{id}` endpoint instead.", "operationId": "objects.get", "x-serviceIds": [ "weaviate.local.query" ], "parameters": [ { "description": "Unique UUID of the object to be retrieved.", "format": "uuid", "in": "path", "name": "id", "required": true, "type": "string" }, { "$ref": "#/parameters/CommonIncludeParameterQuery" } ], "responses": { "200": { "description": "Successful response containing the object.", "schema": { "$ref": "#/definitions/Object" } }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Object not found." }, "410": { "description": "Endpoint not available in the current cluster configuration.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error occurred while trying to fulfill the request. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "summary": "Get an object", "tags": [ "objects" ], "x-available-in-mqtt": false, "x-available-in-websocket": false, "deprecated": true }, "patch": { "description": "Update an object based on its UUID (using patch semantics). This method supports json-merge style patch semantics (RFC 7396). Provided meta-data and schema values are validated. `lastUpdateTimeUnix` is set to the time this function is called. \n\n**Note**: This endpoint is deprecated and will be removed in a future version. Use the `/objects/{className}/{id}` endpoint instead.", "operationId": "objects.patch", "x-serviceIds": [ "weaviate.local.manipulate" ], "parameters": [ { "description": "Unique UUID of the object to be patched.", "format": "uuid", "in": "path", "name": "id", "required": true, "type": "string" }, { "description": "RFC 7396-style JSON merge patch object containing the fields to update.", "in": "body", "name": "body", "required": false, "schema": { "$ref": "#/definitions/Object" } }, { "$ref": "#/parameters/CommonConsistencyLevelParameterQuery" } ], "responses": { "204": { "description": "Object patched successfully." }, "400": { "description": "Malformed patch request body." }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Object not found." }, "410": { "description": "Endpoint not available in the current cluster configuration.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "The patch object is valid JSON but is unprocessable for other reasons (e.g., invalid schema).", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error occurred while trying to fulfill the request. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "summary": "Patch an object", "tags": [ "objects" ], "x-available-in-mqtt": false, "x-available-in-websocket": false, "deprecated": true }, "put": { "description": "Updates an object based on its UUID. Given meta-data and schema values are validated. `lastUpdateTimeUnix` is set to the time this function is called. \n\n**Note**: This endpoint is deprecated and will be removed in a future version. Use the `/objects/{className}/{id}` endpoint instead.", "operationId": "objects.update", "x-serviceIds": [ "weaviate.local.manipulate" ], "parameters": [ { "description": "Unique UUID of the object to be replaced.", "format": "uuid", "in": "path", "name": "id", "required": true, "type": "string" }, { "in": "body", "name": "body", "description": "The object definition to replace the existing object with.", "required": true, "schema": { "$ref": "#/definitions/Object" } }, { "$ref": "#/parameters/CommonConsistencyLevelParameterQuery" } ], "responses": { "200": { "description": "Object replaced successfully.", "schema": { "$ref": "#/definitions/Object" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Object not found." }, "410": { "description": "Endpoint not available in the current cluster configuration.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request. Ensure the collection exists and the object properties are valid.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error occurred while trying to fulfill the request. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "summary": "Update an object", "tags": [ "objects" ], "x-available-in-mqtt": false, "x-available-in-websocket": false, "deprecated": true }, "head": { "description": "Checks if an object exists in the system based on its UUID. \n\n**Note**: This endpoint is deprecated and will be removed in a future version. Use the `/objects/{className}/{id}` endpoint instead.", "operationId": "objects.head", "x-serviceIds": [ "weaviate.objects.check" ], "parameters": [ { "description": "Unique UUID of the object to check.", "format": "uuid", "in": "path", "name": "id", "required": true, "type": "string" } ], "responses": { "204": { "description": "Object exists." }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Object does not exist." }, "410": { "description": "Endpoint not available in the current cluster configuration.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error occurred while trying to fulfill the request. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "summary": "Check if an object exists", "tags": [ "objects" ], "x-available-in-mqtt": true, "x-available-in-websocket": true, "deprecated": true } }, "/objects/{className}/{id}": { "get": { "description": "Get a data object based on its collection name (`className`) and UUID (`id`).", "operationId": "objects.class.get", "x-serviceIds": [ "weaviate.local.query" ], "parameters": [ { "name": "className", "description": "Name of the collection (class) the object belongs to.", "in": "path", "required": true, "type": "string" }, { "description": "Unique UUID of the object to be retrieved.", "format": "uuid", "in": "path", "name": "id", "required": true, "type": "string" }, { "$ref": "#/parameters/CommonIncludeParameterQuery" }, { "$ref": "#/parameters/CommonConsistencyLevelParameterQuery" }, { "$ref": "#/parameters/CommonNodeNameParameterQuery" }, { "$ref": "#/parameters/CommonTenantParameterQuery" } ], "responses": { "200": { "description": "Successful response containing the object.", "schema": { "$ref": "#/definitions/Object" } }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Object not found." }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error occurred while trying to fulfill the request. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "summary": "Get an object", "tags": [ "objects" ], "x-available-in-mqtt": false, "x-available-in-websocket": false }, "delete": { "description": "Removes a data object from a specific collection, identified by its collection name (`className`) and UUID (`id`).\n\n**Note on deleting references (legacy format):**\nFor backward compatibility with older beacon formats (lacking a collection name), deleting a reference requires the beacon in the request to exactly match the stored format. Beacons always use `localhost` as the host, indicating the target is within the same Weaviate instance.", "operationId": "objects.class.delete", "x-serviceIds": [ "weaviate.local.manipulate" ], "parameters": [ { "name": "className", "description": "Name of the collection (class) the object belongs to.", "in": "path", "required": true, "type": "string" }, { "description": "Unique UUID of the object to be deleted.", "format": "uuid", "in": "path", "name": "id", "required": true, "type": "string" }, { "$ref": "#/parameters/CommonConsistencyLevelParameterQuery" }, { "$ref": "#/parameters/CommonTenantParameterQuery" } ], "responses": { "204": { "description": "Object deleted successfully." }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Object not found." }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error occurred while trying to fulfill the request. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "summary": "Delete an object", "tags": [ "objects" ], "x-available-in-mqtt": true, "x-available-in-websocket": true }, "put": { "description": "Replaces properties of an existing data object. The object is identified by its collection name (`className`) and UUID (`id`). The request body must contain the complete object definition with the new property values.", "operationId": "objects.class.put", "x-serviceIds": [ "weaviate.local.manipulate" ], "parameters": [ { "name": "className", "description": "Name of the collection (class) the object belongs to.", "in": "path", "required": true, "type": "string" }, { "description": "Unique UUID of the object to be replaced.", "format": "uuid", "in": "path", "name": "id", "required": true, "type": "string" }, { "in": "body", "name": "body", "description": "The object definition to replace the existing object with.", "required": true, "schema": { "$ref": "#/definitions/Object" } }, { "$ref": "#/parameters/CommonConsistencyLevelParameterQuery" } ], "responses": { "200": { "description": "Object replaced successfully.", "schema": { "$ref": "#/definitions/Object" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Object not found." }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request. Ensure the collection exists and the object properties are valid.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "429": { "description": "The configured object-count usage limit was exceeded. See `UsageLimitExceededResponse` for the limit value.", "schema": { "$ref": "#/definitions/UsageLimitExceededResponse" } }, "500": { "description": "An error occurred while trying to fulfill the request. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "summary": "Replace an object", "tags": [ "objects" ], "x-available-in-mqtt": false, "x-available-in-websocket": false }, "patch": { "description": "Updates specific properties of an existing data object using JSON merge patch semantics (RFC 7396). The object is identified by its collection name (`className`) and UUID (`id`). Only the fields provided in the request body are modified. Metadata and schema values are validated, and the object's `lastUpdateTimeUnix` is updated.", "operationId": "objects.class.patch", "x-serviceIds": [ "weaviate.local.manipulate" ], "parameters": [ { "description": "Name of the collection (class) the object belongs to.", "name": "className", "in": "path", "required": true, "type": "string" }, { "description": "Unique UUID of the object to be patched.", "format": "uuid", "in": "path", "name": "id", "required": true, "type": "string" }, { "description": "RFC 7396-style JSON merge patch object containing the fields to update.", "in": "body", "name": "body", "required": false, "schema": { "$ref": "#/definitions/Object" } }, { "$ref": "#/parameters/CommonConsistencyLevelParameterQuery" } ], "responses": { "204": { "description": "Object patched successfully." }, "400": { "description": "Malformed patch request body.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Object not found." }, "422": { "description": "The patch object is valid JSON but is unprocessable for other reasons (e.g., invalid schema).", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error occurred while trying to fulfill the request. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "summary": "Patch an object", "tags": [ "objects" ], "x-available-in-mqtt": false, "x-available-in-websocket": false }, "head": { "description": "Verifies the existence of a specific data object within a collection (class), identified by its collection name (`className`) and UUID (`id`), without returning the object itself.\n\nThis is faster than a GET request as it avoids retrieving and processing object data. Existence is confirmed by a 204 No Content status code, while non-existence results in a 404 Not Found.", "operationId": "objects.class.head", "x-serviceIds": [ "weaviate.local.manipulate" ], "parameters": [ { "description": "Name of the collection (class) the object belongs to.", "name": "className", "in": "path", "required": true, "type": "string" }, { "description": "Unique UUID of the object to check.", "format": "uuid", "in": "path", "name": "id", "required": true, "type": "string" }, { "$ref": "#/parameters/CommonConsistencyLevelParameterQuery" }, { "$ref": "#/parameters/CommonTenantParameterQuery" } ], "responses": { "204": { "description": "Object exists." }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Object does not exist." }, "422": { "description": "Invalid data provided. Please check the values in your request (e.g., invalid UUID format).", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error occurred while trying to fulfill the request. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "summary": "Check if an object exists", "tags": [ "objects" ], "x-available-in-mqtt": true, "x-available-in-websocket": true } }, "/objects/{id}/references/{propertyName}": { "post": { "description": "Add a reference to a specific property of a data object. \n\n**Note**: This endpoint is deprecated and will be removed in a future version. Use the `/objects/{className}/{id}/references/{propertyName}` endpoint instead.", "operationId": "objects.references.create", "x-serviceIds": [ "weaviate.local.manipulate" ], "parameters": [ { "description": "Unique UUID of the source object.", "format": "uuid", "in": "path", "name": "id", "required": true, "type": "string" }, { "description": "Unique name of the reference property of the source object.", "in": "path", "name": "propertyName", "required": true, "type": "string" }, { "in": "body", "name": "body", "description": "The reference to add.", "required": true, "schema": { "$ref": "#/definitions/SingleRef" } }, { "$ref": "#/parameters/CommonTenantParameterQuery" } ], "responses": { "200": { "description": "Reference added successfully." }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "410": { "description": "Endpoint not available in the current cluster configuration.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request. Ensure the property exists and is a reference type.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error occurred while trying to fulfill the request. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "summary": "Add an object reference", "tags": [ "objects" ], "x-available-in-mqtt": false, "x-available-in-websocket": false, "deprecated": true }, "put": { "description": "Replace all references in cross-reference property of an object. \n\n**Note**: This endpoint is deprecated and will be removed in a future version. Use the `/objects/{className}/{id}/references/{propertyName}` endpoint instead.", "operationId": "objects.references.update", "x-serviceIds": [ "weaviate.local.manipulate" ], "parameters": [ { "description": "Unique UUID of the source object.", "format": "uuid", "in": "path", "name": "id", "required": true, "type": "string" }, { "description": "Unique name of the reference property of the source object.", "in": "path", "name": "propertyName", "required": true, "type": "string" }, { "in": "body", "name": "body", "description": "The new list of references.", "required": true, "schema": { "$ref": "#/definitions/MultipleRef" } }, { "$ref": "#/parameters/CommonTenantParameterQuery" } ], "responses": { "200": { "description": "References replaced successfully." }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "410": { "description": "Endpoint not available in the current cluster configuration.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request. Ensure the property exists and is a reference type.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error occurred while trying to fulfill the request. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "summary": "Replace object references", "tags": [ "objects" ], "x-available-in-mqtt": false, "x-available-in-websocket": false, "deprecated": true }, "delete": { "description": "Delete the single reference that is given in the body from the list of references that this property has. \n\n**Note**: This endpoint is deprecated and will be removed in a future version. Use the `/objects/{className}/{id}/references/{propertyName}` endpoint instead.", "operationId": "objects.references.delete", "x-serviceIds": [ "weaviate.local.manipulate" ], "parameters": [ { "description": "Unique UUID of the source object.", "format": "uuid", "in": "path", "name": "id", "required": true, "type": "string" }, { "description": "Unique name of the reference property of the source object.", "in": "path", "name": "propertyName", "required": true, "type": "string" }, { "in": "body", "name": "body", "description": "The reference to remove.", "required": true, "schema": { "$ref": "#/definitions/SingleRef" } }, { "$ref": "#/parameters/CommonTenantParameterQuery" } ], "responses": { "204": { "description": "Reference deleted successfully." }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Object or reference not found.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "410": { "description": "Endpoint not available in the current cluster configuration.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error occurred while trying to fulfill the request. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "summary": "Delete an object reference", "tags": [ "objects" ], "x-available-in-mqtt": false, "x-available-in-websocket": false, "deprecated": true } }, "/objects/{className}/{id}/references/{propertyName}": { "post": { "description": "Adds a new reference to a reference property (`propertyName`) on a source data object. The source object is identified by its collection name (`className`) and UUID (`id`). The reference to add is specified in the request body.", "operationId": "objects.class.references.create", "x-serviceIds": [ "weaviate.local.manipulate" ], "parameters": [ { "description": "Name of the collection (class) the source object belongs to.", "name": "className", "in": "path", "required": true, "type": "string" }, { "description": "Unique UUID of the source object.", "format": "uuid", "in": "path", "name": "id", "required": true, "type": "string" }, { "description": "Unique name of the reference property of the source object.", "in": "path", "name": "propertyName", "required": true, "type": "string" }, { "in": "body", "name": "body", "description": "The reference to add.", "required": true, "schema": { "$ref": "#/definitions/SingleRef" } }, { "$ref": "#/parameters/CommonConsistencyLevelParameterQuery" }, { "$ref": "#/parameters/CommonTenantParameterQuery" } ], "responses": { "200": { "description": "Reference added successfully." }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Source object not found." }, "410": { "description": "Endpoint not available in the current cluster configuration.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request. Ensure the property exists and is a reference type.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error occurred while trying to fulfill the request. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "summary": "Add an object reference", "tags": [ "objects" ], "x-available-in-mqtt": false, "x-available-in-websocket": false }, "put": { "description": "Replaces all existing references for a specific reference property (`propertyName`) on a source data object. The source object is identified by its collection name (`className`) and UUID (`id`). The new set of references is provided in the request body.", "operationId": "objects.class.references.put", "x-serviceIds": [ "weaviate.local.manipulate" ], "parameters": [ { "description": "Name of the collection (class) the source object belongs to.", "name": "className", "in": "path", "required": true, "type": "string" }, { "description": "Unique UUID of the source object.", "format": "uuid", "in": "path", "name": "id", "required": true, "type": "string" }, { "description": "Unique name of the reference property of the source object.", "in": "path", "name": "propertyName", "required": true, "type": "string" }, { "in": "body", "name": "body", "description": "The new list of references.", "required": true, "schema": { "$ref": "#/definitions/MultipleRef" } }, { "$ref": "#/parameters/CommonConsistencyLevelParameterQuery" }, { "$ref": "#/parameters/CommonTenantParameterQuery" } ], "responses": { "200": { "description": "References replaced successfully." }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Source object not found." }, "410": { "description": "Endpoint not available in the current cluster configuration.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request. Ensure the property exists and is a reference type.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error occurred while trying to fulfill the request. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "summary": "Replace object references", "tags": [ "objects" ], "x-available-in-mqtt": false, "x-available-in-websocket": false }, "delete": { "description": "Removes a specific reference from a reference property (`propertyName`) of a source data object. The source object is identified by its collection name (`className`) and UUID (`id`). The reference to remove is specified in the request body.", "operationId": "objects.class.references.delete", "x-serviceIds": [ "weaviate.local.manipulate" ], "parameters": [ { "description": "Name of the collection (class) the source object belongs to.", "name": "className", "in": "path", "required": true, "type": "string" }, { "description": "Unique UUID of the source object.", "format": "uuid", "in": "path", "name": "id", "required": true, "type": "string" }, { "description": "Unique name of the reference property of the source object.", "in": "path", "name": "propertyName", "required": true, "type": "string" }, { "in": "body", "name": "body", "description": "The reference to remove.", "required": true, "schema": { "$ref": "#/definitions/SingleRef" } }, { "$ref": "#/parameters/CommonConsistencyLevelParameterQuery" }, { "$ref": "#/parameters/CommonTenantParameterQuery" } ], "responses": { "204": { "description": "Reference deleted successfully." }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Object or reference not found.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "410": { "description": "Endpoint not available in the current cluster configuration.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request. Ensure the property exists and is a reference type.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error occurred while trying to fulfill the request. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "summary": "Delete an object reference", "tags": [ "objects" ], "x-available-in-mqtt": false, "x-available-in-websocket": false } }, "/objects/validate": { "post": { "description": "Checks if a data object's structure conforms to the specified collection schema and metadata rules without actually storing the object.\n\nA successful validation returns a 200 OK status code with no body. If validation fails, an error response with details is returned.", "operationId": "objects.validate", "x-serviceIds": [ "weaviate.local.query.meta" ], "parameters": [ { "in": "body", "name": "body", "description": "The object definition to validate.", "required": true, "schema": { "$ref": "#/definitions/Object" } } ], "responses": { "200": { "description": "Object is valid according to the schema." }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Request body is well-formed but the object is invalid according to the schema.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error occurred while trying to fulfill the request. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "summary": "Validate an object", "tags": [ "objects" ], "x-available-in-mqtt": false, "x-available-in-websocket": false } }, "/batch/objects": { "post": { "description": "Registers multiple data objects in a single request for efficiency. Metadata and schema values for each object are validated.\n\n**Note (idempotence)**:\nThis operation is idempotent based on the object UUIDs provided. If an object with a given UUID already exists, it will be overwritten (similar to a PUT operation for that specific object within the batch).", "operationId": "batch.objects.create", "x-serviceIds": [ "weaviate.local.add" ], "parameters": [ { "in": "body", "name": "body", "description": "The request body containing the objects to be created.", "required": true, "schema": { "type": "object", "properties": { "fields": { "description": "Controls which fields are returned in the response for each object. Default is `ALL`.", "type": "array", "items": { "type": "string", "default": "ALL", "enum": [ "ALL", "class", "schema", "id", "creationTimeUnix" ] } }, "objects": { "description": "Array of objects to be created.", "type": "array", "items": { "$ref": "#/definitions/Object" } } } } }, { "$ref": "#/parameters/CommonConsistencyLevelParameterQuery" } ], "responses": { "200": { "description": "Request processed successfully. Individual object statuses are provided in the response body.", "schema": { "type": "array", "items": { "$ref": "#/definitions/ObjectsGetResponse" } } }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request. Ensure the collection exists and the object properties are valid.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "429": { "description": "The configured object-count usage limit was exceeded. The whole batch is rejected (no partial fill); the client decides what to retry. See `UsageLimitExceededResponse` for the limit value.", "schema": { "$ref": "#/definitions/UsageLimitExceededResponse" } }, "500": { "description": "An error occurred while trying to fulfill the request. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "summary": "Create objects in batch", "tags": [ "batch" ], "x-available-in-mqtt": false, "x-available-in-websocket": false }, "delete": { "description": "Removes multiple data objects based on a filter specified in the request body.\n\nDeletion occurs based on the filter criteria provided in the `where` clause. There is a configurable limit (default 10,000, set via `QUERY_MAXIMUM_RESULTS`) on how many objects can be deleted in a single batch request to prevent excessive resource usage. Objects are deleted in the order they match the filter. To delete more objects than the limit allows, repeat the request until no more matching objects are found.", "operationId": "batch.objects.delete", "x-serviceIds": [ "weaviate.local.manipulate" ], "parameters": [ { "in": "body", "name": "body", "description": "The request body containing the match filter and output configuration.", "required": true, "schema": { "$ref": "#/definitions/BatchDelete" } }, { "$ref": "#/parameters/CommonConsistencyLevelParameterQuery" }, { "$ref": "#/parameters/CommonTenantParameterQuery" } ], "responses": { "200": { "description": "Request processed successfully. See response body for matching objects and deletion results.", "schema": { "$ref": "#/definitions/BatchDeleteResponse" } }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Invalid data provided. Please check the values in your request (e.g., invalid filter).", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error occurred while trying to fulfill the request. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "summary": "Delete objects in batch", "tags": [ "batch" ], "x-available-in-mqtt": false, "x-available-in-websocket": false } }, "/batch/references": { "post": { "description": "Batch create cross-references between collection items in bulk.", "operationId": "batch.references.create", "x-serviceIds": [ "weaviate.local.add" ], "parameters": [ { "in": "body", "name": "body", "description": "A list of references to be batched. The ideal size depends on the used database connector. Please see the documentation of the used connector for help.", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/BatchReference" } } }, { "$ref": "#/parameters/CommonConsistencyLevelParameterQuery" } ], "responses": { "200": { "description": "Request Successful. Warning: A successful request does not guarantee that every batched reference was successfully created. Inspect the response body to see which references succeeded and which failed.", "schema": { "type": "array", "items": { "$ref": "#/definitions/BatchReferenceResponse" } } }, "400": { "description": "Malformed request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request. Ensure the collection exists and the object properties are valid.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "summary": "Create cross-references in bulk", "tags": [ "batch" ], "x-available-in-mqtt": false, "x-available-in-websocket": false } }, "/graphql": { "post": { "summary": "Perform a GraphQL query", "description": "Executes a single GraphQL query provided in the request body. Use this endpoint for all Weaviate data queries and exploration.", "operationId": "graphql.post", "x-serviceIds": [ "weaviate.local.query", "weaviate.local.query.meta", "weaviate.network.query", "weaviate.network.query.meta" ], "parameters": [ { "description": "The GraphQL query to execute, including the query string and optional variables.", "in": "body", "name": "body", "required": true, "schema": { "$ref": "#/definitions/GraphQLQuery" } } ], "responses": { "200": { "description": "Query executed successfully. The response body contains the query result.", "schema": { "$ref": "#/definitions/GraphQLResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "410": { "description": "Endpoint not available in the current cluster configuration.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An internal server error occurred during query execution. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "tags": [ "graphql" ], "x-available-in-mqtt": false, "x-available-in-websocket": false } }, "/graphql/batch": { "post": { "summary": "Perform batched GraphQL queries", "description": "Executes multiple GraphQL queries provided in the request body as an array. Allows performing several queries in a single network request for efficiency.", "operationId": "graphql.batch", "x-serviceIds": [ "weaviate.local.query", "weaviate.local.query.meta", "weaviate.network.query", "weaviate.network.query.meta" ], "parameters": [ { "description": "An array containing multiple GraphQL query objects to execute in batch.", "in": "body", "name": "body", "required": true, "schema": { "$ref": "#/definitions/GraphQLQueries" } } ], "responses": { "200": { "description": "Batch request processed successfully. The response body contains an array of results corresponding to the input queries.", "schema": { "$ref": "#/definitions/GraphQLResponses" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "410": { "description": "Endpoint not available in the current cluster configuration.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues. Please check the values in your request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An internal server error occurred during batch query execution. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "tags": [ "graphql" ], "x-available-in-mqtt": false, "x-available-in-websocket": false } }, "/meta": { "get": { "summary": "Get instance metadata", "description": "Provides meta-information about the running Weaviate instance, including its version, loaded modules, and network hostname. This information can be useful for monitoring, compatibility checks, or inter-instance communication.", "operationId": "meta.get", "x-serviceIds": [ "weaviate.local.query.meta" ], "tags": [ "meta" ], "responses": { "200": { "description": "Successfully retrieved meta information.", "schema": { "$ref": "#/definitions/Meta" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An internal server error occurred while retrieving meta information. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "x-available-in-mqtt": false, "x-available-in-websocket": false } }, "/tokenize": { "post": { "summary": "Tokenize text", "description": "Tokenizes the provided text using the specified tokenization method. This is a stateless utility endpoint useful for debugging and understanding how text will be processed during indexing and querying. The response includes both the indexed tokens (as stored in the inverted index) and query tokens (after optional stopword removal).", "operationId": "tokenize", "tags": [ "tokenize" ], "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/TokenizeRequest" } } ], "responses": { "200": { "description": "Successfully tokenized the text.", "schema": { "$ref": "#/definitions/TokenizeResponse" } }, "400": { "description": "Invalid or malformed request body." }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Request binding or validation error. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An unexpected error occurred while tokenizing the text. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/schema": { "get": { "summary": "Get all collection definitions", "description": "Retrieves the definitions of all collections (classes) currently in the database schema.", "operationId": "schema.dump", "x-serviceIds": [ "weaviate.local.query.meta" ], "tags": [ "schema" ], "parameters": [ { "name": "consistency", "in": "header", "required": false, "default": true, "type": "boolean", "description": "If true, the request is proxied to the cluster leader to ensure strong schema consistency. Default is true." } ], "responses": { "200": { "description": "Successfully retrieved the database schema.", "schema": { "$ref": "#/definitions/Schema" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error occurred while retrieving the schema. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } }, "post": { "summary": "Create a new collection", "description": "Defines and creates a new collection (class).\n\nIf [`AutoSchema`](https://docs.weaviate.io/weaviate/config-refs/collections#auto-schema) is enabled (not recommended for production), Weaviate might attempt to infer schema from data during import. Manual definition via this endpoint provides explicit control.", "operationId": "schema.objects.create", "x-serviceIds": [ "weaviate.local.add.meta" ], "tags": [ "schema" ], "parameters": [ { "name": "objectClass", "in": "body", "required": true, "description": "The definition of the collection (class) to create.", "schema": { "$ref": "#/definitions/Class" } } ], "responses": { "200": { "description": "Collection created successfully and its definition returned.", "schema": { "$ref": "#/definitions/Class" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Invalid collection definition provided. Check the definition structure and properties.", "schema": { "$ref": "#/definitions/RestrictionViolationResponse" } }, "429": { "description": "A configured usage limit (collections/shards) was exceeded. See the `UsageLimitExceededResponse` body for which limit and the configured value.", "schema": { "$ref": "#/definitions/UsageLimitExceededResponse" } }, "500": { "description": "An error occurred during collection creation. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/schema/{className}": { "get": { "summary": "Get a single collection", "description": "Retrieve the definition of a specific collection (`className`), including its properties, configuration, and vectorizer settings.", "operationId": "schema.objects.get", "x-serviceIds": [ "weaviate.local.get.meta" ], "tags": [ "schema" ], "parameters": [ { "name": "className", "description": "The name of the collection (class) to retrieve.", "in": "path", "required": true, "type": "string" }, { "name": "consistency", "in": "header", "required": false, "default": true, "type": "boolean", "description": "If true, the request is proxied to the cluster leader to ensure strong schema consistency. Default is true." } ], "responses": { "200": { "description": "Successfully retrieved the collection definition.", "schema": { "$ref": "#/definitions/Class" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Collection not found." }, "422": { "description": "Invalid collection name provided (e.g. malformed namespace prefix). Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error occurred while retrieving the collection definition. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } }, "delete": { "summary": "Delete a collection (and all associated data)", "description": "Removes a collection definition from the schema. WARNING: This action permanently deletes all data objects stored within the collection.", "operationId": "schema.objects.delete", "x-serviceIds": [ "weaviate.local.manipulate.meta" ], "tags": [ "schema" ], "parameters": [ { "name": "className", "description": "The name of the collection (class) to delete.", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Collection deleted successfully." }, "400": { "description": "Could not delete the collection. See the error response for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error occurred during collection deletion. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } }, "put": { "summary": "Update collection definition", "description": "Updates the configuration settings of an existing collection (`className`) based on the provided definition. Note: This operation modifies mutable settings specified in the request body. It does not add properties (use `POST /schema/{className}/properties` for that) or change the collection name.", "operationId": "schema.objects.update", "x-serviceIds": [ "weaviate.local.manipulate", "weaviate.local.manipulate.meta" ], "tags": [ "schema" ], "parameters": [ { "name": "className", "description": "The name of the collection (class) to update.", "in": "path", "required": true, "type": "string" }, { "name": "objectClass", "description": "The updated collection definition containing the settings to modify.", "in": "body", "required": true, "schema": { "$ref": "#/definitions/Class" } } ], "responses": { "200": { "description": "Collection settings updated successfully.", "schema": { "$ref": "#/definitions/Class" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Collection not found.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Invalid update attempt.", "schema": { "$ref": "#/definitions/RestrictionViolationResponse" } }, "500": { "description": "An error occurred while updating the collection. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/schema/{className}/properties": { "post": { "summary": "Add a property to a collection", "description": "Adds a new property definition to an existing collection (`className`) definition.", "operationId": "schema.objects.properties.add", "x-serviceIds": [ "weaviate.local.manipulate.meta" ], "tags": [ "schema" ], "parameters": [ { "name": "className", "description": "The name of the collection (class) to add the property to.", "in": "path", "required": true, "type": "string" }, { "name": "body", "description": "The definition of the property to add.", "in": "body", "required": true, "schema": { "$ref": "#/definitions/Property" } } ], "responses": { "200": { "description": "Property added successfully and its definition returned.", "schema": { "$ref": "#/definitions/Property" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Invalid property definition provided.", "schema": { "$ref": "#/definitions/RestrictionViolationResponse" } }, "500": { "description": "An error occurred while adding the property. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/schema/{className}/indexes": { "get": { "operationId": "schema.objects.indexes.get", "tags": [ "schema" ], "summary": "Get index status for all properties of a collection", "description": "Returns per-property index state including active reindex progress. This powers the UI to show live migration status.", "parameters": [ { "name": "className", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Index status for all properties.", "schema": { "$ref": "#/definitions/IndexStatusResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Collection not found." }, "500": { "description": "An error occurred.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/schema/{className}/properties/{propertyName}/index/{indexName}": { "put": { "summary": "Declaratively create or migrate a property's inverted index", "description": "Upserts the inverted index of a property, identified by `indexName`. The body describes the desired index configuration; the server diffs it against the current state and either creates the index, migrates its configuration, or does nothing. Index-mutating work is asynchronous: a `202` with a task ID is returned when a reindex task is submitted, and `200` with `{\"status\":\"NO_OP\"}` is returned when the desired configuration is already in place. `indexName` accepts `rangeable` as an alias for `rangeFilters`.", "operationId": "schema.objects.index.upsert", "x-serviceIds": [ "weaviate.local.manipulate.meta" ], "tags": [ "schema" ], "parameters": [ { "name": "className", "description": "The name of the collection (class) containing the property.", "in": "path", "required": true, "type": "string" }, { "name": "propertyName", "description": "The name of the property whose inverted index should be upserted.", "in": "path", "required": true, "type": "string" }, { "name": "indexName", "description": "The inverted index type to upsert. `rangeable` is accepted as a write-path alias for `rangeFilters`.", "in": "path", "required": true, "type": "string", "enum": [ "filterable", "searchable", "rangeFilters", "rangeable" ] }, { "name": "tenants", "in": "query", "required": false, "type": "array", "items": { "type": "string" }, "description": "Tenant names to target. Only valid on multi-tenant collections and only when the resulting operation is format-only (on PUT that is `rangeFilters` creation). Omit to target all tenants." }, { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/IndexUpsertRequest" } } ], "responses": { "200": { "description": "Desired configuration already in place AND no reindex task in flight; no task submitted. Body carries `{\"status\":\"NO_OP\"}`.", "schema": { "$ref": "#/definitions/IndexUpdateResponse" } }, "202": { "description": "A reindex task is running for the requested configuration; the body carries its `taskId` with `{\"status\":\"STARTED\"}`. A request converging on an already-running migration joins it and receives that task's ID.", "schema": { "$ref": "#/definitions/IndexUpdateResponse" } }, "400": { "description": "Validation failure; the message carries an actionable hint.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Unknown collection or property.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "409": { "description": "Conflicting in-flight reindex task; the message names the offending task ID.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Invalid `indexName` path value.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "429": { "description": "Per-collection cap of concurrent active reindex tasks reached.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error occurred.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "503": { "description": "Cluster service unavailable, or an in-flight task's payload cannot be parsed so conflict-freedom cannot be proven.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } }, "delete": { "summary": "Delete a property's inverted index", "description": "Deletes an inverted index of a specific property within a collection (`className`). The index to delete is identified by `indexName` and must be one of `filterable`, `searchable`, or `rangeFilters` (with `rangeable` accepted as an alias for `rangeFilters`).", "operationId": "schema.objects.properties.delete", "x-serviceIds": [ "weaviate.local.manipulate.meta" ], "tags": [ "schema" ], "parameters": [ { "name": "className", "description": "The name of the collection (class) containing the property.", "in": "path", "required": true, "type": "string" }, { "name": "propertyName", "description": "The name of the property whose inverted index should be deleted.", "in": "path", "required": true, "type": "string" }, { "name": "indexName", "description": "The name of the inverted index to delete from the property. `rangeable` is accepted as a write-path alias for `rangeFilters`.", "in": "path", "required": true, "type": "string", "enum": [ "filterable", "searchable", "rangeFilters", "rangeable" ] } ], "responses": { "200": { "description": "Index deleted successfully." }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Invalid index, property or collection provided.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error occurred while deleting the index. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/schema/{className}/properties/{propertyName}/index/{indexName}/rebuild": { "post": { "summary": "Rebuild a property's inverted index with unchanged configuration", "description": "Rebuilds the inverted index from the stored objects with its current configuration (repair / format refresh). No request body. Index-mutating work is asynchronous: a `202` with a task ID is returned. `indexName` accepts `rangeable` as an alias for `rangeFilters`.", "operationId": "schema.objects.index.rebuild", "x-serviceIds": [ "weaviate.local.manipulate.meta" ], "tags": [ "schema" ], "parameters": [ { "name": "className", "description": "The name of the collection (class) containing the property.", "in": "path", "required": true, "type": "string" }, { "name": "propertyName", "description": "The name of the property whose inverted index should be rebuilt.", "in": "path", "required": true, "type": "string" }, { "name": "indexName", "description": "The inverted index type to rebuild. `rangeable` is accepted as a write-path alias for `rangeFilters`.", "in": "path", "required": true, "type": "string", "enum": [ "filterable", "searchable", "rangeFilters", "rangeable" ] }, { "name": "tenants", "in": "query", "required": false, "type": "array", "items": { "type": "string" }, "description": "Tenant names to target. Allowed for all index types on multi-tenant collections (rebuilds are format-only). Omit to target all tenants." } ], "responses": { "202": { "description": "Reindex task submitted.", "schema": { "$ref": "#/definitions/IndexUpdateResponse" } }, "400": { "description": "Validation failure; the message carries an actionable hint.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Unknown collection or property.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "409": { "description": "Conflicting in-flight reindex task; the message names the offending task ID.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Invalid `indexName` path value.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "429": { "description": "Per-collection cap of concurrent active reindex tasks reached.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error occurred.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "503": { "description": "Cluster service unavailable, or an in-flight task's payload cannot be parsed so conflict-freedom cannot be proven.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/schema/{className}/properties/{propertyName}/index/{indexName}/cancel": { "post": { "summary": "Cancel the in-flight reindex task on a property's inverted index", "description": "Cancels the in-flight reindex task targeting this property's index. No request body. Idempotent: succeeds whether or not a task was in flight (a `202` with `{\"status\":\"NO_OP\"}` is returned when there is nothing to cancel). `indexName` accepts `rangeable` as an alias for `rangeFilters`.", "operationId": "schema.objects.index.cancel", "x-serviceIds": [ "weaviate.local.manipulate.meta" ], "tags": [ "schema" ], "parameters": [ { "name": "className", "description": "The name of the collection (class) containing the property.", "in": "path", "required": true, "type": "string" }, { "name": "propertyName", "description": "The name of the property whose reindex task should be cancelled.", "in": "path", "required": true, "type": "string" }, { "name": "indexName", "description": "The inverted index type whose in-flight task should be cancelled. `rangeable` is accepted as a write-path alias for `rangeFilters`.", "in": "path", "required": true, "type": "string", "enum": [ "filterable", "searchable", "rangeFilters", "rangeable" ] } ], "responses": { "202": { "description": "Cancellation processed. Body carries `{\"status\":\"CANCELLED\",\"taskId\":...}` when a live task was cancelled, or `{\"status\":\"NO_OP\"}` when there was nothing to cancel.", "schema": { "$ref": "#/definitions/IndexUpdateResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Unknown collection or property. \"Nothing to cancel\" is NOT a 404 — it returns 202 with status NO_OP.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Invalid `indexName` path value.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error occurred.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "503": { "description": "Cluster service unavailable.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/schema/{className}/properties/{propertyName}/tokenize": { "post": { "summary": "Tokenize text using a property's configuration", "description": "Tokenizes the provided text using the tokenization method configured for the specified property. This endpoint automatically applies the property's tokenization setting and the collection's stopword configuration, making it useful for understanding exactly how text will be processed for a given property during indexing and querying.", "operationId": "schema.objects.properties.tokenize", "x-serviceIds": [ "weaviate.local.query.meta" ], "tags": [ "schema" ], "parameters": [ { "name": "className", "description": "The name of the collection (class) containing the property.", "in": "path", "required": true, "type": "string" }, { "name": "propertyName", "description": "The name of the property whose tokenization configuration should be used.", "in": "path", "required": true, "type": "string" }, { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/PropertyTokenizeRequest" } } ], "responses": { "200": { "description": "Successfully tokenized the text using the property's configuration.", "schema": { "$ref": "#/definitions/TokenizeResponse" } }, "400": { "description": "Invalid request body, missing required fields, or property does not have tokenization configured." }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Collection or property not found." }, "422": { "description": "Validation error, such as invalid class or property configuration for tokenization.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Unexpected server error while tokenizing the text.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/schema/{className}/vectors/{vectorIndexName}/index": { "delete": { "summary": "Delete a collection's vector index.", "description": "Deletes a specific vector index within a collection (`className`). The vector index to delete is identified by `vectorIndexName`.", "operationId": "schema.objects.vectors.delete", "x-serviceIds": [ "weaviate.local.manipulate", "weaviate.local.manipulate.meta" ], "tags": [ "schema" ], "parameters": [ { "name": "className", "description": "The name of the collection (class) containing the property.", "in": "path", "required": true, "type": "string" }, { "name": "vectorIndexName", "description": "The name of the vector index.", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Vector index deleted successfully." }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Invalid vector index or collection provided.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error occurred while deleting the vector index. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/schema/{className}/shards": { "get": { "summary": "Get the shards status of a collection", "description": "Retrieves the status of all shards associated with the specified collection (`className`). For multi-tenant collections, use the `tenant` query parameter to retrieve status for a specific tenant's shards.", "operationId": "schema.objects.shards.get", "x-serviceIds": [ "weaviate.local.get.meta" ], "tags": [ "schema" ], "parameters": [ { "name": "className", "description": "The name of the collection (class) whose shards to query.", "in": "path", "required": true, "type": "string" }, { "name": "tenant", "description": "The name of the tenant for which to retrieve shard statuses (only applicable for multi-tenant collections).", "in": "query", "type": "string" } ], "responses": { "200": { "description": "Shard statuses retrieved successfully.", "schema": { "$ref": "#/definitions/ShardStatusList" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Collection not found.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error occurred while retrieving shard statuses. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/schema/{className}/shards/{shardName}": { "put": { "summary": "Update a shard status", "description": "Updates the status of a specific shard within a collection (e.g., sets it to `READY` or `READONLY`). This is typically used after resolving an underlying issue (like disk space) that caused a shard to become non-operational. There is also a convenience function in each client to set the status of all shards of a collection.", "operationId": "schema.objects.shards.update", "x-serviceIds": [ "weaviate.local.manipulate.meta" ], "tags": [ "schema" ], "parameters": [ { "name": "className", "description": "The name of the collection (class) containing the shard.", "in": "path", "required": true, "type": "string" }, { "name": "shardName", "description": "The name of the shard to update.", "in": "path", "required": true, "type": "string" }, { "in": "body", "name": "body", "description": "The shard status object containing the desired new status.", "required": true, "schema": { "$ref": "#/definitions/ShardStatus" } } ], "responses": { "200": { "description": "Shard status updated successfully.", "schema": { "$ref": "#/definitions/ShardStatus" } }, "422": { "description": "Invalid update attempt", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Collection or shard not found.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error occurred while updating the shard status. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/schema/{className}/tenants": { "post": { "summary": "Create a new tenant", "description": "Creates one or more new tenants for a specified collection (`className`). Multi-tenancy must be enabled for the collection via its definition.", "operationId": "tenants.create", "tags": [ "schema" ], "parameters": [ { "name": "className", "description": "The name of the multi-tenant enabled collection (class).", "in": "path", "required": true, "type": "string" }, { "in": "body", "name": "body", "description": "An array of tenant objects to create.", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/Tenant" } } } ], "responses": { "200": { "description": "Tenants created successfully.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Tenant" } } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Invalid request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "429": { "description": "The configured tenant-per-collection usage limit was exceeded. See `UsageLimitExceededResponse` for the limit value.", "schema": { "$ref": "#/definitions/UsageLimitExceededResponse" } }, "500": { "description": "An error occurred while creating tenants. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } }, "put": { "summary": "Update a tenant", "description": "Updates the activity status (e.g., `ACTIVE`, `INACTIVE`, etc.) of one or more specified tenants within a collection (`className`).", "operationId": "tenants.update", "tags": [ "schema" ], "parameters": [ { "name": "className", "description": "The name of the collection (class) containing the tenants.", "in": "path", "required": true, "type": "string" }, { "in": "body", "name": "body", "description": "An array of tenant objects specifying the tenants to update and their desired new status.", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/Tenant" } } } ], "responses": { "200": { "description": "Tenant statuses updated successfully.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Tenant" } } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Invalid update request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error occurred while updating tenants. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } }, "delete": { "summary": "Delete tenants", "description": "Deletes one or more specified tenants from a collection (`className`). WARNING: This action permanently deletes all data associated with the specified tenants.", "operationId": "tenants.delete", "tags": [ "schema" ], "parameters": [ { "name": "className", "description": "The name of the collection (class) from which to delete tenants.", "in": "path", "required": true, "type": "string" }, { "in": "body", "name": "tenants", "description": "An array of tenant names to delete.", "required": true, "schema": { "type": "array", "items": { "type": "string", "description": "Name of a tenant to delete." } } } ], "responses": { "200": { "description": "Tenants deleted successfully." }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Invalid request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error occurred while deleting tenants. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } }, "get": { "summary": "Get the list of tenants", "description": "Retrieves a list of all tenants currently associated with the specified collection.", "operationId": "tenants.get", "tags": [ "schema" ], "parameters": [ { "name": "className", "description": "The name of the collection (class) whose tenants to list.", "in": "path", "required": true, "type": "string" }, { "name": "consistency", "in": "header", "required": false, "default": true, "type": "boolean", "description": "If true, the request is proxied to the cluster leader to ensure strong schema consistency. Default is true." } ], "responses": { "200": { "description": "Successfully retrieved tenants.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Tenant" } } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Invalid request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error occurred while listing tenants. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/schema/{className}/tenants/{tenantName}": { "head": { "summary": "Check if a tenant exists", "description": "Checks for the existence of a specific tenant within the given collection (`className`).", "operationId": "tenant.exists", "tags": [ "schema" ], "parameters": [ { "name": "className", "description": "The name of the collection (class) to check within.", "in": "path", "required": true, "type": "string" }, { "name": "tenantName", "description": "The name of the tenant to check for.", "in": "path", "required": true, "type": "string" }, { "name": "consistency", "in": "header", "required": false, "default": true, "type": "boolean", "description": "If true, the request is proxied to the cluster leader to ensure strong schema consistency. Default is true." } ], "responses": { "200": { "description": "The tenant exists in the specified collection." }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Tenant or collection not found." }, "422": { "description": "Invalid request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error occurred during the check. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } }, "get": { "summary": "Get a specific tenant", "description": "Retrieves details about a specific tenant within the given collection (`className`), such as its current activity status.", "operationId": "tenants.get.one", "tags": [ "schema" ], "parameters": [ { "name": "className", "description": "The name of the collection (class) containing the tenant.", "in": "path", "required": true, "type": "string" }, { "name": "tenantName", "description": "The name of the tenant to retrieve.", "in": "path", "required": true, "type": "string" }, { "name": "consistency", "in": "header", "required": false, "default": true, "type": "boolean", "description": "If true, the request is proxied to the cluster leader to ensure strong schema consistency. Default is true." } ], "responses": { "200": { "description": "Successfully retrieved tenant details.", "schema": { "$ref": "#/definitions/Tenant" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Tenant or collection not found." }, "422": { "description": "Invalid request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error occurred while retrieving the tenant. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/aliases": { "get": { "summary": "List aliases", "description": "Retrieve a list of all aliases in the system. Results can be filtered by specifying a collection (class) name to get aliases for a specific collection only.", "operationId": "aliases.get", "tags": [ "schema" ], "parameters": [ { "name": "class", "description": "Optional filter to retrieve aliases for a specific collection (class) only. If not provided, returns all aliases.", "in": "query", "required": false, "type": "string" } ], "responses": { "200": { "description": "Successfully retrieved the list of aliases", "schema": { "$ref": "#/definitions/AliasResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Invalid collection (class) parameter provided", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } }, "post": { "summary": "Create a new alias", "description": "Create a new alias mapping between an alias name and a collection (class). The alias acts as an alternative name for accessing the collection.", "operationId": "aliases.create", "tags": [ "schema" ], "parameters": [ { "in": "body", "name": "body", "required": true, "schema": { "$ref": "#/definitions/Alias" } } ], "responses": { "200": { "description": "Successfully created a new alias for the specified collection (class)", "schema": { "$ref": "#/definitions/Alias" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Invalid create alias request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/aliases/{aliasName}": { "get": { "summary": "Get an alias", "description": "Retrieve details about a specific alias by its name, including which collection (class) it points to.", "operationId": "aliases.get.alias", "tags": [ "schema" ], "parameters": [ { "name": "aliasName", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Successfully retrieved the alias details.", "schema": { "$ref": "#/definitions/Alias" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Not Found - Alias does not exist", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Invalid alias name provided.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } }, "put": { "summary": "Update an alias", "description": "Update an existing alias to point to a different collection (class). This allows you to redirect an alias from one collection to another without changing the alias name.", "operationId": "aliases.update", "tags": [ "schema" ], "parameters": [ { "name": "aliasName", "in": "path", "required": true, "type": "string" }, { "in": "body", "name": "body", "required": true, "schema": { "type": "object", "properties": { "class": { "description": "The new collection (class) that the alias should point to.", "type": "string" } } } } ], "responses": { "200": { "description": "Successfully updated the alias to point to the new collection (class).", "schema": { "$ref": "#/definitions/Alias" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Not Found - Alias does not exist", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Invalid update alias request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } }, "delete": { "summary": "Delete an alias", "description": "Remove an existing alias from the system. This will delete the alias mapping but will not affect the underlying collection (class).", "operationId": "aliases.delete", "tags": [ "schema" ], "parameters": [ { "name": "aliasName", "in": "path", "required": true, "type": "string" } ], "responses": { "204": { "description": "Successfully deleted the alias." }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Not Found - Alias does not exist", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Invalid delete alias request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/namespaces": { "get": { "summary": "List namespaces", "description": "Retrieve the list of all namespaces the caller has permission to see. Callers without any applicable `manage_namespaces` permission receive an empty list (never 403).", "operationId": "listNamespaces", "tags": [ "namespaces" ], "responses": { "200": { "description": "Successfully retrieved the list of namespaces (possibly empty).", "schema": { "$ref": "#/definitions/NamespaceListResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "404": { "description": "Not Found - The namespaces feature is not enabled on this cluster.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "The request syntax is correct, but the server couldn't process it.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/namespaces/{namespace_id}": { "post": { "summary": "Create a new namespace", "description": "Create a new cluster-level namespace with the given name. Names must contain only lowercase letters, digits, and hyphens, must start and end with a letter or digit, must be 3-36 characters long, and must not be a reserved name.", "operationId": "createNamespace", "tags": [ "namespaces" ], "parameters": [ { "description": "The name of the namespace. Must start with a lowercase letter, contain only lowercase letters and digits, length 3-36, and not be a reserved name.", "in": "path", "name": "namespace_id", "required": true, "type": "string" }, { "description": "Optional body. When omitted, `home_node` is picked automatically.", "in": "body", "name": "body", "schema": { "$ref": "#/definitions/NamespaceCreateRequest" } } ], "responses": { "201": { "description": "Namespace created successfully.", "schema": { "$ref": "#/definitions/Namespace" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Not Found - The namespaces feature is not enabled on this cluster.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "409": { "description": "A namespace with the specified name already exists, or a namespace with the same name is currently being deleted. Differentiate by reading the human-readable message in the error payload.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues (e.g. invalid name format or reserved name).", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } }, "get": { "summary": "Get a namespace", "description": "Retrieve details about a specific namespace by its name.", "operationId": "getNamespace", "tags": [ "namespaces" ], "parameters": [ { "description": "The name of the namespace.", "in": "path", "name": "namespace_id", "required": true, "type": "string" } ], "responses": { "200": { "description": "Successfully retrieved the namespace.", "schema": { "$ref": "#/definitions/Namespace" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Not Found - Namespace does not exist, or the namespaces feature is not enabled on this cluster.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues (e.g. invalid name format or reserved name).", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } }, "put": { "summary": "Update a namespace", "description": "Update a namespace's `home_node`. The new value applies to future placement decisions only (new collection create, new tenant create, tenant reactivation). Existing live shards are not moved.", "operationId": "updateNamespace", "tags": [ "namespaces" ], "parameters": [ { "description": "The name of the namespace.", "in": "path", "name": "namespace_id", "required": true, "type": "string" }, { "description": "Required body. `home_node` is the new placement target.", "in": "body", "name": "body", "required": true, "schema": { "$ref": "#/definitions/NamespaceUpdateRequest" } } ], "responses": { "200": { "description": "Namespace updated successfully.", "schema": { "$ref": "#/definitions/Namespace" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Not Found - Namespace does not exist, or the namespaces feature is not enabled on this cluster.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues (e.g. invalid name format, reserved name, unknown home_node, or the namespace being in the `deleting` state).", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } }, "delete": { "summary": "Delete a namespace", "description": "Mark a namespace for deletion. The endpoint is asynchronous: the namespace is flipped to the \"deleting\" state, which stops its dynamic users from authenticating; their rows, along with classes and aliases, are reclaimed by the leader on a periodic cleanup tick. Repeated calls while the namespace is still in the \"deleting\" state are idempotent and return 202.", "operationId": "deleteNamespace", "tags": [ "namespaces" ], "parameters": [ { "description": "The name of the namespace.", "in": "path", "name": "namespace_id", "required": true, "type": "string" } ], "responses": { "202": { "description": "The namespace has been marked for deletion. Cleanup of its classes, aliases, and users completes asynchronously." }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Not Found - Namespace does not exist, or the namespaces feature is not enabled on this cluster.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues (e.g. invalid name format or reserved name).", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/namespaces/{namespace_id}/suspend": { "post": { "summary": "Suspend a namespace", "description": "Move a namespace to the \"suspended\" state. Suspending stops the namespace's users from authenticating and blocks the creation of new classes, aliases, users, roles, and role assignments, but retains the namespace and everything it owns. Repeated calls against an already-suspended namespace are idempotent and return 202. Use the resume endpoint to return it to \"active\".", "operationId": "suspendNamespace", "tags": [ "namespaces" ], "parameters": [ { "description": "The name of the namespace.", "in": "path", "name": "namespace_id", "required": true, "type": "string" } ], "responses": { "202": { "description": "The state change is committed and the namespace is suspended." }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Not Found - Namespace does not exist, or the namespaces feature is not enabled on this cluster.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "409": { "description": "Another state change was applied to this namespace while this request was in flight, so it was not applied. Re-read the namespace and retry if the change is still wanted.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues (e.g. invalid name format, reserved name, or a namespace that is being deleted).", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "503": { "description": "No cluster leader was reachable. The state change may or may not have been applied; re-read the namespace before retrying.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/namespaces/{namespace_id}/resume": { "post": { "summary": "Resume a namespace", "description": "Return a suspended namespace to the \"active\" state, so its dynamic users authenticate again and its resources accept writes. Repeated calls against an already-active namespace are idempotent and return 202.", "operationId": "resumeNamespace", "tags": [ "namespaces" ], "parameters": [ { "description": "The name of the namespace.", "in": "path", "name": "namespace_id", "required": true, "type": "string" } ], "responses": { "202": { "description": "The state change is committed and the namespace is active." }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Not Found - Namespace does not exist, or the namespaces feature is not enabled on this cluster.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "409": { "description": "Another state change was applied to this namespace while this request was in flight, so it was not applied. Re-read the namespace and retry if the change is still wanted.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "The request syntax is correct, but the server couldn't process it due to semantic issues (e.g. invalid name format, reserved name, or a namespace that is being deleted).", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "503": { "description": "No cluster leader was reachable. The state change may or may not have been applied; re-read the namespace before retrying.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/backups/{backend}": { "post": { "summary": "Create a backup", "description": "Initiates the creation of a backup for specified collections on a designated backend storage.\n\nNotes:\n- Backups are compressed using gzip by default.\n- Weaviate remains operational during the backup process.", "operationId": "backups.create", "x-serviceIds": [ "weaviate.local.backup" ], "tags": [ "backups" ], "parameters": [ { "name": "backend", "in": "path", "required": true, "type": "string", "description": "Specifies the backend storage system where the backup will be stored (e.g., `filesystem`, `gcs`, `s3`, `azure`)." }, { "in": "body", "name": "body", "description": "Details of the backup request, including the backup ID and collections to include or exclude.", "required": true, "schema": { "$ref": "#/definitions/BackupCreateRequest" } } ], "responses": { "200": { "description": "Backup creation process initiated successfully. Check the status endpoint for progress.", "schema": { "$ref": "#/definitions/BackupCreateResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Invalid backup creation request. Check the request body and backend configuration.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An internal server error occurred during backup initiation. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } }, "get": { "summary": "List all created backups", "description": "List all created backups IDs, Status", "operationId": "backups.list", "x-serviceIds": [ "weaviate.local.backup" ], "tags": [ "backups" ], "parameters": [ { "name": "backend", "in": "path", "required": true, "type": "string", "description": "Specifies the backend storage system to list backups from (e.g., `filesystem`, `gcs`, `s3`, `azure`)." }, { "name": "order", "in": "query", "required": false, "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Order of returned list of backups based on creation time. (asc or desc)" } ], "responses": { "200": { "description": "Successfully retrieved the list of backups in progress.", "schema": { "$ref": "#/definitions/BackupListResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Invalid request to list backups.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An internal server error occurred while listing backups. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/backups/{backend}/{id}": { "get": { "summary": "Get backup creation status", "description": "Checks the status of a specific backup creation process identified by its ID on the specified backend.\n\nClient libraries often provide a 'wait for completion' feature that polls this endpoint automatically. Use this endpoint for manual status checks or if 'wait for completion' is disabled.", "operationId": "backups.create.status", "x-serviceIds": [ "weaviate.local.backup" ], "tags": [ "backups" ], "parameters": [ { "name": "backend", "in": "path", "required": true, "type": "string", "description": "Specifies the backend storage system where the backup resides (e.g., `filesystem`, `gcs`, `s3`, `azure`)." }, { "name": "id", "in": "path", "required": true, "type": "string", "description": "The unique identifier of the backup. Must be URL-safe and compatible with filesystem paths (only lowercase, numbers, underscore, minus characters allowed)." }, { "name": "bucket", "in": "query", "required": false, "type": "string", "description": "Optional: Specifies the bucket, container, or volume name if required by the backend." }, { "name": "path", "in": "query", "required": false, "type": "string", "description": "Optional: Specifies the path within the bucket/container/volume if the backup is not at the root." } ], "responses": { "200": { "description": "Successfully retrieved the status of the backup creation process.", "schema": { "$ref": "#/definitions/BackupCreateStatusResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Backup not found on the specified backend with the given ID.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Invalid request to check backup creation status.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An internal server error occurred while checking backup status. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } }, "delete": { "summary": "Cancel a backup", "description": "Cancels an ongoing backup operation identified by its ID.", "operationId": "backups.cancel", "x-serviceIds": [ "weaviate.local.backup" ], "tags": [ "backups" ], "parameters": [ { "name": "backend", "in": "path", "required": true, "type": "string", "description": "Specifies the backend storage system where the backup resides (e.g., `filesystem`, `gcs`, `s3`, `azure`)." }, { "name": "id", "in": "path", "required": true, "type": "string", "description": "The unique identifier of the backup to cancel. Must be URL-safe and compatible with filesystem paths (only lowercase, numbers, underscore, minus characters allowed)." }, { "name": "bucket", "in": "query", "required": false, "type": "string", "description": "Optional: Specifies the bucket, container, or volume name if required by the backend." }, { "name": "path", "in": "query", "required": false, "type": "string", "description": "Optional: Specifies the path within the bucket/container/volume if the backup is not at the root." } ], "responses": { "204": { "description": "Backup canceled successfully." }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Invalid backup cancellation request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An internal server error occurred during backup cancellation. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/backups/{backend}/{id}/restore": { "post": { "summary": "Restore from a backup", "description": "Initiates the restoration of collections from a specified backup located on a designated backend.\n\nRequirements:\n- Target cluster must have the same number of nodes as the source cluster where the backup was created.\n- Collections included in the restore must not already exist on the target cluster.\n- Node names must match between the backup and the target cluster.", "operationId": "backups.restore", "x-serviceIds": [ "weaviate.local.backup" ], "tags": [ "backups" ], "parameters": [ { "name": "backend", "in": "path", "required": true, "type": "string", "description": "Specifies the backend storage system where the backup resides (e.g., `filesystem`, `gcs`, `s3`, `azure`)." }, { "name": "id", "in": "path", "required": true, "type": "string", "description": "The unique identifier of the backup to restore from. Must be URL-safe and compatible with filesystem paths (only lowercase, numbers, underscore, minus characters allowed)." }, { "in": "body", "name": "body", "description": "Details of the restore request, including collections to include or exclude and node mapping if necessary.", "required": true, "schema": { "$ref": "#/definitions/BackupRestoreRequest" } } ], "responses": { "200": { "description": "Backup restoration process initiated successfully. Check the status endpoint for progress.", "schema": { "$ref": "#/definitions/BackupRestoreResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Backup not found on the specified backend with the given ID.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Invalid backup restoration request. Check requirements and request body.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An internal server error occurred during restore initiation. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } }, "get": { "summary": "Get backup restoration status", "description": "Checks the status of a specific backup restoration process identified by the backup ID on the specified backend.\n\nClient libraries often provide a 'wait for completion' feature that polls this endpoint automatically. Use this endpoint for manual status checks or if 'wait for completion' is disabled.", "operationId": "backups.restore.status", "x-serviceIds": [ "weaviate.local.backup" ], "tags": [ "backups" ], "parameters": [ { "name": "backend", "in": "path", "required": true, "type": "string", "description": "Specifies the backend storage system where the backup resides (e.g., `filesystem`, `gcs`, `s3`, `azure`)." }, { "name": "id", "in": "path", "required": true, "type": "string", "description": "The unique identifier of the backup being restored. Must be URL-safe and compatible with filesystem paths (only lowercase, numbers, underscore, minus characters allowed)." }, { "name": "bucket", "in": "query", "required": false, "type": "string", "description": "Optional: Specifies the bucket, container, or volume name if required by the backend." }, { "name": "path", "in": "query", "required": false, "type": "string", "description": "Optional: Specifies the path within the bucket." } ], "responses": { "200": { "description": "Successfully retrieved the status of the backup restoration process.", "schema": { "$ref": "#/definitions/BackupRestoreStatusResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Backup not found on the specified backend with the given ID.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An internal server error occurred while checking restore status. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } }, "delete": { "summary": "Cancel a backup restoration", "description": "Cancels an ongoing backup restoration process identified by its ID on the specified backend storage.", "operationId": "backups.restore.cancel", "x-serviceIds": [ "weaviate.local.backup" ], "tags": [ "backups" ], "parameters": [ { "name": "backend", "in": "path", "required": true, "type": "string", "description": "Specifies the backend storage system where the backup resides (e.g., `filesystem`, `gcs`, `s3`, `azure`)." }, { "name": "id", "in": "path", "required": true, "type": "string", "description": "The unique identifier of the backup restoration to cancel. Must be URL-safe and compatible with filesystem paths (only lowercase, numbers, underscore, minus characters allowed)." }, { "name": "bucket", "in": "query", "required": false, "type": "string", "description": "Optional: Specifies the bucket, container, or volume name if required by the backend." }, { "name": "path", "in": "query", "required": false, "type": "string", "description": "Optional: Specifies the path within the bucket/container/volume if the backup is not at the root." } ], "responses": { "204": { "description": "Backup restoration cancelled successfully." }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Invalid backup restoration cancellation request.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An internal server error occurred during backup restoration cancellation. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/export/{backend}": { "post": { "summary": "Start a new export", "description": "Initiates an export operation on the specified backend storage (S3, GCS, Azure, or filesystem). The output format is controlled by the required 'file_format' field in the request body (currently only 'parquet' is supported). Each collection is exported to a separate file.", "operationId": "export.create", "x-serviceIds": [ "weaviate.local.export.create" ], "tags": [ "export" ], "parameters": [ { "name": "backend", "in": "path", "required": true, "type": "string", "description": "The backend storage system to use for the export (e.g., `filesystem`, `gcs`, `s3`, `azure`)." }, { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/ExportCreateRequest" } } ], "responses": { "200": { "description": "Successfully started export operation", "schema": { "$ref": "#/definitions/ExportCreateResponse" } }, "401": { "description": "Unauthorized or invalid credentials" }, "403": { "description": "Forbidden - insufficient permissions", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "409": { "description": "Export already exists or another export is already in progress", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Invalid export request", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error occurred while starting export", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/export/{backend}/{id}": { "get": { "summary": "Get export status", "description": "Retrieves the current status of an export operation, including progress for each collection being exported.", "operationId": "export.status", "x-serviceIds": [ "weaviate.local.export.status" ], "tags": [ "export" ], "parameters": [ { "name": "backend", "in": "path", "required": true, "type": "string", "description": "The backend storage system where the export is stored." }, { "name": "id", "in": "path", "required": true, "type": "string", "description": "The unique identifier of the export." } ], "responses": { "200": { "description": "Successfully retrieved export status", "schema": { "$ref": "#/definitions/ExportStatusResponse" } }, "401": { "description": "Unauthorized or invalid credentials" }, "403": { "description": "Forbidden - insufficient permissions", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Export not found", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Invalid request (e.g., unsupported backend)", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error occurred while retrieving export status", "schema": { "$ref": "#/definitions/ErrorResponse" } } } }, "delete": { "summary": "Cancel an export", "description": "Cancels an ongoing export operation identified by its ID.", "operationId": "export.cancel", "x-serviceIds": [ "weaviate.local.export.cancel" ], "tags": [ "export" ], "parameters": [ { "name": "backend", "in": "path", "required": true, "type": "string", "description": "The backend storage system where the export is stored." }, { "name": "id", "in": "path", "required": true, "type": "string", "description": "The unique identifier of the export to cancel." } ], "responses": { "204": { "description": "Export cancelled successfully." }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden - insufficient permissions", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Export not found", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "409": { "description": "Export has already finished and cannot be cancelled", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Invalid request (e.g., unsupported backend)", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error occurred while cancelling export", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/cluster/statistics": { "get": { "summary": "Get cluster statistics", "description": "Provides statistics about the internal Raft consensus protocol state for the Weaviate cluster.", "operationId": "cluster.get.statistics", "x-serviceIds": [ "weaviate.cluster.statistics.get" ], "tags": [ "cluster" ], "responses": { "200": { "description": "Successfully retrieved Raft cluster statistics.", "schema": { "$ref": "#/definitions/ClusterStatisticsResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Invalid request for cluster statistics.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An internal server error occurred while retrieving cluster statistics. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/nodes": { "get": { "summary": "Get node status", "description": "Retrieves status information about all nodes in the cluster. Use the `output` query parameter to control the level of detail.", "operationId": "nodes.get", "x-serviceIds": [ "weaviate.nodes.status.get" ], "tags": [ "nodes" ], "parameters": [ { "$ref": "#/parameters/CommonOutputVerbosityParameterQuery" } ], "responses": { "200": { "description": "Successfully retrieved the status for all nodes.", "schema": { "$ref": "#/definitions/NodesStatusResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Not Found.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Invalid request for node status.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An internal server error occurred while retrieving node status. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/nodes/{className}": { "get": { "summary": "Get node status by collection", "description": "Retrieves status information only for the nodes that host shards for the specified collection (`className`). Use the `output` query parameter to control the level of detail.", "operationId": "nodes.get.class", "x-serviceIds": [ "weaviate.nodes.status.get.class" ], "tags": [ "nodes" ], "parameters": [ { "name": "className", "description": "The name of the collection (class) for which to retrieve node status.", "in": "path", "required": true, "type": "string" }, { "name": "shardName", "in": "query", "required": false, "type": "string" }, { "$ref": "#/parameters/CommonOutputVerbosityParameterQuery" } ], "responses": { "200": { "description": "Successfully retrieved the status for nodes relevant to the specified collection.", "schema": { "$ref": "#/definitions/NodesStatusResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Not Found.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Invalid request for node status.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An internal server error occurred while retrieving node status for the collection. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/tasks": { "get": { "summary": "Lists all distributed tasks in the cluster", "operationId": "distributedTasks.get", "x-serviceIds": [ "weaviate.distributedTasks.get" ], "tags": [ "distributedTasks" ], "responses": { "200": { "description": "Distributed tasks successfully returned.", "schema": { "$ref": "#/definitions/DistributedTasks" } }, "403": { "description": "Unauthorized or invalid credentials.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An internal server error occurred while retrieving distributed tasks. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/classifications/": { "post": { "summary": "Start a classification", "description": "Initiates a background classification task based on the provided parameters. Use the GET /classifications/{id} endpoint to monitor the status and retrieve results.", "operationId": "classifications.post", "x-serviceIds": [ "weaviate.classifications.post" ], "parameters": [ { "description": "Configuration parameters for the classification task, including type, target properties, and training data references.", "in": "body", "schema": { "$ref": "#/definitions/Classification" }, "name": "params", "required": true } ], "responses": { "201": { "description": "Classification task successfully initiated. The response body contains the classification details including its ID.", "schema": { "$ref": "#/definitions/Classification" } }, "400": { "description": "Invalid request body or parameters.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "410": { "description": "Endpoint not available in the current cluster configuration.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An internal server error occurred while starting the classification task. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "tags": [ "classifications" ] } }, "/classifications/{id}": { "get": { "summary": "Get classification status", "description": "Retrieves the status, metadata, and results (if completed) of a classification task identified by its unique ID.", "operationId": "classifications.get", "x-serviceIds": [ "weaviate.classifications.get" ], "parameters": [ { "description": "The unique identifier (UUID) of the classification task.", "in": "path", "type": "string", "name": "id", "required": true } ], "responses": { "200": { "description": "Successfully retrieved the classification details.", "schema": { "$ref": "#/definitions/Classification" } }, "401": { "description": "Unauthorized or invalid credentials." }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Classification with the given ID not found." }, "410": { "description": "Endpoint not available in the current cluster configuration.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An internal server error occurred while retrieving the classification status. Check the ErrorResponse for details.", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "tags": [ "classifications" ] } }, "/mcp": { "post": { "description": "MCP Streamable HTTP endpoint. Handles JSON-RPC requests for tool discovery and invocation.", "tags": [ "mcp" ], "operationId": "mcp.post", "consumes": [ "application/json" ], "produces": [ "application/json", "text/event-stream" ], "responses": { "200": { "description": "JSON-RPC response or SSE stream" } } }, "get": { "description": "Opens an SSE stream for receiving MCP server-sent events.", "tags": [ "mcp" ], "operationId": "mcp.get", "produces": [ "text/event-stream" ], "responses": { "200": { "description": "SSE event stream" } } }, "delete": { "description": "Terminates an MCP session.", "tags": [ "mcp" ], "operationId": "mcp.delete", "responses": { "200": { "description": "Session terminated" } } } }, "/search/{collection}/near-text": { "post": { "summary": "Search a collection with near-text", "description": "Performs a semantic (near-text) search over the objects of a collection. The query text is vectorized server-side by the collection's vectorizer module and the closest objects are returned, each as an envelope of its `id`, the selected `properties`, the selected `references` and, when requested, its retrieval `metadata`.", "tags": [ "search" ], "operationId": "search.nearText", "consumes": [ "application/json" ], "parameters": [ { "name": "collection", "description": "The name (or alias) of the collection to search. A lowercase first letter is normalized to the canonical uppercase form.", "in": "path", "required": true, "type": "string" }, { "name": "body", "description": "The near-text search request.", "in": "body", "required": true, "schema": { "$ref": "#/definitions/SearchNearTextRequest" } } ], "responses": { "200": { "description": "Search performed successfully.", "schema": { "$ref": "#/definitions/SearchResponse" } }, "400": { "description": "An invalid parameter value (e.g. empty query, negative paging, unknown property) or an unparseable request body.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized or invalid credentials.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Unknown collection or tenant.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Either a request-schema violation (a missing required field such as `query`, or an invalid enum value), or a well-formed request that cannot run: no vectorizer module is configured for the collection, targetVector is missing on a multi-named-vector collection, certainty is used on a non-cosine index, a reserved (not yet supported) parameter is present, the tenant usage does not match the collection's multi-tenancy configuration, a where filter targets a property whose inverted index is disabled, or the experimental REST Search API is not enabled (set EXPERIMENTAL_REST_SEARCH_ENABLED=true).", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "429": { "description": "The server's query rate limit was reached; retry later.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "502": { "description": "The embedding provider failed to vectorize the query; the search cannot run.", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "503": { "description": "The server is in an operational mode that blocks searches (e.g. WRITE_ONLY); retry once the server returns to normal operation.", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } } }, "produces": [ "application/json" ], "schemes": [ "https" ], "security": [ {}, { "oidc": [] } ], "securityDefinitions": { "oidc": { "type": "oauth2", "description": "OIDC (OpenConnect ID - based on OAuth2)", "flow": "implicit", "authorizationUrl": "http://to-be-configured-in-the-application-config" } }, "swagger": "2.0", "tags": [ { "name": "root", "description": "The root of the API. Note the base url is `/v1`." }, { "name": "schema", "description": "Operations related to managing collections. In Weaviate, 'collections' (formerly called 'classes') store your data objects. Each collection has a definition that specifies its data structure (properties and their data types), vectorizer settings (how vectors are generated or managed), and indexing configuration (how data is indexed for efficient search). These endpoints allow you to create, retrieve, update, and delete collection definitions. For detailed usage and code examples on interacting with collections, see the documentation: [https://weaviate.io/developers/weaviate/manage-data/collections](https://weaviate.io/developers/weaviate/manage-data/collections)." }, { "name": "objects", "description": "Operations for managing individual data objects. Objects are the primary units of data stored within Weaviate collections. Each object conforms to the data schema definition of its parent collection, containing specific properties (data fields). Objects have one or multiple associated vector embeddings and can link to other objects via cross-references. These endpoints allow you to perform CRUD (Create, Read, Update, Delete) operations on individual data objects." }, { "name": "batch", "description": "Operations for performing actions on multiple data items (objects or references) in a single API request. Batch operations significantly improve performance and efficiency, especially for bulk data imports or large-scale deletions, by reducing network overhead compared to sending individual requests. These endpoints allow for creating multiple objects or deleting objects based on filters." }, { "name": "search", "description": "Operations for querying collections over REST. The near-text endpoint performs semantic vector search with server-side embedding of the query text; each result carries the object's `id`, the selected `properties`, the selected `references` and, when requested, its retrieval `metadata`." }, { "name": "backups", "description": "Operations related to creating and managing backups of Weaviate data. This feature allows you to create snapshots of your collections and store them on external storage backends such as cloud object storage (S3, GCS, Azure) or a shared filesystem. These endpoints enable you to initiate backup and restore processes, monitor their status, list available backups on a backend, and cancel ongoing backups. Backups are essential for disaster recovery, data migration, and maintaining point-in-time copies of your vector database." }, { "name": "meta", "description": "Retrieve information about the server such as the hostname, location, versions and modules." }, { "name": "cluster", "description": "Retrieve Raft cluster statistics and node health information for the Weaviate database." }, { "name": "nodes", "description": "Monitor node status, shard distribution, and resource statistics for the cluster or specific collections." }, { "name": "well-known", "description": "Standard discovery endpoints for health checks (liveness, readiness) and OpenID Connect configuration if [OIDC authentication](https://docs.weaviate.io/deploy/configuration/authentication#oidc-authentication) is enabled." }, { "name": "graphql", "description": "Query data using the GraphQL query language. See the [Weaviate GraphQL documentation](https://docs.weaviate.io/weaviate/api/graphql) for query syntax details." }, { "name": "export", "description": "Operations for exporting Weaviate data to external storage backends (S3, GCS, Azure, or filesystem). The output file format is specified via the 'file_format' field (currently only 'parquet' is supported). Exports provide a way to extract your vector data and object properties into a standardized columnar format for data analysis, archival, or migration. Each collection is exported to a separate file containing object IDs, vectors, properties, and metadata." }, { "name": "authz", "description": "Endpoints for managing Weaviate's Role-Based Access Control (RBAC) system. Access to Weaviate resources is granted through roles, which are collections of fine-grained permissions. \n\n**Permissions:** Define allowed actions (e.g., `read_data`, `create_collections`, `delete_users`) on specific resources. Resources can be specified broadly (e.g., all collections: `*`) or narrowly (e.g., a specific collection name, tenant pattern, user name, or role name).\n\n**Roles:** Are named sets of permissions. Managing roles involves creating roles with specific permissions, retrieving role definitions, deleting roles, and adding or removing permissions from existing roles.\n\n**Role assignment:** Roles grant their contained permissions to users or groups. These endpoints allow assigning roles to:\n* `db` users: Users managed directly by Weaviate via API or environment variables, authenticating with API keys.\n* `oidc` users: Users authenticated via an external OpenID Connect provider, managed externally but assigned roles within Weaviate.\n* OIDC `groups`: Users authenticated via OIDC who belong to a group automatically inherit roles assigned to that group.\n\nOperations also include revoking roles, checking if a role has a specific permission, listing roles assigned to a user, and listing users/groups assigned to a role. The authorization framework applies universally to both `db` and `oidc` users based on their assigned roles." }, { "name": "users", "description": "Endpoints for user account management in Weaviate. This includes operations specific to Weaviate-managed database users (`db` users), such as creation (which generates an API key), listing, deletion, activation/deactivation, and API key rotation. It also provides operations applicable to any authenticated user (`db` or `oidc`), like retrieving their own information (username and assigned roles).\n\n**User Types:**\n* **`db` users:** Managed entirely within Weaviate (creation, deletion, API keys). Use these endpoints for full lifecycle management.\n* **`oidc` users:** Authenticated via an external OpenID Connect provider. Their lifecycle (creation, credentials) is managed externally, but their role assignments *within Weaviate* are managed via the `authz` endpoints." }, { "name": "classifications", "description": "Perform classification operations." }, { "name": "replication", "description": "Operations related to managing data replication, including initiating and monitoring shard replica movements between nodes, querying current sharding states, and managing the lifecycle of replication tasks." }, { "name": "mcp", "description": "Model Context Protocol (MCP) endpoint. Provides tool discovery and invocation for LLM agents via the MCP Streamable HTTP transport. Check out the [Weaviate MCP server documentation](https://docs.weaviate.io/weaviate/configuration/mcp-server) for more info." }, { "name": "namespaces", "description": "Operations for managing cluster-level namespaces. Namespaces group resources under a common administrative unit. Access is gated by the operator-tier `manage_namespaces` action." } ] }