Skip to main content

AI Assistant API

Use the Coalesce Catalog public API to call the AI Assistant from your own agent, MCP server, or custom tool chain. You submit a question with addAiAssistantJob, then poll getAiAssistantJobResult until the job completes.

Summary​

You can use the AI Assistant API with:

  • an MCP server
  • your agent's tools

Resources​

Prerequisites​

You need a Catalog API token with Read & Write scope. Catalog administrators create tokens in Settings > API. See Getting Your Catalog API Keys for generation and rotation steps.

How the API Works​

The Coalesce Catalog public API is a GraphQL API. To interact with the AI Assistant, implement a polling flow with these two queries:

Add AI Assistant Job​

Use the addAiAssistantJob query to create an asynchronous AI Assistant job.

Add Job Request​

Headers:

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

Body:

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

Add Job Response​

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

Poll for Job Result​

Use the getAiAssistantJobResult query to poll for the job result.

Poll Request​

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
      }
    }
  }
}

Poll Response​

{
  "data": {
    "getAiAssistantJobResult": {
      "data": {
        "status": "completed",
        "answer": "<AI_Assistant_answer>",
        "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.