Hana API

For a quick index of endpoints, see the Hana API Overview.

Sample data notice

IDs in this document are illustrative placeholders. Real API responses return stable IDs for your organization data.

Authorization

info

Use this header to authorize requests to the Hana API.

Auth Type

You need to pass this API key in the header of your requests.

API Key
- Key: X-API-KEY
- Value: HANA-<YOUR_API_KEY>

Runtime auth and billing checks

401 Unauthorized: invalid API key, missing OAuth consent, or expired/incomplete OAuth scopes for the key owner.
402 Payment Required: seat/billing mismatch or monthly interaction limit reached for the plan.

How to Get Your API Key

Go to the Connectors Page
- Visit Hana Dashboard Connectors.
- You will find a list of available connectors.
Find & Connect to the Hana API
- Look for the "Hana API" connector.
- Click on "Connect" to generate your API key.
Copy & Save Your API Key
- The API key will be displayed only once.
- Make sure to copy and save it securely for future use.

note

If you disconnect the Hana API connector, the current API key becomes invalid.
To continue using the API, reconnect and generate a new key.

API Key Validation

info

Test the connection and validity of the API key.

Request Type

GET

Endpoint

https://hana-api.hanabitech.com/v1/expose-api/test

cURL Example

curl -X GET https://hana-api.hanabitech.com/v1/expose-api/test -H "X-API-KEY: HANA-<YOUR_API_KEY>"

Success Response

{
  "success": true,
  "content": {
    "email": "john.doe@example.com",
    "role": "ADMIN",
    "displayName": "John Doe",
    "timestamp": "2025-03-09T11:48:40.713Z"
  }
}

Chat Completion

info

Generate a completion request from a message history. Hana may use available web context and organization memory depending on request scope and permissions.

Request Type

POST

Endpoint

https://hana-api.hanabitech.com/v1/expose-api/chat/completion

Payload

`messages`: Array of `message` - required

In the payload, the messages array must contain at least one message. Each message object in the array should have the following properties:

Properties of a `message`

role: 'user' | 'assistant' - required
- Specifies the sender's role.
  - user - represents a person interacting with the assistant.
  - assistant - represents a non-human entity such as an AI model or a platform such as Notion etc.
content: string - required
- Message content can be:
  - plain text string, or
  - multimodal array entries like text/image items:
    - { "type": "text", "text": "..." }
    - { "type": "image_url", "image_url": { "url": "https://..." } }
name: string - required
- A unique identifier for the sender. Allowed characters are letters, numbers, and hyphens (^[a-zA-Z0-9-]+$).
includeWebSources: boolean - optional
- Set true to allow web-source inclusion in completion flow.
includeMetadata: boolean - optional
- Set true to include metadata in completion flow.

{
  "includeWebSources": true,
  "includeMetadata": false,
  "messages": [
    {
      "role": "user",
      "content": "I’m planning to refresh my wardrobe for spring. Any recommendations for must-have items?",
      "name": "alex-jones"
    },
    {
      "role": "user",
      "content": "Same here! I’d love some inspiration for colors and styles that feel trendy this season.",
      "name": "clark"
    },
    {
      "role": "assistant",
      "content": [
        {
          "type": "text",
          "text": "Use this image as style inspiration."
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/reference.jpg"
          }
        }
      ],
      "name": "assistant-bot"
    }
  ]
}

cURL Example

curl -X POST "https://hana-api.hanabitech.com/v1/expose-api/chat/completion" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: HANA-<YOUR_API_KEY>" \
  -d '{
    "includeWebSources": true,
    "includeMetadata": false,
    "messages": [
      {"role":"user","content":"Summarize today team updates","name":"alex-jones"}
    ]
  }'

Response

warning

This endpoint only creates the completion request. Retrieve the final output from the Chat Completion Status endpoint.

{
  "success": true,
  "content": {
    "userId": "USER_ID",
    "organizationId": "ORG_ID",
    "messageId": "client-hana-<UUID>",
    "completionStartTime": "2025-03-09T12:12:03.388Z",
    "completionFinishTime": null,
    "completionResponse": null,
    "completionStatus": "IN_PROGRESS",
    "_id": "COMPLETION_ID",
    "__v": 0,
    "createdAt": "2025-03-09T12:12:03.389Z",
    "updatedAt": "2025-03-09T12:12:03.389Z"
  }
}

Chat Completion Status

info

Use this endpoint to check completion request status. completionStatus can be IN_PROGRESS, COMPLETED, or ERROR. When status is COMPLETED, the output is available in completionResponse; otherwise completionResponse is null.

Status retention

Completion status records are automatically deleted after 3 hours.

Request Type

GET

Endpoint

https://hana-api.hanabitech.com/v1/expose-api/chat/statuses?messageId={{CHAT_COMPLETION_MESSAGE_ID}}&page={{PAGE_NUMBER}}&per_page={{PAGE_NUMBER_LIMIT}}

Request Params

messageId: string - optional
- Provide the messageId from Chat Completion to filter for one request; omit it to list recent status records for the API key owner.
per_page: number - optional
- The number of records to fetch per page
- Defaults to 10
page: number - optional
- The page number starting from 1
- Defaults to 1

cURL Example

curl -G "https://hana-api.hanabitech.com/v1/expose-api/chat/statuses" -H "Content-Type: application/json" -H "X-API-KEY: HANA-<YOUR_API_KEY>" --data-urlencode "page=1" --data-urlencode "per_page=1" --data-urlencode "messageId=client-hana-03b495e3-4ba1-457e-9065-749545b6f33e"

Response

tip

In automations, treat a request as successful only when completionStatus is COMPLETED and completionResponse is non-null.

Completion in Progress

{
  "success": true,
  "content": {
    "data": [
      {
        "_id": "STATUS_ID_IN_PROGRESS",
        "userId": "USER_ID",
        "organizationId": "ORG_ID",
        "messageId": "client-hana-03b495e3-4ba1-457e-9065-749545b6f33e",
        "completionStartTime": "2025-03-09T17:22:06.638Z",
        "completionFinishTime": null,
        "completionResponse": null,
        "completionStatus": "IN_PROGRESS",
        "__v": 0,
        "createdAt": "2025-03-09T17:22:06.639Z",
        "updatedAt": "2025-03-09T17:22:06.639Z"
      }
    ],
    "totalCount": 1
  }
}

Completion Completed

{
  "success": true,
  "content": {
    "data": [
      {
        "_id": "STATUS_ID_COMPLETED",
        "userId": "USER_ID",
        "organizationId": "ORG_ID",
        "messageId": "client-hana-03b495e3-4ba1-457e-9065-749545b6f33e",
        "completionStartTime": "2025-03-09T17:22:06.638Z",
        "completionFinishTime": "2025-03-09T17:22:36.867Z",
        "completionResponse": "To align your wardrobe with Hanabi’s theme and the colors typically associated with spring, consider the following suggestions:\n\n1. *Hanabi Theme*: Hanabi, meaning \"fireworks\" in Japanese, inspires vibrant and dynamic imagery. Opt for bold, colorful outfits with patterns reminiscent of fireworks, such as bright floral prints or geometric designs.\n\n2. *Spring Colors*: Spring is often associated with pastel shades, bright whites, and soft greens. Incorporate these colors through accessories like scarves, hats, or shoes in pastel hues, or choose clothing items like light green dresses or white tops with floral patterns.\n\n3. *Combining Themes*: For a look that combines both themes, consider a pastel-colored dress with fireworks-inspired accessories, such as a bold, colorful scarf or statement jewelry that reflects the dynamic colors of fireworks. Alternatively, a white or light-colored outfit with vibrant floral patterns can capture the essence of spring while nodding to the celebratory aspect of Hanabi.\n\nThese suggestions blend the vibrant and celebratory nature of Hanabi with the freshness of spring, creating a unique and stylish wardrobe update.",
        "completionStatus": "COMPLETED",
        "__v": 0,
        "createdAt": "2025-03-09T17:22:06.639Z",
        "updatedAt": "2025-03-09T17:22:36.867Z"
      }
    ],
    "totalCount": 1
  }
}

Completion Error

{
  "success": true,
  "content": {
    "data": [
      {
        "_id": "STATUS_ID_ERROR",
        "userId": "USER_ID",
        "organizationId": "ORG_ID",
        "messageId": "client-hana-03b495e3-4ba1-457e-9065-749545b6f33e",
        "completionStartTime": "2025-03-09T17:22:06.638Z",
        "completionFinishTime": "2025-03-09T17:22:36.867Z",
        "completionResponse": null,
        "completionStatus": "ERROR",
        "__v": 0,
        "createdAt": "2025-03-09T17:22:06.639Z",
        "updatedAt": "2025-03-09T17:22:06.639Z"
      }
    ],
    "totalCount": 1
  }
}

Report Message Creation

info

Create a message in a report group. This endpoint is commonly used in automation pipelines where external systems publish structured updates to Hana for downstream Q&A and summaries.

Example follow-up prompts in Google Chat: @Hana what is the sprint status today in notion_tech_updates? @Hana what was completed this week in notion_tech_updates?

Request Type

POST

Endpoint

https://hana-api.hanabitech.com/v1/expose-api/report-groups/report-messages

note

A report group must exist before calling this endpoint.
If needed, create one in Hana Dashboard Report Groups.

Payload

In the payload, the object must contain all required properties. Each property should be structured as follows:

reportGroupName: string - required
- The name of the report group where this message should be added.
- Always small letters with hyphens and no spaces.
sourcePlatform: string - required
- The platform where the reported message originated from (e.g., "Website" , "Slack", "Google Chat", "Microsoft Teams").
messageTitle: string - required
- A short summary or title for the report message.
messageString: string - required
- The actual message content that is being reported.

{
  "reportGroupName": "web-development-project",
  "messageString": "The new dashboard UI is much better, but the loading time is still slow when switching between reports.",
  "messageTitle": "UI Improvement Feedback",
  "sourcePlatform": "Slack"
}

cURL Example

curl -X POST "https://hana-api.hanabitech.com/v1/expose-api/report-groups/report-messages" -H "Content-Type: application/json" -H "X-API-KEY: HANA-<YOUR_API_KEY>" -d "{\"reportGroupName\":\"web-development-project\",\"messageString\":\"The new dashboard UI is much better, but the loading time is still slow when switching between reports.\",\"messageTitle\":\"UI Improvement Feedback\",\"sourcePlatform\":\"Slack\"}"

Response

{
  "success": true,
  "content": {
    "reportGroupName": "web-development-project",
    "messageString": "The new dashboard UI is much better, but the loading time is still slow when switching between reports.",
    "messageTitle": "UI Improvement Feedback",
    "sourcePlatform": "SLACK"
  }
}

Create Google Chat Message

info

Create a Google Chat message through Hana. This is commonly used in automation flows to publish updates into team spaces. Google Chat formatting rules apply: Formatting Rules.

Request Type

POST

Endpoint

https://hana-api.hanabitech.com/v1/expose-api/chat/create-google-chat-message

Ensure Hana is in the target space

Before sending a message, verify Hana is added to the target Google Chat space.

Payload

In the payload, the object must contain all required properties. Each property should be structured as follows:

message: string - required
- The actual text content of the message being sent.
spaceName: string - required
- The unique identifier of the chat space or conversation where the message should be delivered.
- Always of the format - spaces/AAAAR9-3Sxs

{
  "message": "📢 **Sales Update:** Great news! We closed 5 major deals this week, bringing in a total revenue of $250,000. 🚀 Kudos to the sales team for their hard work! Let’s keep up the momentum and push for an even stronger quarter. 💪",
  "spaceName": "spaces/AAAA1234xyz"
}

How to Get the `spaceName`

From Google Chat URL

Open the desired chat space in your browser.
Look at the URL bar, example:
- https://mail.google.com/chat/#chat/space/AAAA1234xyz
- The part after /space/ (example: AAAA1234xyz) is the spaceId.
- Format the spaceName:
  - Prefix thespaceId with spaces/ to create the spaceName.
  - Example: If thespaceId is AAAA1234xyz, then the spaceName will be {"spaceName": "spaces/AAAA1234xyz"}

cURL Example

curl -X POST "https://hana-api.hanabitech.com/v1/expose-api/chat/create-google-chat-message" -H "Content-Type: application/json" -H "X-API-KEY: HANA-<YOUR_API_KEY>" -d "{\"message\":\"📢 **Sales Update:** Great news! We closed 5 major deals this week, bringing in a total revenue of $250,000. 🚀 Kudos to the sales team for their hard work! Let’s keep up the momentum and push for an even stronger quarter. 💪\",\"spaceName\":\"spaces/AAAA1234xyz\"}"

Response

{
  "success": true,
  "content": "📢 **Sales Update:** Great news! We closed 5 major deals this week, bringing in a total revenue of $250,000. 🚀 Kudos to the sales team for their hard work! Let’s keep up the momentum and push for an even stronger quarter. 💪"
}

Get Report Groups

info

List report groups available to the authenticated organization.

Request Type

GET

Endpoint

https://hana-api.hanabitech.com/v1/expose-api/report-groups?page={{PAGE_NUMBER}}&per_page={{PAGE_NUMBER_LIMIT}}&search={{SEARCH_QUERY}}

Request Params

search: string - optional
- Filters the result for a particular search string
per_page: number - optional
- The number of records to fetch per page
- Defaults to 10
page: number - optional
- The page number starting from 1
- Defaults to 1

cURL Example

curl -G "https://hana-api.hanabitech.com/v1/expose-api/report-groups" -H "Content-Type: application/json" -H "X-API-KEY: HANA-<YOUR_API_KEY>" --data-urlencode "per_page=10" --data-urlencode "page=1" --data-urlencode "search=daily"

Response

{
  "success": true,
  "content": {
    "data": [
      {
        "_id": "REPORT_GROUP_ID",
        "title": "daily_standup",
        "createdBy": {
          "_id": "USER_ID",
          "userID": "users/USER_ID",
          "email": "user@example.com",
          "displayName": "Nav Aggarwal",
          "organizationId": "ORG_ID",
          "createdAt": "2024-02-14T07:40:12.108Z",
          "updatedAt": "2025-03-09T17:28:44.306Z",
          "__v": 0,
          "profilePicture": "https://example.com/user.jpg",
          "updatedBy": "UPDATER_ID",
          "designation": "Chief Executive Officer"
        },
        "organizationId": "ORG_ID",
        "createdAt": "2024-01-25T13:10:16.277Z",
        "updatedAt": "2024-07-18T02:40:05.679Z",
        "reportMessagesCount": 42,
        "score": 0.9611515998840332
      }
    ],
    "totalCount": 1,
    "llmDigestableOutput": "REPORT GROUP TITLE: daily_standup\nREPORT GROUP CREATED BY NAME: Nav Aggarwal\nREPORT GROUP CREATED BY EMAIL: nav.archer@hanabitech.com\nREPORT GROUP CREATED BY GOOGLE USER ID: users/USER_ID"
  }
}

Get Report Group Messages

info

List messages from a specific report group.

Request Type

GET

Endpoint

https://hana-api.hanabitech.com/v1/expose-api/report-groups/{{REPORT_GROUP_ID}}/report-messages?page={{PAGE_NUMBER}}&per_page={{PAGE_NUMBER_LIMIT}}&search={{SEARCH_QUERY}}&startTimestamp={{START_TIME_STAMP}}&endTimestamp={{END_TIME_STAMP}}

Here REPORT_GROUP_ID is the _id of the report groups for which the messages must be fetched

Request Params

search: string - optional
- Filters the result for a particular search string
per_page: number - optional
- The number of records to fetch per page
- Defaults to 10
page: number - optional
- The page number starting from 1
- Defaults to 1
startTimestamp: string - optional
- The start timestamp from which the messages must be fetched (inclusive)
- Example - 2025-02-16T01:42:07.213Z
endTimestamp: string - optional
- The end timestamp till which the messages must be fetched (inclusive)
- Example - 2025-02-17T01:00:07.213Z

cURL Example

curl -G "https://hana-api.hanabitech.com/v1/expose-api/report-groups/{{REPORT_GROUP_ID}}/report-messages" -H "Content-Type: application/json" -H "X-API-KEY: HANA-<YOUR_API_KEY>" --data-urlencode "per_page=10" --data-urlencode "page=1" --data-urlencode "search=Notion" --data-urlencode "startTimestamp=2024-01-14T07:40:12.108Z" --data-urlencode "endTimestamp=2024-03-14T07:40:12.108Z"

Response

{
  "success": true,
  "content": {
    "data": [
      {
        "_id": "REPORT_MESSAGE_ID_1",
        "reportGroupId": "REPORT_GROUP_ID",
        "title": "Sprint Ops Update",
        "description": "Completed onboarding docs refresh, fixed ingestion retry handling, and validated Zapier report delivery for production workflows.",
        "createdBy": {
          "_id": "USER_ID",
          "userID": "users/USER_ID",
          "email": "user@example.com",
          "displayName": "Nav Aggarwal",
          "organizationId": "ORG_ID",
          "createdAt": "2024-02-14T07:40:12.108Z",
          "updatedAt": "2025-03-09T18:28:32.988Z",
          "__v": 0,
          "profilePicture": "https://example.com/user.jpg",
          "updatedBy": "UPDATER_ID",
          "designation": "Chief Executive Officer"
        },
        "createdPlatformSource": "NOTION",
        "organizationId": "ORG_ID",
        "reportMessagesCount": 185,
        "createdAt": "2025-03-05T12:43:19.377Z",
        "updatedAt": "2025-03-05T12:43:19.377Z",
        "score": 1.3040423393249512
      },
      {
        "_id": "REPORT_MESSAGE_ID_2",
        "reportGroupId": "REPORT_GROUP_ID",
        "title": "Platform Reliability Follow-up",
        "description": "Investigated dashboard date-range filtering behavior, opened follow-up tasks for query optimization, and documented mitigation steps for support triage.",
        "createdBy": {
          "_id": "USER_ID",
          "userID": "users/USER_ID",
          "email": "user@example.com",
          "displayName": "Santhosh Kumar",
          "organizationId": "ORG_ID",
          "createdAt": "2024-02-01T10:56:51.966Z",
          "updatedAt": "2025-03-09T18:35:19.535Z",
          "__v": 0,
          "profilePicture": "https://example.com/user.jpg",
          "updatedBy": "UPDATER_ID",
          "designation": "Full Stack Developer"
        },
        "createdPlatformSource": "SLACK",
        "organizationId": "ORG_ID",
        "reportMessagesCount": 185,
        "createdAt": "2025-03-04T14:03:55.977Z",
        "updatedAt": "2025-03-04T14:03:55.977Z",
        "score": 1.6430115699768066
      }
    ],
    "totalCount": 2,
    "llmDigestableOutput": "REPORT GROUP MESSAGE TITLE: Sprint Ops Update\nREPORT GROUP MESSAGE DESCRIPTION: Completed onboarding docs refresh, fixed ingestion retry handling, and validated Zapier report delivery for production workflows.\nREPORT GROUP MESSAGE PLATFORM SOURCE: NA\nREPORT GROUP MESSAGE CREATED DATE: Wed Mar 05 2025 12:43:19 GMT+0000 (Coordinated Universal Time)\nREPORT GROUP MESSAGE CREATED BY NAME: Nav Aggarwal\nREPORT GROUP MESSAGE CREATED BY EMAIL: nav.archer@hanabitech.com\nREPORT GROUP MESSAGE CREATED BY GOOGLE USER ID: users/USER_ID\n\nREPORT GROUP MESSAGE TITLE: Platform Reliability Follow-up\nREPORT GROUP MESSAGE DESCRIPTION: Investigated dashboard date-range filtering behavior, opened follow-up tasks for query optimization, and documented mitigation steps for support triage."
  }
}

Get Spaces Hana is Integrated In

info

List Google Chat spaces where Hana is currently integrated.

Request Type

GET

Endpoint

https://hana-api.hanabitech.com/v1/expose-api/spaces?page={{PAGE_NUMBER}}&per_page={{PAGE_NUMBER_LIMIT}}&search={{SEARCH_QUERY}}

Request Params

search: string - optional
- Filters the result for a particular search string
per_page: number - optional
- The number of records to fetch per page
- Defaults to 10
page: number - optional
- The page number starting from 1
- Defaults to 1

cURL Example

curl -G "https://hana-api.hanabitech.com/v1/expose-api/spaces" -H "Content-Type: application/json" -H "X-API-KEY: HANA-<YOUR_API_KEY>" --data-urlencode "per_page=10" --data-urlencode "page=1" --data-urlencode "search=test"

Response

{
  "success": true,
  "content": {
    "data": [
      {
        "_id": "SPACE_RECORD_ID_1",
        "spaceId": "spaces/SPACE_ID",
        "orgId": "ORG_ID",
        "displayName": "test",
        "spaceType": "GROUP_CHAT",
        "description": null,
        "spaceCreatedAt": "2024-11-27T06:00:37.312Z",
        "isActive": true,
        "hanaStatus": "ADDED",
        "isAutoInitiationEnabled": false,
        "isAutoMemoryIngestionEnabled": false,
        "createdAt": "2024-11-27T06:02:45.124Z",
        "updatedAt": "2024-11-27T06:02:45.124Z",
        "score": 1.8675340414047241
      },
      {
        "_id": "SPACE_RECORD_ID_2",
        "spaceId": "spaces/SPACE_ID",
        "orgId": "ORG_ID",
        "displayName": "test",
        "spaceType": "GROUP_CHAT",
        "description": null,
        "spaceCreatedAt": "2024-04-17T17:17:56.113Z",
        "isActive": true,
        "hanaStatus": "ADDED",
        "isAutoInitiationEnabled": false,
        "isAutoMemoryIngestionEnabled": false,
        "createdAt": "2024-04-17T17:18:46.442Z",
        "updatedAt": "2024-04-17T17:18:46.442Z",
        "score": 1.8675340414047241
      },
      {
        "_id": "SPACE_RECORD_ID_3",
        "spaceId": "spaces/SPACE_ID",
        "orgId": "ORG_ID",
        "displayName": "Temp Test",
        "spaceType": "GROUP_CHAT",
        "description": null,
        "spaceCreatedAt": "2025-02-23T21:32:28.036Z",
        "isActive": true,
        "isAutoInitiationEnabled": false,
        "isAutoMemoryIngestionEnabled": false,
        "createdAt": "2025-02-23T21:34:15.266Z",
        "updatedAt": "2025-03-06T10:36:19.023Z",
        "score": 1.5343365669250488
      },
      {
        "_id": "SPACE_RECORD_ID_4",
        "spaceId": "spaces/SPACE_ID",
        "orgId": "ORG_ID",
        "displayName": "[TEMP]: Test Space",
        "spaceType": "GROUP_CHAT",
        "description": null,
        "spaceCreatedAt": "2024-09-08T06:33:26.300Z",
        "isActive": true,
        "hanaStatus": "ADDED",
        "isAutoInitiationEnabled": false,
        "isAutoMemoryIngestionEnabled": false,
        "createdAt": "2024-11-13T17:18:26.793Z",
        "updatedAt": "2025-02-22T18:43:58.778Z",
        "score": 1.3020334243774414
      },
      {
        "_id": "SPACE_RECORD_ID_5",
        "spaceId": "spaces/SPACE_ID",
        "orgId": "ORG_ID",
        "displayName": "[TEST] Hana testing",
        "spaceType": "GROUP_CHAT",
        "description": "Everything about the testing of Hana bot",
        "spaceCreatedAt": "2024-03-26T09:20:30.047Z",
        "isActive": true,
        "hanaStatus": "ADDED",
        "createdAt": "2024-07-30T11:56:19.852Z",
        "updatedAt": "2025-01-23T08:22:19.423Z",
        "isAutoInitiationEnabled": false,
        "isAutoMemoryIngestionEnabled": false,
        "score": 1.3020334243774414
      },
      {
        "_id": "SPACE_RECORD_ID_6",
        "spaceId": "spaces/SPACE_ID",
        "orgId": "ORG_ID",
        "displayName": "Hana Test Group",
        "spaceType": "GROUP_CHAT",
        "description": null,
        "spaceCreatedAt": "2024-01-16T19:46:41.882Z",
        "isActive": true,
        "hanaStatus": "ADDED",
        "isAutoInitiationEnabled": false,
        "isAutoMemoryIngestionEnabled": false,
        "createdAt": "2024-02-14T11:02:46.045Z",
        "updatedAt": "2024-02-14T11:02:46.045Z",
        "score": 1.3020334243774414
      }
    ],
    "totalCount": 6,
    "llmDigestableOutput": "SPACE NAME: test\nSPACE DESCRIPTION: NA\nSPACE GOOGLE CHAT ID: spaces/AAAAA6QArts\nSPACE GOOGLE CHAT TYPE: GROUP_CHAT\nSPACE CREATED DATE IN GOOGLE CHAT: Wed Nov 27 2024 06:00:37 GMT+0000 (Coordinated Universal Time)\nSPACE ACTIVE STATUS: true\nCAN Hana AUTO INITIATE MESSAGES in SPACE: false\nCAN Hana AUTO DIGEST MEMORIES in SPACE: false\n\nSPACE NAME: test\nSPACE DESCRIPTION: NA\nSPACE GOOGLE CHAT ID: spaces/AAAAUk0RiiU\nSPACE GOOGLE CHAT TYPE: GROUP_CHAT\nSPACE CREATED DATE IN GOOGLE CHAT: Wed Apr 17 2024 17:17:56 GMT+0000 (Coordinated Universal Time)\nSPACE ACTIVE STATUS: true\nCAN Hana AUTO INITIATE MESSAGES in SPACE: false\nCAN Hana AUTO DIGEST MEMORIES in SPACE: false\n\nSPACE NAME: Temp Test\nSPACE DESCRIPTION: NA\nSPACE GOOGLE CHAT ID: spaces/AAAAsQJOWhA\nSPACE GOOGLE CHAT TYPE: GROUP_CHAT\nSPACE CREATED DATE IN GOOGLE CHAT: Sun Feb 23 2025 21:32:28 GMT+0000 (Coordinated Universal Time)\nSPACE ACTIVE STATUS: true\nCAN Hana AUTO INITIATE MESSAGES in SPACE: false\nCAN Hana AUTO DIGEST MEMORIES in SPACE: false\n\nSPACE NAME: [TEMP]: Test Space\nSPACE DESCRIPTION: NA\nSPACE GOOGLE CHAT ID: spaces/AAAAomn9p20\nSPACE GOOGLE CHAT TYPE: GROUP_CHAT\nSPACE CREATED DATE IN GOOGLE CHAT: Sun Sep 08 2024 06:33:26 GMT+0000 (Coordinated Universal Time)\nSPACE ACTIVE STATUS: true\nCAN Hana AUTO INITIATE MESSAGES in SPACE: false\nCAN Hana AUTO DIGEST MEMORIES in SPACE: false\n\nSPACE NAME: [TEST] Hana testing\nSPACE DESCRIPTION: Everything about the testing of Hana bot\nSPACE GOOGLE CHAT ID: spaces/AAAAyvKje9s\nSPACE GOOGLE CHAT TYPE: GROUP_CHAT\nSPACE CREATED DATE IN GOOGLE CHAT: Tue Mar 26 2024 09:20:30 GMT+0000 (Coordinated Universal Time)\nSPACE ACTIVE STATUS: true\nCAN Hana AUTO INITIATE MESSAGES in SPACE: false\nCAN Hana AUTO DIGEST MEMORIES in SPACE: false\n\nSPACE NAME: Hana Test Group\nSPACE DESCRIPTION: NA\nSPACE GOOGLE CHAT ID: spaces/AAAAzu2E6Rg\nSPACE GOOGLE CHAT TYPE: GROUP_CHAT\nSPACE CREATED DATE IN GOOGLE CHAT: Tue Jan 16 2024 19:46:41 GMT+0000 (Coordinated Universal Time)\nSPACE ACTIVE STATUS: true\nCAN Hana AUTO INITIATE MESSAGES in SPACE: false\nCAN Hana AUTO DIGEST MEMORIES in SPACE: false"
}
}

Get Users

info

Retrieve a paginated list of users, optionally filtered by a search query on email or display name.

Request Type

GET

Endpoint

https://hana-api.hanabitech.com/v1/expose-api/users?page={{PAGE_NUMBER}}&per_page={{PAGE_NUMBER_LIMIT}}&search={{SEARCH_QUERY}}

Request Params

search: string - optional
- Filters the result for a particular search string against email and displayName.
per_page: number - optional
- The number of records to fetch per page
- Defaults to 10
page: number - optional
- The page number starting from 1
- Defaults to 1

cURL Example

curl -G "https://hana-api.hanabitech.com/v1/expose-api/users" -H "Content-Type: application/json" -H "X-API-KEY: HANA-<YOUR_API_KEY>" --data-urlencode "page=1" --data-urlencode "per_page=10"

Response

A successful response returns HTTP 200 OK with this JSON structure:

{
"success": true,
"content": {
  "data": [
    {
      "_id": "USER_DOC_ID",
      "userID": "users/USER_ID",
      "email": "user@example.com",
      "displayName": "Sagar Kapoor",
      "role": "USER",
      "designation": null,
      "isActive": true,
      "organizationId": "67f4d7483fd123456789",
      "profilePicture": "https://example.com/user.jpg",
      "createdAt": "2025-04-10T13:32:56.847Z",
      "updatedAt": "2025-04-10T13:32:56.847Z",
      "updatedBy": "UPDATER_ID",
      "__v": 0
    },
    {
      "_id": "USER_DOC_ID_2",
      "userID": "users/USER_ID",
      "email": "user@example.com",
      "displayName": "Santhosh Kumar",
      "role": "ADMIN",
      "designation": "Full Stack Developer",
      "isActive": true,
      "organizationId": "67f4d7483fd012356",
      "profilePicture": "https://example.com/user.jpg",
      "createdAt": "2025-04-08T07:59:05.601Z",
      "updatedAt": "2025-05-13T16:25:01.365Z",
      "updatedBy": "UPDATER_ID",
      "__v": 0
    }
  ],
  "totalCount": 2
}
}

Create Memory

info

Create a new text memory batch.

memoryType must be TEXT_MEMORY.
isGlobal: true is restricted (global memory CUD is role-gated).
For non-global memory creation, organization roles such as ADMIN and DOMAIN_OWNER are permitted.

Request Type

POST

Endpoint

https://hana-api.hanabitech.com/v1/expose-api/memory

Payload

memoryType – must be "TEXT_MEMORY" (required)
text – memory text (required)
isGlobal – whether the memory should be global (optional, default false)
memoryLevel – ORG or JUST_MYSELF (optional, defaults to ORG if omitted/invalid)
useCaseInstructions – optional instruction string to improve retrieval targeting

cURL Example

curl -X POST "https://hana-api.hanabitech.com/v1/expose-api/memory" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: HANA-<YOUR_API_KEY>" \
  -d '{"memoryType":"TEXT_MEMORY","text":"Initial planning","isGlobal":false,"memoryLevel":"ORG"}'

Response

{
  "success": true,
  "content": {
    "batch": {
      "_id": "MEMORY_BATCH_ID",
      "title": "Initial planning",
      "organizationId": "ORG_ID",
      "type": "TEXT_MEMORY",
      "memoryLevel": "ORG",
      "isGlobal": false,
      "ingestionStatus": "IN_PROGRESS",
      "ingestionProgress": 0,
      "createdBy": "USER_ID",
      "updatedBy": "USER_ID",
      "createdAt": "2025-03-10T00:00:00.000Z",
      "updatedAt": "2025-03-10T00:00:00.000Z",
      "__v": 0
    },
    "warning": "Similar memory may already exist.",
    "similarBatchLinks": [
      "https://hana-dashboard.hanabitech.com/memories?batchId=EXISTING_MEMORY_BATCH_ID"
    ]
  }
}

Get Memory Batch

info

Retrieve a previously created memory batch using its batch ID.

Request Type

GET

Endpoint

https://hana-api.hanabitech.com/v1/expose-api/memory/{batchId}

cURL Example

curl -X GET "https://hana-api.hanabitech.com/v1/expose-api/memory/BATCH_ID" \
  -H "X-API-KEY: HANA-<YOUR_API_KEY>"

Response

{
  "success": true,
  "content": {
    "_id": "BATCH_ID",
    "title": "Initial planning",
    "organizationId": "ORG_ID",
    "type": "TEXT_MEMORY",
    "memoryLevel": "ORG",
    "isGlobal": false,
    "ingestionStatus": "INGESTED",
    "ingestionProgress": 100,
    "createdBy": "USER_ID",
    "updatedBy": "USER_ID",
    "createdAt": "2025-03-10T00:00:00.000Z",
    "updatedAt": "2025-03-10T00:05:00.000Z",
    "status": "ACTIVE",
    "effectiveSheetTotalRowLimit": 5000,
    "__v": 0
  }
}

Delete Memory Batch

info

Delete a memory batch owned by the authenticated user.

Request Type

DELETE

Endpoint

https://hana-api.hanabitech.com/v1/expose-api/memory/{batchId}

cURL Example

curl -X DELETE "https://hana-api.hanabitech.com/v1/expose-api/memory/BATCH_ID" \
  -H "X-API-KEY: HANA-<YOUR_API_KEY>"

Response

{
  "success": true,
  "content": true
}

Get URL Content

info

Fetch readable text from a web page. Available only to organizations on the PRO plan.

Request Type

GET

Endpoint

https://hana-api.hanabitech.com/v1/expose-api/get-url-content?url={URL}

cURL Example

curl -G "https://hana-api.hanabitech.com/v1/expose-api/get-url-content" \
  -H "X-API-KEY: HANA-<YOUR_API_KEY>" \
  --data-urlencode "url=https://example.com/article"

Response

{
  "success": true,
  "content": "# Article Title\n\nArticle body in Markdown format"
}

Get Memory Batches

info

List memory batches for the authenticated organization with optional filters.

Request Type

GET

Endpoint

https://hana-api.hanabitech.com/v1/expose-api/memory/batches?page={{PAGE_NUMBER}}&per_page={{PAGE_NUMBER_LIMIT}}&batchType={{MEMORY_BATCH_TYPE}}&status={{MEMORY_STATUS}}&memoryLevel={{MEMORY_LEVEL}}&search={{SEARCH_QUERY}}

Request Params

page (optional): page number, defaults to 1
per_page (optional): page size, defaults to 10, max 100
batchType (optional): memory batch type (for example TEXT_MEMORY)
status (optional): STALE | ACTIVE | FRESH
memoryLevel (optional): ORG | JUST_MYSELF
search (optional): text search query

cURL Example

curl -G "https://hana-api.hanabitech.com/v1/expose-api/memory/batches" \
  -H "X-API-KEY: HANA-<YOUR_API_KEY>" \
  --data-urlencode "page=1" \
  --data-urlencode "per_page=10" \
  --data-urlencode "batchType=TEXT_MEMORY" \
  --data-urlencode "status=ACTIVE" \
  --data-urlencode "memoryLevel=ORG" \
  --data-urlencode "search=planning"

Response

{
  "success": true,
  "content": {
    "data": [
      {
        "_id": "MEMORY_BATCH_ID",
        "type": "TEXT_MEMORY",
        "title": "Initial planning",
        "status": "ACTIVE",
        "ingestionStatus": "INGESTED",
        "ingestionProgress": 100,
        "memoryLevel": "ORG",
        "isGlobal": false,
        "memoryChunksCount": 3,
        "createdBy": {
          "_id": "USER_ID",
          "userID": "users/USER_ID",
          "email": "user@example.com",
          "displayName": "Alex Jones",
          "organizationId": "ORG_ID",
          "profilePicture": "https://example.com/user.jpg",
          "createdAt": "2025-02-10T11:22:33.000Z",
          "updatedAt": "2025-02-12T08:15:11.000Z",
          "__v": 0
        },
        "updatedBy": {
          "_id": "USER_ID",
          "userID": "users/USER_ID",
          "email": "user@example.com",
          "displayName": "Alex Jones",
          "organizationId": "ORG_ID",
          "profilePicture": "https://example.com/user.jpg",
          "createdAt": "2025-02-10T11:22:33.000Z",
          "updatedAt": "2025-02-12T08:15:11.000Z",
          "__v": 0
        },
        "createdAt": "2025-03-10T00:00:00.000Z",
        "updatedAt": "2025-03-10T00:05:00.000Z"
      }
    ],
    "totalCount": 1
  }
}

Create Task

info

Create a task in the authenticated organization.

Request Type

POST

Endpoint

https://hana-api.hanabitech.com/v1/expose-api/tasks

Payload

title (optional but recommended)
description (optional)
status (optional): TODO | IN_PROGRESS | COMPLETED | CANCELED
priority (optional): LOW | MEDIUM | HIGH | CRITICAL
due (optional): ISO timestamp
assignees (optional): array of user Mongo IDs
tags (optional): array of tag Mongo IDs
sprintId (optional): sprint Mongo ID

cURL Example

curl -X POST "https://hana-api.hanabitech.com/v1/expose-api/tasks" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: HANA-<YOUR_API_KEY>" \
  -d '{
    "title": "Finalize dashboard QA checklist",
    "status": "TODO",
    "priority": "HIGH",
    "due": "2026-02-28T18:30:00.000Z"
  }'

Response

{
  "success": true,
  "content": {
    "_id": "TASK_ID",
    "title": "Finalize dashboard QA checklist",
    "status": "TODO",
    "priority": "HIGH",
    "due": "2026-02-28T18:30:00.000Z",
    "organizationId": "ORG_ID",
    "createdBy": "USER_ID",
    "updatedBy": "USER_ID",
    "createdAt": "2026-02-19T12:11:10.000Z",
    "updatedAt": "2026-02-19T12:11:10.000Z",
    "__v": 0
  }
}

Get User By ID

info

Retrieve one user by Mongo user ID.

Request Type

GET

Endpoint

https://hana-api.hanabitech.com/v1/expose-api/users/{userId}

cURL Example

curl -X GET "https://hana-api.hanabitech.com/v1/expose-api/users/USER_ID" \
  -H "X-API-KEY: HANA-<YOUR_API_KEY>"

Response

{
  "success": true,
  "content": {
    "_id": "USER_ID",
    "userID": "users/12345678901234567890",
    "email": "user@example.com",
    "displayName": "Alex Jones",
    "organizationId": "ORG_ID",
    "role": "ADMIN",
    "isActive": true,
    "profilePicture": "https://example.com/user.jpg",
    "createdAt": "2025-02-10T11:22:33.000Z",
    "updatedAt": "2025-02-12T08:15:11.000Z",
    "__v": 0
  }
}

Get Organization

info

Retrieve the authenticated organization details associated with the API key.

Request Type

GET

Endpoint

https://hana-api.hanabitech.com/v1/expose-api/organization

cURL Example

curl -X GET "https://hana-api.hanabitech.com/v1/expose-api/organization" \
  -H "X-API-KEY: HANA-<YOUR_API_KEY>"

Response

{
  "success": true,
  "content": {
    "_id": "ORG_ID",
    "displayName": "Acme Inc.",
    "planId": {
      "_id": "PLAN_ID",
      "displayName": "PRO"
    },
    "purchasedSeats": 25,
    "country": "United States",
    "website": "https://acme.com",
    "allowDm": true,
    "allowThreadedSpaceInteraction": true,
    "allowAutoMemoryIngestion": true,
    "allowPrivateChat": true,
    "allowInvocationHistory": true,
    "allowAutoEngagement": false,
    "allowResponseControlCard": true,
    "allowResponseMetadata": true,
    "knowledgeValidationMode": "UNRESTRICTED",
    "preferredLanguage": "EN",
    "createdAt": "2025-02-01T10:00:00.000Z",
    "updatedAt": "2025-02-19T10:00:00.000Z",
    "__v": 0
  }
}

Create Approval

info

Create an approval request that can be tracked in dashboard and automation flows.

Request Type

POST

Endpoint

https://hana-api.hanabitech.com/v1/expose-api/approval/create-approval

Payload

content (required): text needing approval
approvers (required): non-empty array of approver user Mongo IDs
expiryDate (required): ISO timestamp, must be sufficiently in the future
defaultAction (required): APPROVED | REJECTED | NO_ACTION
images (optional): image URL array
links (optional): URL array
googleChatSpaceId (optional): target spaces/{...} for posting approval card

Automation-safe defaults

For high-risk actions (publishing, external sends, production changes), prefer defaultAction: "REJECTED" and a short expiryDate.

cURL Example

curl -X POST "https://hana-api.hanabitech.com/v1/expose-api/approval/create-approval" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: HANA-<YOUR_API_KEY>" \
  -d '{
    "content": "Approve publishing the Q1 launch announcement.",
    "approvers": ["USER_ID_1", "USER_ID_2"],
    "expiryDate": "2026-02-21T18:30:00.000Z",
    "defaultAction": "REJECTED",
    "links": ["https://docs.google.com/document/d/EXAMPLE"]
  }'

Response

{
  "success": true,
  "content": {
    "_id": "APPROVAL_ID",
    "content": "Approve publishing the Q1 launch announcement.",
    "approvers": ["USER_ID_1", "USER_ID_2"],
    "approverActions": {
      "USER_ID_1": {
        "action": "NO_ACTION",
        "actionDate": "2026-02-19T12:12:00.000Z"
      },
      "USER_ID_2": {
        "action": "NO_ACTION",
        "actionDate": "2026-02-19T12:12:00.000Z"
      }
    },
    "defaultAction": "REJECTED",
    "expiryDate": "2026-02-21T18:30:00.000Z",
    "organizationId": "ORG_ID",
    "createdBy": "USER_ID",
    "links": ["https://docs.google.com/document/d/EXAMPLE"],
    "createdAt": "2026-02-19T12:12:00.000Z",
    "updatedAt": "2026-02-19T12:12:00.000Z",
    "__v": 0
  }
}

How to Use in Zapier/API Flows

Create approval and store returned _id as approvalId.
Poll GET /approval/{approvalId} until:
- approvers act, or
- expiryDate is reached.
Evaluate outcome using approverActions + defaultAction.

Suggested decision patterns:

Any-approver approve: proceed if any approver action is APPROVED.
All-approver approve: proceed only if all approver actions are APPROVED.
Strict reject: fail fast if any approver action is REJECTED.
Timeout fallback: when expired and unresolved, apply defaultAction.

Get Approval By ID

info

Retrieve a single approval request by ID.

Request Type

GET

Endpoint

https://hana-api.hanabitech.com/v1/expose-api/approval/{approvalId}

cURL Example

curl -X GET "https://hana-api.hanabitech.com/v1/expose-api/approval/APPROVAL_ID" \
  -H "X-API-KEY: HANA-<YOUR_API_KEY>"

Response

{
  "success": true,
  "content": {
    "_id": "APPROVAL_ID",
    "content": "Approve publishing the Q1 launch announcement.",
    "approvers": [
      {
        "_id": "USER_ID_1",
        "userID": "users/USER_ID_1",
        "email": "manager@example.com",
        "displayName": "Manager",
        "organizationId": "ORG_ID",
        "profilePicture": "https://example.com/user.jpg",
        "createdAt": "2025-01-20T09:12:00.000Z",
        "updatedAt": "2026-02-01T08:00:00.000Z",
        "__v": 0
      }
    ],
    "approverActions": {
      "USER_ID_1": {
        "action": "NO_ACTION",
        "actionDate": "2026-02-20T10:00:00.000Z"
      }
    },
    "defaultAction": "REJECTED",
    "expiryDate": "2026-02-21T18:30:00.000Z",
    "createdBy": {
      "_id": "USER_ID",
      "userID": "users/USER_ID",
      "email": "owner@example.com",
      "displayName": "Owner",
      "organizationId": "ORG_ID",
      "profilePicture": "https://example.com/user.jpg",
      "createdAt": "2025-01-20T09:12:00.000Z",
      "updatedAt": "2026-02-01T08:00:00.000Z",
      "__v": 0
    },
    "organizationId": "ORG_ID",
    "links": ["https://docs.google.com/document/d/EXAMPLE"],
    "images": [],
    "createdAt": "2026-02-19T12:12:00.000Z",
    "updatedAt": "2026-02-19T12:12:00.000Z",
    "__v": 0
  }
}

Get Approvals

info

List approvals for the authenticated organization.

Request Type

GET

Endpoint

https://hana-api.hanabitech.com/v1/expose-api/approval?page={{PAGE_NUMBER}}&per_page={{PAGE_NUMBER_LIMIT}}

cURL Example

curl -G "https://hana-api.hanabitech.com/v1/expose-api/approval" \
  -H "X-API-KEY: HANA-<YOUR_API_KEY>" \
  --data-urlencode "page=1" \
  --data-urlencode "per_page=10"

Response

{
  "success": true,
  "content": {
    "data": [
      {
        "_id": "APPROVAL_ID",
        "content": "Approve publishing the Q1 launch announcement.",
        "approvers": [
          {
            "_id": "USER_ID_1",
            "userID": "users/USER_ID_1",
            "email": "manager@example.com",
            "displayName": "Manager",
            "organizationId": "ORG_ID",
            "profilePicture": "https://example.com/user.jpg",
            "createdAt": "2025-01-20T09:12:00.000Z",
            "updatedAt": "2026-02-01T08:00:00.000Z",
            "__v": 0
          }
        ],
        "createdBy": {
          "_id": "USER_ID",
          "userID": "users/USER_ID",
          "email": "owner@example.com",
          "displayName": "Owner",
          "organizationId": "ORG_ID",
          "profilePicture": "https://example.com/user.jpg",
          "createdAt": "2025-01-20T09:12:00.000Z",
          "updatedAt": "2026-02-01T08:00:00.000Z",
          "__v": 0
        },
        "defaultAction": "REJECTED",
        "expiryDate": "2026-02-21T18:30:00.000Z",
        "organizationId": "ORG_ID",
        "googleChatSpaceId": "spaces/AAAA1234xyz",
        "approverActions": {
          "USER_ID_1": { "action": "NO_ACTION", "actionDate": "2026-02-20T10:00:00.000Z" },
          "USER_ID_2": { "action": "APPROVED", "actionDate": "2026-02-20T10:12:00.000Z" }
        },
        "images": [],
        "links": ["https://docs.google.com/document/d/EXAMPLE"]
      }
    ],
    "totalCount": 1
  }
}

Performing approval actions

Approval actions (APPROVED / REJECTED) are taken by authorized approvers through Hana Dashboard Approvals or approval cards in Google Chat.

Authorization​

Auth Type​

How to Get Your API Key​

API Key Validation​

Request Type​

Endpoint​

cURL Example​

Success Response​

Chat Completion​

Request Type​

Endpoint​

Payload​

messages: Array of message - required​

Properties of a message​

cURL Example​

Response​

Chat Completion Status​

Request Type​

Endpoint​

Request Params​

cURL Example​

Response​

Completion in Progress​

Completion Completed​

Completion Error​

Report Message Creation​

Request Type​

Endpoint​

Payload​

cURL Example​

Response​

Create Google Chat Message​

Request Type​

Endpoint​

Payload​

How to Get the spaceName​

From Google Chat URL​

cURL Example​

Response​

Get Report Groups​

Request Type​

Endpoint​

Request Params​

cURL Example​

Response​

Get Report Group Messages​

Request Type​

Endpoint​

Request Params​

cURL Example​

Response​

Get Spaces Hana is Integrated In​

Request Type​

Endpoint​

Request Params​

cURL Example​

Response​

Get Users​

Request Type​

Endpoint​

Request Params​

cURL Example​

Response​

Create Memory​

Request Type​

Endpoint​

Payload​

cURL Example​

Response​

Get Memory Batch​

Request Type​

Endpoint​

cURL Example​

Response​

Delete Memory Batch​

Request Type​

Endpoint​

cURL Example​

Response​

Get URL Content​

Authorization

Auth Type

How to Get Your API Key

API Key Validation

Request Type

Endpoint

cURL Example

Success Response

Chat Completion

Request Type

Endpoint

Payload

`messages`: Array of `message` - required

Properties of a `message`

cURL Example

Response

Chat Completion Status

Request Type

Endpoint

Request Params

cURL Example

Response

Completion in Progress

Completion Completed

Completion Error

Report Message Creation

Request Type

Endpoint

Payload

cURL Example

Response

Create Google Chat Message

Request Type

Endpoint

Payload

How to Get the `spaceName`

From Google Chat URL

cURL Example

Response

Get Report Groups

Request Type

Endpoint

Request Params

cURL Example

Response

Get Report Group Messages

Request Type

Endpoint

Request Params

cURL Example

Response

Get Spaces Hana is Integrated In

Request Type

Endpoint

Request Params

cURL Example

Response

Get Users

Request Type

Endpoint

Request Params

cURL Example

Response

Create Memory

Request Type

Endpoint

Payload

cURL Example

Response

Get Memory Batch

Request Type

Endpoint

cURL Example

Response

Delete Memory Batch

Request Type

Endpoint

cURL Example

Response

Get URL Content