API Reference

The Solenoid API v1 provides atomic credit metering, key rotation, and usage tracking over HTTPS.

Base URL

https://api.solenoid.systems

All endpoints require a Bearer token. See Authentication.

Meter Endpoints

Multi-tenant endpoints at /v1/meter/:meterId/* let you manage per-user meters. Each meterId is alphanumeric with dashes and underscores (max 64 characters). Meters are created implicitly on first use.

GET /v1/meter/:meterId/balance

Returns the current balance of an end-user meter.

curl https://api.solenoid.systems/v1/meter/user-123/balance \
  -H "Authorization: Bearer sm_your_api_key_here"

Response (200):

{
  "balance": 500,
  "meter_id": "user-123"
}

Errors: 401 Invalid or missing API key

POST /v1/meter/:meterId/deduct

Atomically deducts credits from an end-user meter. If the balance is insufficient, no deduction occurs and a 402 is returned.

curl -X POST https://api.solenoid.systems/v1/meter/user-123/deduct \
  -H "Authorization: Bearer sm_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"amount": 5}'

Request body:

Response (200):

{
  "balance": 495,
  "meter_id": "user-123"
}

Error (402) — insufficient balance:

{
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient balance for this operation"
  },
  "balance": 0,
  "meter_id": "user-123"
}

Other errors:

• 400 — amount must be a positive number
• 401 — invalid or missing API key

POST /v1/meter/:meterId/refill

Add credits to an end-user meter.

curl -X POST https://api.solenoid.systems/v1/meter/user-123/refill \
  -H "Authorization: Bearer sm_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"amount": 100}'

Request body:

Response (200):

{
  "balance": 600,
  "meter_id": "user-123"
}

POST /v1/meter/:meterId/reset

Set an end-user meter to an exact balance.

curl -X POST https://api.solenoid.systems/v1/meter/user-123/reset \
  -H "Authorization: Bearer sm_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"balance": 1000}'

Request body:

Response (200):

{
  "balance": 1000,
  "meter_id": "user-123"
}

POST /v1/keys/rotate

Rotates your API key. The old key is immediately invalidated.

curl -X POST https://api.solenoid.systems/v1/keys/rotate \
  -H "Authorization: Bearer sm_old_key_here"

Response (200):

{
  "key": "sm_new_key_here"
}

Store the new key securely. The old key no longer works.

Errors: 401 Invalid or missing API key

Response Format

All responses are flat JSON objects with no envelope wrapper.

• Success — contains the requested data directly
• Error — includes an error object with code (machine-readable) and message (human-readable)
• Some errors include additional context (e.g., balance in insufficient balance errors)

Rate Limits

Exceeding the limit returns 429 Too Many Requests with a Retry-After header.

Credit Costs

Each API call deducts credits from your account balance. Free-tier users receive a monthly allocation; paid tiers receive more. See Pricing for allocations.

Credits are deducted before the request executes. If your balance is insufficient, the request returns 402 Insufficient Balance.

Atomicity Guarantees

All operations are atomic, powered by stateful edge storage:

• Deduct — balance check and deduction happen in a single atomic step, no race conditions
• Refill — credit addition is atomic
• Concurrent requests — serialized per user, correct balance guaranteed

This eliminates double-spend issues under high concurrency.