Skip to main content

​
Endpoint

POST /v1/budget/allocate

​
Authentication

Requires a developer API key in the Authorization header.

​
Request Headers

HeaderValue
AuthorizationBearer <api_key>
Content-Typeapplication/json

​
Request Body

FieldTypeRequiredDescription
grantIdstringYesThe grant to attach a budget to
initialBudgetnumberYesThe initial budget amount (must be positive)
currencystringNoCurrency code (default "USD")

​
Example Request

curl -X POST https://grantex-auth-dd4mtrt2gq-uc.a.run.app/v1/budget/allocate \
  -H "Authorization: Bearer gx_..." \
  -H "Content-Type: application/json" \
  -d '{
    "grantId": "grnt_01HXYZ...",
    "initialBudget": 100.00,
    "currency": "USD"
  }'

​
Response — 201 Created

{
  "id": "ba_01HXYZ...",
  "grantId": "grnt_01HXYZ...",
  "initialBudget": 100.00,
  "remainingBudget": 100.00,
  "currency": "USD",
  "createdAt": "2026-04-05T12:00:00.000Z"
}

​
Response Fields

FieldTypeDescription
idstringUnique budget allocation ID
grantIdstringThe grant this budget is attached to
initialBudgetnumberThe initial budget amount
remainingBudgetnumberCurrent remaining budget (equals initialBudget on creation)
currencystringCurrency code
createdAtstringISO-8601 creation timestamp

​
Error Responses

StatusCodeDescription
400BAD_REQUESTMissing grantId or initialBudget not positive
401UNAUTHORIZEDInvalid or missing API key
404NOT_FOUNDGrant not found or does not belong to developer
409CONFLICTBudget allocation already exists for this grant

​
SDK Examples

import Grantex from '@grantex/sdk';

const grantex = new Grantex({ apiKey: 'gx_...' });

const allocation = await grantex.budgets.allocate({
  grantId: 'grnt_01HXYZ...',
  initialBudget: 100.00,
  currency: 'USD',
});