API Documentation

The Number Adder API lets you perform organization and calculator-scoped operations, view calculator history, and manage your account programmatically.

Base URL: https://number-adder.com

Getting Started
Authentication
Primary Model
Endpoints
Errors

Getting Started

Create an account on Number Adder
Go to Admin
Click Generate API Key
Copy and save your key — it is only shown once

Your key will look like: na_a1b2c3d4e5f6...

Primary Model

The primary API model is calculator-scoped. Authenticate as a user, list the calculators you can access, then operate on a specific calculator.

curl https://number-adder.com/calculators \
  -H "X-API-Key: na_your_key_here"

Authentication

Include your API key in the X-API-Key header with every request:

curl https://number-adder.com/add \
  -H "X-API-Key: na_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"a": 2, "b": 3}'

All endpoints require authentication. Requests without a valid key return 401 Unauthorized.

Endpoints

GET /calculators

List all calculators the authenticated user can access across their organizations.

Example

curl https://number-adder.com/calculators \
  -H "X-API-Key: na_your_key_here"

POST /calculators/{calc_id}/add

Add two numbers using a specific calculator. The calculator determines the organization scope.

Request body

{
  "a": 5,
  "b": 3
}

Example

curl -X POST https://number-adder.com/calculators/123/add \
  -H "X-API-Key: na_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"a": 5, "b": 3}'

GET /calculators/{calc_id}/history

Get calculation history for one calculator.

Example

curl https://number-adder.com/calculators/123/history \
  -H "X-API-Key: na_your_key_here"

POST /add

Legacy endpoint for older integrations. New multi-tenant clients should prefer /calculators/{calc_id}/add.

Request body

{
  "a": 5,
  "b": 3
}

Response 200

{
  "a": 5,
  "b": 3,
  "result": 8
}

Example

curl -X POST https://number-adder.com/add \
  -H "X-API-Key: na_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"a": 5, "b": 3}'

POST /multiply PREMIUM

Multiply two numbers. Requires a premium subscription.

Request body

{
  "a": 4,
  "b": 7
}

Response 200

{
  "a": 4,
  "b": 7,
  "result": 28
}

Error 403 (not premium)

{
  "detail": "Premium subscription required. Use /create-checkout-session to upgrade."
}

Example

curl -X POST https://number-adder.com/multiply \
  -H "X-API-Key: na_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"a": 4, "b": 7}'

GET /history

Legacy endpoint for older integrations. New multi-tenant clients should prefer /calculators/{calc_id}/history.

Response 200

{
  "calculations": [
    {
      "id": 42,
      "operation": "add",
      "num_a": 5,
      "num_b": 3,
      "result": 8,
      "created_at": "2025-01-15 10:30:00"
    }
  ]
}

Example

curl https://number-adder.com/history \
  -H "X-API-Key: na_your_key_here"

GET /me

Get your account information.

Response 200

{
  "id": 1,
  "email": "user@example.com",
  "is_premium": 0,
  "stripe_customer_id": null,
  "created_at": "2025-01-01 00:00:00"
}

Example

curl https://number-adder.com/me \
  -H "X-API-Key: na_your_key_here"

GET /me/export

Export all your data as JSON (GDPR: Right to Portability).

Response 200

{
  "user": {
    "id": 1,
    "email": "user@example.com",
    "is_premium": false,
    "created_at": "2025-01-01 00:00:00"
  },
  "calculations": [ ... ],
  "export_timestamp": "2025-01-15T10:30:00"
}

Example

curl https://number-adder.com/me/export \
  -H "X-API-Key: na_your_key_here"

DELETE /me

Permanently delete your account and all associated data (GDPR: Right to Erasure). This action cannot be undone.

Response 200

{
  "message": "Account and all associated data deleted successfully"
}

Example

curl -X DELETE https://number-adder.com/me \
  -H "X-API-Key: na_your_key_here"

Errors

The API returns standard HTTP status codes. Error responses include a detail field with a human-readable message.

Status	Meaning
`400`	Bad request — invalid input or malformed JSON
`401`	Unauthorized — missing or invalid API key
`403`	Forbidden — premium subscription required (for `/multiply`)
`404`	Not found — resource does not exist
`422`	Validation error — request body failed validation

Error response format

{
  "detail": "Premium subscription required. Use /create-checkout-session to upgrade."
}

Number Adder API