kaiv-ai Servers API

openapi: 3.2.0
info:
  title: Kaiva Bridge Management Servers API
  version: 1.0.0
  summary: Create, read and publish managed MCP servers from an OpenAPI spec, a GraphQL API, a database, documents or a remote MCP server.
  description: 'The REST API behind the Kaiva Bridge console and the @kaiva/bridge CLI. It creates managed MCP servers from an OpenAPI or Swagger spec, a GraphQL endpoint, a PostgreSQL, MySQL, MariaDB or SQL Server database, uploaded documents or a remote MCP server, chooses which tools are exposed, publishes the server and creates the keys AI clients use.


    Every request carries a management key: `Authorization: Bearer kv_mgmt_...`. An owner or admin creates one in the console under Keys & access (type Management), or `npx @kaiva/bridge login` approves a machine and saves one. A management key acts on its own workspace only, and it cannot create another management key. Gateway keys (`kv_live_...`) are for calling an MCP server and are refused here.


    A published server is an MCP endpoint (Streamable HTTP) at `https://api.kaiv.ai/api/bridge/mcp/`. AI clients call it with MCP, not with this API. Claude, ChatGPT, Cursor, VS Code and Claude Code can sign in to it with OAuth 2.1 instead of a key.


    Limits: 120 requests a minute per address; 60 document uploads a minute and 12 credential tests a minute per workspace.


    The CLI''s source is public: https://github.com/ai-kaiva/bridge'
  contact:
    name: Kaiva support
    email: support@kaiv.ai
    url: https://kaiv.ai/bridge/docs
  termsOfService: https://kaiv.ai/terms
servers:
- url: https://api.kaiv.ai/api/bridge/v1
  description: Production
security:
- managementKey: []
tags:
- name: Servers
  description: Create a managed MCP server from a source, choose its tools and publish it.
paths:
  /servers:
    get:
      tags:
      - Servers
      operationId: listServers
      summary: List the workspace's MCP servers
      responses:
        '200':
          description: Every server in the workspace.
          content:
            application/json:
              schema:
                type: object
                properties:
                  servers:
                    type: array
                    items:
                      $ref: '#/components/schemas/Server'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Servers
      operationId: createServer
      summary: Create an MCP server from an OpenAPI spec, a GraphQL API, a database or a…
      description: Creates a draft server. Read its tools with `POST /servers/{id}/introspect`, choose the tools, then publish. Every tool starts switched off; database tools only read.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - sourceType
              properties:
                name:
                  type: string
                  description: A short name. It becomes part of the server's address.
                sourceType:
                  type: string
                  enum:
                  - openapi
                  - graphql
                  - postgres
                  - mysql
                  - sqlserver
                  - mcp
                sourceUrl:
                  type: string
                  description: The spec's link (openapi), the GraphQL endpoint (graphql), the remote MCP server's address (mcp), or the connection string (postgres, mysql, sqlserver).
                sourceContent:
                  type: string
                  description: An OpenAPI or Swagger spec as text, instead of sourceUrl. Send apiBase with it.
                apiBase:
                  type: string
                  format: uri
                  description: The API's address, when the spec does not name one or names the wrong one.
                auth:
                  $ref: '#/components/schemas/Credential'
      responses:
        '201':
          description: The draft server.
          content:
            application/json:
              schema:
                type: object
                properties:
                  server:
                    $ref: '#/components/schemas/Server'
                additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/Conflict'
  /servers/{id}:
    parameters:
    - $ref: '#/components/parameters/ServerId'
    get:
      tags:
      - Servers
      operationId: getServer
      summary: Get one server with its tools and their input schemas
      responses:
        '200':
          description: The server and its tools.
          content:
            application/json:
              schema:
                type: object
                properties:
                  server:
                    $ref: '#/components/schemas/Server'
                  tools:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tool'
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Servers
      operationId: deleteServer
      summary: Delete a server
      description: Its address stops working at once.
      responses:
        '200':
          description: Whether a server was deleted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted: {}
        '401':
          $ref: '#/components/responses/Unauthorized'
  /servers/{id}/spec:
    parameters:
    - $ref: '#/components/parameters/ServerId'
    put:
      tags:
      - Servers
      operationId: replaceSpec
      summary: Replace a pasted OpenAPI spec
      description: For a server created from spec text. Read the tools again afterwards with `POST /servers/{id}/introspect`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - sourceContent
              properties:
                sourceContent:
                  type: string
                apiBase:
                  type: string
                  format: uri
      responses:
        '200':
          description: The server.
          content:
            application/json:
              schema:
                type: object
                properties:
                  server:
                    $ref: '#/components/schemas/Server'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /servers/{id}/introspect:
    parameters:
    - $ref: '#/components/parameters/ServerId'
    post:
      tags:
      - Servers
      operationId: introspectServer
      summary: Read the source and register its tools
      description: Reads the spec, schema, database or remote server and creates one tool per operation, query or table. On a live server, a tool whose meaning changed is held until the change is accepted (see Changes). Tools that were exposed stay exposed.
      responses:
        '200':
          description: The tools found.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '502':
          $ref: '#/components/responses/SourceError'
  /servers/{id}/tls:
    parameters:
    - $ref: '#/components/parameters/ServerId'
    patch:
      tags:
      - Servers
      operationId: setDatabaseTls
      summary: Set how a database's certificate is checked
      description: 'Check the certificate against a CA you provide (tested before it is saved), or connect without checking it (the connection is still encrypted), which needs `acknowledge: true`.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - mode
              properties:
                mode:
                  type: string
                  enum:
                  - verify
                  - skip
                caPem:
                  type: string
                  description: The CA certificate in PEM, for verify.
                acknowledge:
                  type: boolean
                  description: Required to skip the check.
      responses:
        '200':
          description: The server.
          content:
            application/json:
              schema:
                type: object
                properties:
                  server:
                    $ref: '#/components/schemas/Server'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /servers/{id}/api-base:
    parameters:
    - $ref: '#/components/parameters/ServerId'
    patch:
      tags:
      - Servers
      operationId: setApiBase
      summary: Change the address of the API a server calls
      description: A saved credential for a different host is removed, so it is never sent to an address it was not given for.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - apiBase
              properties:
                apiBase:
                  type: string
                  format: uri
      responses:
        '200':
          description: The server and what changed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  server:
                    $ref: '#/components/schemas/Server'
                  changes: {}
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /servers/{id}/tools:
    parameters:
    - $ref: '#/components/parameters/ServerId'
    patch:
      tags:
      - Servers
      operationId: setToolsExposed
      summary: Expose or hide several tools at once
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - toolIds
              - exposed
              properties:
                toolIds:
                  type: array
                  items:
                    type: string
                exposed:
                  type: boolean
      responses:
        '200':
          description: The result.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /servers/{id}/tools/{toolId}:
    parameters:
    - $ref: '#/components/parameters/ServerId'
    - $ref: '#/components/parameters/ToolId'
    patch:
      tags:
      - Servers
      operationId: setToolExposed
      summary: Expose or hide one tool
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - exposed
              properties:
                exposed:
                  type: boolean
      responses:
        '200':
          description: The tool.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /servers/{id}/publish:
    parameters:
    - $ref: '#/components/parameters/ServerId'
    post:
      tags:
      - Servers
      operationId: publishServer
      summary: Publish a server so its MCP address goes live
      description: The server answers at `https://api.kaiv.ai/api/bridge/mcp/` with the tools that are exposed. The plan's server count is checked here.
      responses:
        '200':
          description: The published server.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: The plan's server limit is reached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'
  /servers/{id}/tools/{toolId}/invoke:
    parameters:
    - $ref: '#/components/parameters/ServerId'
    - $ref: '#/components/parameters/ToolId'
    post:
      tags:
      - Servers
      operationId: invokeTool
      summary: Call one tool to test it
      description: 'Runs the same path an AI client''s call takes: the saved credential, the plan''s answer size and the tool-call record. Recorded as a test call, so it never counts as an AI client''s call. With `readOnly: true` only a tool that reads is run.'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                arguments:
                  type: object
                  additionalProperties: true
                readOnly:
                  type: boolean
      responses:
        '200':
          description: The tool's answer.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: A short code, or a sentence for errors in your request.
        message:
          type: string
    Credential:
      description: What Bridge sends to your API or MCP server. Stored encrypted; never shown to an AI client.
      oneOf:
      - type: object
        title: Bearer token
        required:
        - type
        - token
        properties:
          type:
            const: bearer
          token:
            type: string
      - type: object
        title: Username and password
        required:
        - type
        - username
        properties:
          type:
            const: basic
          username:
            type: string
          password:
            type: string
      - type: object
        title: Header
        required:
        - type
        - name
        - value
        properties:
          type:
            const: header
          name:
            type: string
            examples:
            - X-API-Key
          value:
            type: string
      - type: object
        title: Query parameter
        required:
        - type
        - name
        - value
        properties:
          type:
            const: query
          name:
            type: string
            examples:
            - api_key
          value:
            type: string
    Server:
      type: object
      description: An MCP server. A published server's MCP address is https://api.kaiv.ai/api/bridge/mcp/<slug>.
      properties:
        id:
          type: string
        name:
          type: string
        slug:
          type: string
        source_type:
          type: string
          enum:
          - openapi
          - graphql
          - postgres
          - mysql
          - sqlserver
          - mcp
          - dataset
          - documents
        state:
          type: string
          description: draft, live and so on.
      additionalProperties: true
    Tool:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        method:
          type: string
        exposed:
          type: boolean
        input_schema:
          type: object
          additionalProperties: true
      additionalProperties: true
  responses:
    Conflict:
      description: A name already in use, or the same request a moment ago.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: No key, an unknown key, or a gateway key (kv_live_) where a management key is needed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request is missing something or has a value Bridge cannot use; the answer says which.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    SourceError:
      description: Your source could not be read; the answer says what to fix.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: No such item in this workspace.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    ServerId:
      name: id
      in: path
      required: true
      description: The server's id.
      schema:
        type: string
    ToolId:
      name: toolId
      in: path
      required: true
      description: The tool's id.
      schema:
        type: string
  securitySchemes:
    managementKey:
      type: http
      scheme: bearer
      bearerFormat: kv_mgmt_
      description: A management key (kv_mgmt_...). Create one in the console under Keys & access, or run `npx @kaiva/bridge login`.
externalDocs:
  description: Kaiva Bridge docs
  url: https://kaiv.ai/bridge/docs