openapi: 3.1.0
info:
  title: Inkeep Search and Chat API
  description: Leverage the Inkeep APIs to create your own AI-powered search and chat experiences built on top of your own content.
  version: 0.1.0
servers:
  - url: https://api.inkeep.com
    description: Production server
security:
  - api_key: []
tags: 
  - name: chat_session
    description: Create and manage chat sessions for users. Chat history and continuation of chat is automatically done.
paths:
  /v0/chat_sessions/chat_results:
    post:
      summary: Create Chat Session
      operationId: create
      tags: [chat_session]
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateChatSessionWithChatResultInput'
        required: true
      x-codeSamples:
        - lang: 'typescript'
          label: 'create_chat_session'
          source: |
            import { InkeepAI } from "@inkeep/ai-api";

            async function run() {
              const sdk = new InkeepAI({
                apiKey: "<INKEEP_API_KEY>",
              });

              const result = await sdk.chatSession.create({
                integrationId: "<INKEEP_INTEGRATION_ID>",
                chatSession: {
                  messages: [
                    {
                      role: "user",
                      content: "How do I get started?",
                    },
                  ],
                },
                stream: true,
              });

              /* Example of handling a streamed response */
              if (res.chatResultStream == null) {
                throw new Error("failed to create stream: received null value");
              }

              let chatSessionId: string | undefined | null = undefined;

              for await (const event of res.chatResultStream) {
                if (event.event == "message_chunk") {
                  console.log("Partial message: " + event.data.contentChunk);
                  chatSessionId = event.data.chatSessionId;
                }
                if (event.event == "records_cited") {
                  console.log("Citations: ", JSON.stringify(event.data.citations, null, 2));
                }
              }
            }

            run();
        - lang: 'typescript'
          label: 'create_chat_session_streamed'
          source: |
            import { InkeepAI } from "@inkeep/ai-api";

            async function run() {
              const sdk = new InkeepAI({
                apiKey: "<INKEEP_API_KEY>",
              });

              const result = await sdk.chatSession.create({
                integrationId: "<INKEEP_INTEGRATION_ID>",
                chatSession: {
                  messages: [
                    {
                      role: "user",
                      content: "How do I get started?",
                    },
                  ],
                },
                stream: true,
              });

              /* Example of handling a streamed response */
              if (result.chatResultStream == null) {
                throw new Error("failed to create stream: received null value");
              }

              let chatSessionId: string | undefined | null = undefined;

              for await (const event of result.chatResultStream) {
                if (event.event == "message_chunk") {
                  console.log("Partial message: " + event.data.contentChunk);
                  chatSessionId = event.data.chatSessionId;
                }
                if (event.event == "records_cited") {
                  console.log("Citations: ", JSON.stringify(event.data.citations, null, 2));
                }
              }
            }

            run();
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatResult'
            text/event-stream:
              schema:
                $ref: '#/components/schemas/ChatResultStream'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v0/chat_sessions/{chat_session_id}/chat_results:
    post:
      summary: Continue Chat Session
      operationId: continue
      tags: [chat_session]
      parameters:
        - required: true
          schema:
            title: Chat Session ID
            type: string
          name: chat_session_id
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContinueChatSessionWithChatResultInput'
        required: true
      x-codeSamples:
        - lang: 'typescript'
          label: 'continue_chat_session'
          source: |
            import { InkeepAI } from "@inkeep/ai-api";

            async function run() {
              const sdk = new InkeepAI({
                apiKey: "<INKEEP_API_KEY>",
              });

              const chatSessionId = "<CHAT_SESSION_ID>";

              const continuedChat = await sdk.chatSession.continue(chatSessionId, {
                integrationId: "<INKEEP_INTEGRATION_ID>",
                message: {
                  role: "user",
                  content: "What's next?",
                },
                stream: false,
              });

              /* Example of handling a non-streamed response */

              if (continuedChat.chatResult == null) {
                throw new Error("Empty chat result");
              }

              console.log("Full message:", continuedChat.chatResult.message.content);
              console.log("Citations: ", JSON.stringify(continuedChat.chatResult.message.recordsCited, null, 2));
            }

            run();
        - lang: 'typescript'
          label: 'continue_chat_session_streamed'
          source: |
            import { InkeepAI } from "@inkeep/ai-api";

            async function run() {
              const sdk = new InkeepAI({
                apiKey: "<INKEEP_API_KEY>",
              });

              const chatSessionId = "string";

              const continuedChat = await sdk.chatSession.continue(chatSessionId, {
                integrationId: "<INKEEP_INTEGRATION_ID>",
                message: {
                  role: "user",
                  content: "What's next?",
                },
                stream: false,
              });

              /* Example of handling a none-streamed response */

              if (continuedChat.chatResult == null) {
                throw new Error("Empty chat result");
              }

              console.log("Full message:", continuedChat.chatResult.message.content);
              console.log("Citations: ", JSON.stringify(continuedChat.chatResult.message.recordsCited, null, 2));
            }

            run();
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatResult'
            text/event-stream:
              schema:
                $ref: '#/components/schemas/ChatResultStream'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  securitySchemes:
    api_key:
      type: http
      scheme: bearer
  schemas:
    ChatResult:
      title: Chat Result
      required:
        - chat_session_id
        - message
      type: object
      properties:
        chat_session_id:
          title: Chat Session ID
          type: string
        message:
          $ref: '#/components/schemas/AssistantMessage'
    ChatResultStream:
      title: The event types that can be emitted as part of a streamed Chat Result
      oneOf:
        - $ref: '#/components/schemas/ChatResultMessageChunkEvent'
        - $ref: '#/components/schemas/ChatResultRecordsCitedEvent'
        # - $ref: '#/components/schemas/ServerSideEvent'
      discriminator:
        propertyName: event
        mapping:
          message_chunk: '#/components/schemas/ChatResultMessageChunkEvent'
          records_cited: '#/components/schemas/ChatResultRecordsCitedEvent'
    ChatResultMessageChunkEvent:
      description: A server-sent event containing a chunk of the message.
      type: object
      required: [event, data]
      properties:
        event:
          type: string
          const: "message_chunk"
        data:
          $ref: '#/components/schemas/MessageChunk'
    ChatResultRecordsCitedEvent:
      description: A server-sent event with information about the records cited in the message.
      type: object
      required: [event, data]
      properties:
        event:
          type: string
          const: "records_cited"
        data:
          $ref: '#/components/schemas/RecordsCited'
    ChatSessionInput:
      title: Chat Session Input
      required:
        - messages
      type: object
      properties:
        guidance:
          title: Guidance
          type: string
          nullable: true
        context:
          title: Context
          type: string
          nullable: true
        messages:
          title: Messages
          type: array
          minItems: 1
          maxItems: 1
          items:
            $ref: '#/components/schemas/Message'
        tags:
          title: Tags
          type: array
          items:
            type: string
    Citation:
      title: Citation
      required:
        - record
      type: object
      properties:
        number:
          title: Citation Number
          type: integer
        record:
          $ref: '#/components/schemas/Record'
        hit_url:
          title: Hit URL
          type: string
          nullable: true
    ContinueChatSessionWithChatResultInput:
      title: Continue Chat Session Input
      required:
        - integration_id
        - message
      type: object
      properties:
        integration_id:
          title: Integration ID
          type: string
        message:
          $ref: '#/components/schemas/Message'
        stream:
          title: Stream
          type: boolean
          default: false
    CreateChatSessionWithChatResultInput:
      title: Create Chat Session Input
      required:
        - integration_id
        - chat_session
      type: object
      properties:
        integration_id:
          title: Integration ID
          type: string
        chat_session:
          $ref: '#/components/schemas/ChatSessionInput'
        chat_mode:
          title: Chat Mode
          oneOf:
            - type: string
              enum: ["turbo", "auto"]
              title: ChatModeOptions
              $anchor: ChatModeOptions
            - type: string
        stream:
          title: Stream
          type: boolean
          default: false
    HTTPValidationError:
      title: HTTP Validation Error
      type: object
      properties:
        detail:
          title: Detail
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
    Message:
      oneOf:
        - $ref: '#/components/schemas/UserMessage'
        - $ref: '#/components/schemas/AssistantMessage'
      discriminator:
        propertyName: role
        mapping:
          user: '#/components/schemas/UserMessage'
          assistant: '#/components/schemas/AssistantMessage'
    UserMessage:
      title: User Message
      required:
        - role
        - content
      type: object
      properties:
        role:
          type: string
          const: "user"
        content:
          title: Content
          type: string
    AssistantMessage:
      title: Assistant Message
      required:
        - role
        - content
      type: object
      properties:
        role:
          type: string
          const: "assistant"
        content:
          title: Content
          type: string
        records_cited:
          $ref: '#/components/schemas/RecordsCited'
    MessageChunk:
      title: Message Chunk
      required:
        - content_chunk
      type: object
      properties:
        chat_session_id:
          title: Chat Session ID
          type: string
          nullable: true
        content_chunk:
          title: Content Chunk
          type: string
        finish_reason:
          oneOf:
            - type: string
              const: "stop"
            - type: string
              const: "length"
            - type: string
              const: "content_filter"
            - type: string
              enum: ["stop", "length", "content_filter"]
          nullable: true
    Record:
      required:
        - type
      type: object
      properties:
        type:
          $ref: '#/components/schemas/RecordType'
        url:
          title: URL
          type: string
          nullable: true
        title:
          title: Title
          type: string
          nullable: true
        description:
          title: Description
          type: string
          nullable: true
        breadcrumbs:
          nullable: true
          title: Breadcrumbs
          type: array
          items:
            type: string
    RecordsCited:
      title: Records Cited
      required:
        - citations
      type: object
      properties:
        citations:
          title: Citations
          type: array
          items:
            $ref: '#/components/schemas/Citation'
    RecordType:
      title: Record Type
      description: The type of record
      oneOf:
        - enum: [documentation, site, discourse_post, github_issue, github_discussion, stackoverflow_question, discord_forum_post, discord_message, custom_question_answer]
          type: string
          $anchor: RecordTypeEnumerated
          title: RecordTypeEnumerated
        - type: string
          title: other
    ValidationError:
      title: ValidationError
      required:
        - loc
        - msg
        - type
      type: object
      properties:
        loc:
          title: Location
          type: array
          items:
            oneOf:
              - type: string
              - type: integer
        msg:
          title: ErrorMessage
          type: string
        type:
          title: Error Type
          type: string