Fuel API (1.0.0)

Download OpenAPI specification:

API for credit and wallet management.

Node.js / Edge SDK

The official server SDK is available at https://www.npmjs.com/package/@underspark/fuel-node.

Authentication

All API requests require an API Key. Include it in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Getting an API Key

Sign in to the UnderSpark Developer Console
Select an organization and open Fuel API
Create the Fuel API database, then generate a key from API Keys

認証 (日本語)

すべてのAPIリクエストにはAPIキーが必要です。Authorizationヘッダーに含めてください：

Authorization: Bearer YOUR_API_KEY

APIキーの取得方法

UnderSpark Developer Console にサインイン
Organizationを選択して Fuel API を開く
Fuel API用DBを作成し、API Keys からキーを発行

/v1/users

Authorizations:

BearerAuth

Request Body schema: application/json

userId

required

string [ 1 .. 128 ] characters ^[a-zA-Z0-9_-]+$

email

string <email>

name

string

object

property name*

additional property

any

Responses

Request samples

Payload

Content type

application/json

{"userId": "string",
"email": "user@example.com",
"name": "string",
"metadata": {"property1": null,
"property2": null
}
}

Response samples

200
400
401

Content type

application/json

{"userId": "string",
"metadata": {"property1": null,
"property2": null
},
"createdAt": "2019-08-24T14:15:22Z",
"isNew": true
}

/v1/wallets/{id}

Authorizations:

BearerAuth

path Parameters

id

required

string [ 1 .. 128 ] characters ^[a-zA-Z0-9_-]+$

Example: user_123

Responses

Response samples

200
400
401

Content type

application/json

{"buckets": [{"bucketId": "string",
"userId": "string",
"remainingAmount": 0,
"expiresAt": "2019-08-24T14:15:22Z"
}
],
"events": [{"eventId": "string",
"eventType": "string",
"amount": 0,
"reason": "string",
"actor": "string",
"occurredAt": "2019-08-24T14:15:22Z"
}
]
}

/v1/wallets/{id}/charge

Authorizations:

BearerAuth

path Parameters

id

required

string [ 1 .. 128 ] characters ^[a-zA-Z0-9_-]+$

Example: user_123

Request Body schema: application/json

amount

required

number >= 1

reason

required

string

object

property name*

additional property

any

actor

string

Responses

Request samples

Payload

Content type

application/json

{"amount": 1,
"reason": "string",
"metadata": {"property1": null,
"property2": null
},
"actor": "string"
}

Response samples

200
400
401

Content type

application/json

{"success": true,
"deducted": 0,
"remainingBalance": 0,
"details": [{"bucketId": "string",
"amount": 0
}
]
}

/v1/wallets/{id}/reserve

Authorizations:

BearerAuth

path Parameters

id

required

string [ 1 .. 128 ] characters ^[a-zA-Z0-9_-]+$

Example: user_123

Request Body schema: application/json

amount

required

number >= 1

reason

required

string

ttl

number

object

property name*

additional property

any

actor

string

Responses

Request samples

Payload

Content type

application/json

{"amount": 1,
"reason": "string",
"ttl": 0,
"metadata": {"property1": null,
"property2": null
},
"actor": "string"
}

Response samples

200
400
401

Content type

application/json

{"success": true,
"reservationId": "string",
"expiresAt": "2019-08-24T14:15:22Z"
}

/v1/wallets/{id}/commit

Authorizations:

BearerAuth

path Parameters

id

required

string [ 1 .. 128 ] characters ^[a-zA-Z0-9_-]+$

Example: user_123

Request Body schema: application/json

reservationId required	string
amount	number

Responses

Request samples

Payload

Content type

application/json

{"reservationId": "string",
"amount": 0
}

Response samples

200
400
401

Content type

application/json

{"success": true,
"deducted": 0,
"remainingBalance": 0
}

/v1/wallets/{id}/rollback

Authorizations:

BearerAuth

path Parameters

id

required

string [ 1 .. 128 ] characters ^[a-zA-Z0-9_-]+$

Example: user_123

Request Body schema: application/json

reservationId

required

string

Responses

Request samples

Payload

Content type

application/json

{"reservationId": "string"
}

Response samples

200
400
401

Content type

application/json

{"success": true
}

/v1/wallets/{id}/balance

Authorizations:

BearerAuth

path Parameters

id

required

string [ 1 .. 128 ] characters ^[a-zA-Z0-9_-]+$

Example: user_123

Responses

Response samples

200
400
401

Content type

application/json

{"balance": 1500
}

/v1/wallets/{id}/grant

Authorizations:

BearerAuth

path Parameters

id

required

string [ 1 .. 128 ] characters ^[a-zA-Z0-9_-]+$

Example: user_123

Request Body schema: application/json

amount

required

number >= 1

reason

required

string

expiresAt

string <date-time>

sourceType

string

object

property name*

additional property

any

actor

string

Responses

Request samples

Payload

Content type

application/json

{"amount": 1,
"reason": "string",
"expiresAt": "2019-08-24T14:15:22Z",
"sourceType": "string",
"metadata": {"property1": null,
"property2": null
},
"actor": "string"
}

Response samples

200
400
401

Content type

application/json

{"success": true,
"bucketId": "string",
"granted": 0,
"expiresAt": "2019-08-24T14:15:22Z"
}

/v1/wallets/{id}/cleanup

Authorizations:

BearerAuth

path Parameters

id

required

string [ 1 .. 128 ] characters ^[a-zA-Z0-9_-]+$

Example: user_123

Responses

Response samples

200
400
401

Content type

application/json

{"success": true
}

/v1/campaigns

Authorizations:

BearerAuth

Request Body schema: application/json

name required	string
triggerEvent required	string
rewardType required	string Enum: "fixed_amount" "percent"
rewardValue required	number
rewardAsset required	string

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"triggerEvent": "string",
"rewardType": "fixed_amount",
"rewardValue": 0,
"rewardAsset": "string"
}

Response samples

200
401

Content type

application/json

{"id": 0,
"name": "string",
"triggerEvent": "string",
"rewardType": "fixed_amount",
"rewardValue": 0,
"rewardAsset": "string",
"isActive": true,
"createdAt": "2019-08-24T14:15:22Z"
}

/v1/campaigns

Authorizations:

BearerAuth

Responses

Response samples

200
401

Content type

application/json

[{"id": 0,
"name": "string",
"triggerEvent": "string",
"rewardType": "fixed_amount",
"rewardValue": 0,
"rewardAsset": "string",
"isActive": true,
"createdAt": "2019-08-24T14:15:22Z"
}
]

/v1/referral-codes

Authorizations:

BearerAuth

Request Body schema: application/json

code

required

string

campaignId

number

object

property name*

additional property

any

userId

required

string

Responses

Request samples

Payload

Content type

application/json

{"code": "string",
"campaignId": 0,
"metadata": {"property1": null,
"property2": null
},
"userId": "string"
}

Response samples

200
401

Content type

application/json

{"id": 0,
"code": "string",
"userId": "string",
"campaignId": 0,
"metadata": {"property1": null,
"property2": null
},
"isActive": true,
"createdAt": "2019-08-24T14:15:22Z"
}

/v1/referral-codes

Authorizations:

BearerAuth

Responses

Response samples

200
401

Content type

application/json

[{"id": 0,
"code": "string",
"userId": "string",
"campaignId": 0,
"metadata": {"property1": null,
"property2": null
},
"isActive": true,
"createdAt": "2019-08-24T14:15:22Z"
}
]

/v1/track/click

Authorizations:

BearerAuth

Request Body schema: application/json

referralCode

required

string

url

string

referrer

string

object

property name*

additional property

any

Responses

Request samples

Payload

Content type

application/json

{"referralCode": "string",
"url": "string",
"referrer": "string",
"metadata": {"property1": null,
"property2": null
}
}

Response samples

200

Content type

application/json

{"success": true
}

/v1/track/conversion

Authorizations:

BearerAuth

Request Body schema: application/json

referralCode

required

string

uniqueId

required

string

eventType

required

string

amount

number

object

property name*

additional property

any

Responses

Request samples

Payload

Content type

application/json

{"referralCode": "string",
"uniqueId": "string",
"eventType": "string",
"amount": 0,
"metadata": {"property1": null,
"property2": null
}
}

Response samples

200
400

Content type

application/json

{"success": true,
"rewardId": 0
}

/v1/affiliates/{id}/stats

Authorizations:

BearerAuth

Responses

Response samples

200

Content type

application/json

{"clicks": 0,
"conversions": 0,
"totalEarned": 0,
"pendingPayout": 0
}

/v1/affiliates/{id}/conversions

Authorizations:

BearerAuth

Responses

Response samples

200

Content type

application/json

[{"id": 0,
"campaignId": 0,
"eventType": "string",
"status": "pending",
"rewardAmount": 0,
"createdAt": "2019-08-24T14:15:22Z"
}
]

/v1/affiliates/{id}/rewards

Authorizations:

BearerAuth

Responses

Response samples

200

Content type

application/json

[{"id": 0,
"amount": 0,
"asset": "string",
"status": "pending",
"createdAt": "2019-08-24T14:15:22Z"
}
]

/v1/affiliates/{id}/payouts/request

Authorizations:

BearerAuth

Request Body schema: application/json

amount

required

number >= 1

Responses

Request samples

Payload

Content type

application/json

{"amount": 1
}

Response samples

200
400

Content type

application/json

{"success": true,
"payoutId": 0
}

/v1/campaigns/stats

Authorizations:

BearerAuth

Responses

Response samples

200
401

Content type

application/json

{"activeCampaigns": 0,
"totalConversions": 0,
"totalRewards": 0,
"pendingPayouts": 0
}

/v1/conversions

Authorizations:

BearerAuth

Responses

Response samples

200
401

Content type

application/json

[{"id": 0,
"campaignId": 0,
"eventType": "string",
"status": "pending",
"rewardAmount": 0,
"createdAt": "2019-08-24T14:15:22Z"
}
]

/v1/points/{userId}/grant

Authorizations:

BearerAuth

path Parameters

userId

required

string [ 1 .. 128 ] characters ^[a-zA-Z0-9_-]+$

Request Body schema: application/json

amount

required

number > 0

reason

required

string non-empty

tag

string

object

property name*

additional property

any

Responses

Request samples

Payload

Content type

application/json

{"amount": 100,
"reason": "Daily login bonus",
"tag": "login_bonus"
}

Response samples

200

Content type

application/json

{"success": true,
"balance": 0,
"granted": 0
}

/v1/points/{userId}/spend

Authorizations:

BearerAuth

path Parameters

userId

required

string [ 1 .. 128 ] characters ^[a-zA-Z0-9_-]+$

Request Body schema: application/json

amount

required

number > 0

reason

required

string non-empty

object

property name*

additional property

any

Responses

Request samples

Payload

Content type

application/json

{"amount": 50,
"reason": "Item purchase"
}

Response samples

200

Content type

application/json

{"success": true,
"balance": 0,
"spent": 0
}

/v1/points/{userId}/balance

Authorizations:

BearerAuth

path Parameters

userId

required

string [ 1 .. 128 ] characters ^[a-zA-Z0-9_-]+$

Responses

Response samples

200
400
500

Content type

application/json

{"balance": 1500,
"totalEarned": 2000,
"totalSpent": 500,
"lastEarnedAt": "2025-01-15T10:30:00Z",
"lastSpentAt": "2025-01-14T08:00:00Z",
"expiresAt": null
}

/v1/points/{userId}/events

Authorizations:

BearerAuth

path Parameters

userId

required

string [ 1 .. 128 ] characters ^[a-zA-Z0-9_-]+$

query Parameters

limit	number or null Default: 50
offset	number or null Default: 0
tag	string

Responses

Response samples

200
400
500

Content type

application/json

{"events": [{"eventId": "string",
"eventType": "grant",
"amount": 0,
"balanceAfter": 0,
"reason": "string",
"tag": "string",
"actor": "string",
"occurredAt": "string",
"metadata": {"property1": null,
"property2": null
}
}
],
"total": 0
}

/v1/points/{userId}/stats

Authorizations:

BearerAuth

path Parameters

userId

required

string [ 1 .. 128 ] characters ^[a-zA-Z0-9_-]+$

query Parameters

from	string
to	string

Responses

Response samples

200
400
500

Content type

application/json

{"stats": [{"yearMonth": "string",
"earnedTotal": 0,
"spentTotal": 0
}
]
}