Platform API

Credits, spending caps, API key management, and account details.

GET /v1/credits

Get your current credit balance and spending cap status. Requires credits:read scope.

Response fields

Field	Type	Description
`balance.micro`	integer	Balance in microdollars (1 microdollar = $0.000001).
`balance.display`	string	Human-readable balance (e.g. `"$9.75"`).
`balance.currency`	string	Always `"USD"`.
`caps.organization`	object	Organization-level spending cap and usage.
`caps.project`	object \| null	Project-level spending cap (if set).
`caps.key`	object \| null	API key-level spending cap (if set).

Code examples

curl

curl https://api.fairstack.ai/v1/credits \
  -H "Authorization: Bearer $FAIRSTACK_API_KEY"

Python

from fairstack import FairStack

client = FairStack(api_key="fs_live_YOUR_KEY")

balance = client.credits.get()
print(balance.display)  # "$9.75"
print(balance.micro)    # 9750000

Node.js

import { FairStack } from "fairstack";

const client = new FairStack({ apiKey: "fs_live_YOUR_KEY" });

const balance = await client.credits.get();
console.log(balance.display);  // "$9.75"
console.log(balance.micro);    // 9750000

Response

{
  "balance": {
    "micro": 9750000,
    "display": "$9.75",
    "currency": "USD"
  },
  "caps": {
    "organization": { "micro": 100000000, "display": "$100.00", "used_micro": 250000 },
    "project": null,
    "key": { "micro": 10000000, "display": "$10.00", "used_micro": 250000 }
  }
}

GET /v1/api-keys

List your API keys and their scopes. The full key value is never returned after creation.

Response fields

Field	Type	Description
`id`	string	Key identifier.
`name`	string	Display name you assigned.
`prefix`	string	First 12 characters for identification.
`scopes`	string[]	Permitted actions for this key.
`cap_total_micro`	integer \| null	Spending cap in microdollars (null = unlimited).
`created_at`	string	ISO 8601 creation timestamp.
`last_used_at`	string \| null	Last request timestamp.

Response

{
  "keys": [
    {
      "id": "key_abc123",
      "name": "production",
      "prefix": "fs_live_abc1...",
      "scopes": ["generate", "assets:read", "credits:read"],
      "cap_total_micro": 10000000,
      "created_at": "2026-02-15T10:00:00Z",
      "last_used_at": "2026-03-10T14:30:00Z"
    },
    {
      "id": "key_def456",
      "name": "agent-image-gen",
      "prefix": "fs_live_def4...",
      "scopes": ["generate"],
      "cap_total_micro": 5000000,
      "created_at": "2026-03-01T08:00:00Z",
      "last_used_at": "2026-03-10T12:00:00Z"
    }
  ]
}

POST /v1/api-keys

Create a new API key with specific scopes and an optional spending cap. The full key value is returned only in this response -- store it securely.

Request body

Field	Type	Required	Description
`name`	string	Yes	Display name for the key (e.g. `"production"`, `"staging"`).
`scopes`	string[]	Yes	List of scopes: `"generate"`, `"assets:read"`, `"assets:delete"`, `"credits:read"`.
`cap_total_micro`	integer	No	Spending cap in microdollars. Omit for unlimited.

curl

curl -X POST https://api.fairstack.ai/v1/api-keys \
  -H "Authorization: Bearer $FAIRSTACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-agent","scopes":["generate","credits:read"],"cap_total_micro":10000000}'

Python

# Create a scoped API key with a $10 spending cap
key = client.api_keys.create(
    name="my-agent",
    scopes=["generate", "credits:read"],
    cap_total_micro=10_000_000  # $10.00
)
print(key.key)  # fs_live_ghi789... (shown only once)

Node.js

// Create a scoped API key with a $10 spending cap
const key = await client.apiKeys.create({
  name: "my-agent",
  scopes: ["generate", "credits:read"],
  capTotalMicro: 10_000_000, // $10.00
});
console.log(key.key); // fs_live_ghi789... (shown only once)

Response

{
  "id": "key_ghi789",
  "name": "my-agent",
  "key": "fs_live_ghi789xxxxxxxxxxxxxxxxxxxxxxxx",
  "scopes": ["generate", "credits:read"],
  "cap_total_micro": 10000000,
  "created_at": "2026-03-10T15:00:00Z"
}

Save the key immediately. The full key value is only shown once. If lost, delete this key and create a new one.

DELETE /v1/api-keys/:id

Revoke an API key. This is permanent and takes effect immediately.

curl -X DELETE https://api.fairstack.ai/v1/api-keys/key_abc123 \
  -H "Authorization: Bearer $FAIRSTACK_API_KEY"

Returns 204 No Content on success.

Spending caps

FairStack supports three levels of spending caps to prevent runaway costs:

Level	What it limits	When to use
Organization	Total spend across all keys	Overall budget control
Project	Spend within a project	Multi-team organizations
API key	Spend for a single key	Agent keys, per-use-case limits

When a cap is reached, generation requests return 402 Payment Required with the cap details in the error response.

Next steps

Authentication -- API key scopes and security best practices
Usage API -- track generation history and spending
Error Handling -- handling 402 and other errors

Models API Usage API