openapi: 3.0.3
info:
  title: Weaviate REST authz namespaces API
  description: '# Introduction<br/> Weaviate is an open source, AI-native vector database that helps developers create intuitive and reliable AI-powered applications. <br/> ### Base Path <br/>The 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. <br/> ### Questions? <br/>If 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/). <br/>### Issues? <br/>If 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). <br/>### Need more documentation? <br/>For a quickstart, code examples, concepts and more, please visit our [documentation page](https://docs.weaviate.io/weaviate).'
  version: 1.38.0-dev
servers:
- url: http://localhost:8080
  description: Local Weaviate instance
security:
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: namespaces
paths:
  /namespaces:
    get:
      summary: Weaviate 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).
      tags:
      - namespaces
      operationId: listNamespaces
      responses:
        '200':
          description: Successfully retrieved the list of namespaces (possibly empty).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NamespaceListResponse'
        '401':
          description: Unauthorized or invalid credentials.
        '404':
          description: Not Found - The namespaces feature is not enabled on this cluster.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: The request syntax is correct, but the server couldn't process it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 100
  /namespaces/{namespace_id}:
    post:
      summary: Weaviate Create A New Namespace
      description: Create a new cluster-level namespace with the given name. Names must start with a lowercase letter, contain only lowercase letters and digits, be 3-36 characters long, and must not be a reserved name.
      tags:
      - namespaces
      operationId: createNamespace
      parameters:
      - name: namespace_id
        in: path
        required: true
        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.
        schema:
          type: string
      responses:
        '201':
          description: Namespace created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Namespace'
        '401':
          description: Unauthorized or invalid credentials.
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found - The namespaces feature is not enabled on this cluster.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: A namespace with the specified name already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 100
    get:
      summary: Weaviate Get A Namespace
      description: Retrieve details about a specific namespace by its name.
      tags:
      - namespaces
      operationId: getNamespace
      parameters:
      - name: namespace_id
        in: path
        required: true
        description: The name of the namespace.
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved the namespace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Namespace'
        '401':
          description: Unauthorized or invalid credentials.
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found - Namespace does not exist, or the namespaces feature is not enabled on this cluster.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 100
    delete:
      summary: Weaviate Delete A Namespace
      description: Hard-delete a namespace by its name.
      tags:
      - namespaces
      operationId: deleteNamespace
      parameters:
      - name: namespace_id
        in: path
        required: true
        description: The name of the namespace.
        schema:
          type: string
      responses:
        '204':
          description: Successfully deleted.
        '401':
          description: Unauthorized or invalid credentials.
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found - Namespace does not exist, or the namespaces feature is not enabled on this cluster.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An error has occurred while trying to fulfill the request. Most likely the ErrorResponse will contain more information about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 100
components:
  schemas:
    NamespaceListResponse:
      type: array
      description: Response object containing a list of namespaces.
      items:
        $ref: '#/components/schemas/Namespace'
    ErrorResponse:
      type: object
      description: An error response returned by Weaviate endpoints.
      properties:
        error:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
    Namespace:
      type: object
      description: A cluster-level namespace used to group resources under a common administrative unit. Namespace names must start with a lowercase letter, contain only lowercase letters and digits, be 3-36 characters long, and must not be a reserved name.
      properties:
        name:
          type: string
          description: The unique name of the namespace.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: API key authentication
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OIDC/JWT bearer authentication