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

# Create Share

> Enables you to make an AI agent available to the users who has access to a shared key. 

Ideal for integrating AI agents into public-facing websites where user authentication isn't required,
such as landing pages, help centers, or public knowledge bases. This allows website visitors to
interact with your AI agent without needing to create an account or log in. The shared key will be stored in the website.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/public-sharing/
openapi: 3.1.0
info:
  title: Verbex Platform API
  description: API for managing AI agents, calls, phone numbers, and more.
  version: 1.0.0
servers: []
security: []
tags:
  - name: Knowledge Bases
    description: >-
      Create and manage knowledge bases, ingest documents into them, and search
      them semantically.


      **Authentication.** Every request carries a bearer token: `Authorization:
      Bearer <API_TOKEN>`. That is the only credential a client sends. The
      gateway resolves your identity from it and injects the tenant headers the
      service reads internally, so clients never send `x-user-org-id` or
      `x-verbex-id` themselves.


      **Tenancy is enforced on every route.** A knowledge base belongs to one
      organization and one user. Requesting one your token does not own returns
      `404 Knowledge base not found`, never `403`. This is deliberate: a
      nonexistent ID, a malformed ID and someone else's ID are indistinguishable
      in the response, so the API cannot be used to probe for other tenants'
      data. If you get a `404` on an ID you are certain exists, suspect the
      token before you suspect the ID.


      **Ingestion is asynchronous.** File upload and website crawl both answer
      `202` as soon as the material is stored and the job is queued. Parsing,
      chunking, embedding and indexing happen afterwards in a worker. Poll the
      document status endpoint until it reports `completed` before expecting
      search to see the content. That gap is the most common source of "why
      isn't my data showing up".


      **There is no document update endpoint.** Every submission mints a new
      `document_id`, so re-uploading a file or re-crawling the same URLs creates
      a second document while the first remains. To refresh material, delete
      then resubmit — and note that the sequence is not atomic.
paths:
  /v1/public-sharing/:
    post:
      tags:
        - Public Sharing
      summary: Create Share
      description: >-
        Enables you to make an AI agent available to the users who has access to
        a shared key. 


        Ideal for integrating AI agents into public-facing websites where user
        authentication isn't required,

        such as landing pages, help centers, or public knowledge bases. This
        allows website visitors to

        interact with your AI agent without needing to create an account or log
        in. The shared key will be stored in the website.
      operationId: create_share_v1_public_sharing__post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePublicShareRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicShareResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    CreatePublicShareRequest:
      properties:
        ai_agent_id:
          type: string
          title: Ai Agent Id
          description: >-
            The unique identifier of the AI agent that you want to make publicly
            accessible. This agent will be available for web calls through a
            public URL.
      type: object
      required:
        - ai_agent_id
      title: CreatePublicShareRequest
    PublicShareResponse:
      properties:
        share_id:
          type: string
          title: Share Id
          description: >-
            Unique identifier for this public share configuration. Use this ID
            to manage or revoke public access
        ai_agent_id:
          type: string
          title: Ai Agent Id
          description: >-
            The unique identifier of the AI agent that is publicly accessible
            through this share configuration
        public_key:
          type: string
          title: Public Key
          description: >-
            The public access key that anonymous users must provide to initiate
            web calls with this AI agent
        created_at:
          type: string
          format: date-time
          title: Created At
          description: >-
            Timestamp indicating when this public share configuration was
            created
      type: object
      required:
        - share_id
        - ai_agent_id
        - public_key
        - created_at
      title: PublicShareResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError

````