integrations

Grant AI tokens to a case (internal)

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL

https://docs.usehearsay.com/mcp

Standard setup for AI tools providing an mcp.json file

mcp.json 
{
  "integrations MCP server": {
    "url": "https://docs.usehearsay.com/mcp"
  }
}
Close
POST /admin/billing/token-grants
Access token

Adds tokens to the case's AI token allowance and returns the new allowance and usage. When the organization is on case billing the grant also shows on its statement as a $0 item, and a repeated requestId does not grant again. Returns 404 for an unknown case. Super admin only.

application/json

Body Required

  • caseId string Required

    Id of the case to grant tokens on

  • tokens number Required

    Minimum value is 1.

  • reason string Required

    Required audit reason — persisted on the BillingEvent

  • requestId string

    Client-supplied dedup token — repeating the same requestId for the same case returns the prior grant untouched instead of granting a second time. Requires the organization to already have a BillingProfile to be enforced.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • data object Required
      Hide data attributes Show data attributes object
      • caseId string Required
      • granted number Required
      • allowance number Required
      • used number Required
    • statusCode number Required
    • timestamp string(date-time) Required
POST /admin/billing/token-grants 
curl \
 --request POST 'http://api.example.com/admin/billing/token-grants' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{
  "caseId": "string",
  "tokens": 42.0,
  "reason": "string",
  "requestId": "string"
}'
Request examples 
{
  "caseId": "string",
  "tokens": 42.0,
  "reason": "string",
  "requestId": "string"
}
Response examples (200) 
{
  "data": {
    "caseId": "65a1b2c3d4e5f6a7b8c9d0e2",
    "granted": 1000000,
    "allowance": 3000000,
    "used": 250000
  },
  "statusCode": 200,
  "timestamp": "2026-01-15T10:15:00.000Z"
}