AI Assistant API

Summary

This documentation will guide you on how to integrate the Coalesce Catalog AI Assistant into your agent by calling it through our public API.

You can use it with:

• an MCP server

• as part of your agent's tools

📚

• Coalesce Catalog public API

• addAiAssistantJob endpoint

• getAiAssistantJobResult endpoint

Prerequisites

• You’ll need a Coalesce Catalog API Token. If you don’t have one, reach out to the Catalog ops team to request a new token

Introduction

• Coalesce Catalog public API is a GraphQL API

• To interact with the AI Assistant, you'll need to implement a polling system using the two queries below

  • addAiAssistantJob: Creates an asynchronous AI Assistant job and returns a jobId.

  • getAiAssistantJobResult: Uses the jobId to poll for the job's result.

Details

addAiAssistantJob

• Input

  • Headers

    {"Authorization": "Token <API_TOKEN>"}

  • Body

    query {
      addAiAssistantJob (
        data: {
          question: "<user_question>"
          email: "<user_email>"
          externalConversationId: "<unique_conversation_id>"
        }
      ){
        data {
          jobId
        }
      }
    }
    

• Output

  {
    "data": {
      "addAiAssistantJob": {
        "data": {
          "jobId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
        }
      }
    }
  }

getAiAssistantJobResult

• Input

  • Headers

    {"Authorization": "Token <API_TOKEN>"}

  • Body

    query {
      getAiAssistantJobResult (
        data: {
          id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
          delaySeconds: 5
        }
      ){
        data {
          status
          answer
          assets {
            id
            internalLink
            name
            url
          }
        }
      }
    }
    

• Output

  {
    "data": {
      "getAiAssistantJobResult": {
        "data": {
          "status": "completed",
          "answer": "<AI_Assistant_anwer>",
          "assets": [
            {
              "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
              "internalLink": "https://castordoc.com",
              "name": "",
              "url": "https://example.com"
            }
          ]
        }
      }
    }
  }

First, call addAiAssistantJob to receive the jobId. Then, use that jobId to poll for the result with getAiAssistantJobResult, which includes a built-in polling delay controlled by the delaySeconds parameter.