> ## Documentation Index
> Fetch the complete documentation index at: https://docs.conare.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a namespace

> Creates a namespace before its first write. Only a namespace with a sparse (SPLADE) index
needs this: a write creates a namespace without one. With `sparse`, every chunk written to it
also gets a learned-sparse vector (writes are slower: the sparse model encodes each chunk) and
its queries can use the `sparse` retriever; while the sparse model is off, writes to it answer
503. Idempotent; a namespace that exists with the other
index answers 409, as a namespace's index never changes. It is listed once it holds documents.




## OpenAPI

````yaml /api/openapi.yaml post /namespaces
openapi: 3.1.0
info:
  title: Conare API
  version: '1'
  summary: Store your data, keep it in sync, and return the right context to your AI.
  description: >
    Write documents into namespaces, query them with hybrid search, and connect
    apps that keep

    syncing into a namespace.


    Authenticate with an API key from conare.ai/console/keys:

    `Authorization: Bearer sk-conare-…`. Bodies are JSON with snake_case keys;
    timestamps are

    RFC 3339 strings. Every response carries `X-Request-Id`, and every error has
    the shape

    `{"error": {"code", "message", "request_id"}}`. A 429, and a 503 that clears
    on its own,

    carry `Retry-After` (seconds).


    Conare is also an MCP server at `https://api.conare.ai/mcp` (streamable
    HTTP, same bearer key)

    with the tools `search`, `fetch`, `save`, `delete` and `list_namespaces`.
  contact:
    name: Conare
    url: https://conare.ai
servers:
  - url: https://api.conare.ai
security:
  - apiKey: []
tags:
  - name: Namespaces
    description: >
      A namespace is a named set of documents, e.g. `docs` or `user-42`. It is
      created by its first

      write and exists while it holds documents: a namespace whose documents are
      all deleted is not

      listed, and querying or listing it answers 404 `namespace_not_found`, like
      a name never written.
  - name: Documents
    description: >-
      A document is `{ id, text, metadata }`. Conare chunks and embeds it.
      Writing the same id replaces it.
  - name: Query
    description: >-
      Hybrid search (vector and keyword) over one namespace, with an optional
      metadata filter, reranked.
  - name: Models
    description: The embedding and reranking models Conare searches with.
  - name: Sources
    description: >
      Apps connected to Conare. Each keeps syncing into one namespace. While
      sources are not

      available, every sources route answers 503 with code
      `sources_unavailable`.
  - name: Health
    description: Service health.
paths:
  /namespaces:
    post:
      tags:
        - Namespaces
      summary: Create a namespace
      description: >
        Creates a namespace before its first write. Only a namespace with a
        sparse (SPLADE) index

        needs this: a write creates a namespace without one. With `sparse`,
        every chunk written to it

        also gets a learned-sparse vector (writes are slower: the sparse model
        encodes each chunk) and

        its queries can use the `sparse` retriever; while the sparse model is
        off, writes to it answer

        503. Idempotent; a namespace that exists with the other

        index answers 409, as a namespace's index never changes. It is listed
        once it holds documents.
      operationId: createNamespace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  $ref: '#/components/schemas/NamespaceName'
                sparse:
                  type: boolean
                  default: false
                  description: Give the namespace a sparse index.
            example:
              name: docs
              sparse: true
      responses:
        '200':
          description: The namespace exists with this index.
          content:
            application/json:
              schema:
                type: object
                required:
                  - name
                  - sparse
                properties:
                  name:
                    $ref: '#/components/schemas/NamespaceName'
                  sparse:
                    type: boolean
              example:
                name: docs
                sparse: true
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '409':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
components:
  schemas:
    NamespaceName:
      type: string
      pattern: ^[a-z0-9][a-z0-9_-]{0,63}$
      description: 1-64 characters of `a-z 0-9 _ -`, starting with a letter or digit.
      examples:
        - docs
        - user-42
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - request_id
          properties:
            code:
              type: string
              description: >
                Stable and machine-readable. 400: `invalid_request`,
                `invalid_json`, `invalid_namespace`,

                `invalid_id`, `invalid_metadata`, `invalid_filter`,
                `invalid_cursor`. 401: `unauthorized`.

                403: `forbidden`. 404: `namespace_not_found`,
                `document_not_found`, `source_not_found`,

                `not_found`. 405: `method_not_allowed`. 413:
                `payload_too_large`. 429: `rate_limited`. 500: `internal_error`.

                502: `upstream_error`. 503: `unavailable`,
                `sources_unavailable`. 504: `timeout`.
            message:
              type: string
            request_id:
              type: string
  responses:
    Error:
      description: An error. `X-Request-Id` is also in the response headers.
      headers:
        X-Request-Id:
          schema:
            type: string
        Retry-After:
          description: >-
            On 429, and on a 503 that clears on its own, seconds to wait before
            retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: invalid_request
              message: text is required
              request_id: 7d0f4c1e-2b8a-4e39-9a61-3c5e8b2f9d04
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: sk-conare-…
      description: >-
        An API key from conare.ai/console/keys. It can read and write every
        namespace in its organization.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.