Create an answer

POST https://app.inconvo.ai/api/v1/conversations/answer

Body Parameters

---

question string Required

A natural language question.

---

context object Required

A JSON object of arbitrary key-value pairs that describe the caller’s tenancy or permission context. In the backend context filters map these keys to table columns to restrict every query to the appropriate tenant or access scope.

---

conversationId string Optional

The unique ID of a conversation. If not passed Inconvo will create a new conversation for the answer. Use this to create multi-turn conversations.

---

Response Type

type Answer = {
  id: string;
  conversationId: string;
  message: string;
  type: "text" | "chart" | "table";
  chart?: {
    type: "line" | "bar";
    data: {
      label: string;
      value: number;
    }[];
  };
  table?: {
    headers: string[];
    rows: string[][];
  };
};

Examples

Text

Request

curl -X POST "https://app.inconvo.ai/api/v1/conversations/answer" \
  -H "Authorization: Bearer $INCONVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d $'{
    "question": "What is our most popular product?",
    "context": {
      "organisationId": 1
    }
  }'

Response

{
  "id": "57ad0f60-617d-4d4c-a2ed-63e3bf0413ff",
  "conversationId": "2c4d3456-e1f7-4d36-a8fd-f5cf15491d00",
  "type": "text",
  "message": "Your most popular product is the iPhone 15, with a total of 24,840 orders.",
}

Chart

Request

curl -X POST 'https://app.inconvo.ai/api/v1/conversations/answer'\
  -H "Authorization: Bearer $INCONVO_API_KEY" \
  -H 'Content-Type: application/json'\
  -d $'{
    "question": "Show me our revenue trend for this year.",
    "context": {
      "organisationId": 1
    }
  }'

Response

{
  "id": "19ab658b-94f7-45c1-97b7-777711446194",
  "conversationId": "852595cc-8a1f-4b6a-8ccf-31e7f25fc75b",
  "type": "chart",
  "message": "Here is your monthly revenue trend for 2025 so far. The chart shows total revenue for each month from January to May.",
  "chart": {
    "type": "line",
    "data": [
      {
        "label": "2025-01",
        "value": 3019366.23
      },
      {
        "label": "2025-02",
        "value": 2766805.29
      },
      {
        "label": "2025-03",
        "value": 3026689.03
      },
      {
        "label": "2025-04",
        "value": 3059223.96
      },
      {
        "label": "2025-05",
        "value": 57216.21
      }
    ],
    "title": "Monthly Revenue Trend for 2025",
    "xLabel": "Month",
    "yLabel": "Revenue ($)"
  }
}

Table

Request

curl -X POST 'https://app.inconvo.ai/api/v1/conversations/answer'\
  -H "Authorization: Bearer $INCONVO_API_KEY" \
  -H 'Content-Type: application/json'\
  -d $'{
    "question": "What were my top 5 selling products last quarter?",
    "context": {
      "organisationId": 1
    }
  }'

Response

{
  "id": "2dc27a80-5ef9-4d6a-b1a4-c0f45f5f8aba",
  "conversationId": "90d54148-779d-416e-9cd4-382a4aaf674a",
  "type": "table",
  "message": "Here are your top 5 selling products from last quarter:",
  "table": {
    "head": [
      "Product",
      "Units Sold"
    ],
    "body": [
      [
        "iPhone 15",
        "4366"
      ],
      [
        "MacBook Pro",
        "1793"
      ],
      [
        "AirPods Pro",
        "1354"
      ],
      [
        "iPad Pro",
        "1212"
      ],
      [
        "Apple Watch",
        "1019"
      ]
    ]
  }
}