openapi: 3.2.0
info:
title: Bitculator Data Alarms API
description: 'Programmatic access to Bitculator market data: coins, prices, history, exchanges, trust scores, tickers, pairs, wallets, sentiment, technical indicators, liquidations, editorial content, and calculators.'
version: 1.0.0
servers:
- url: https://bitculator.com
security:
- default: []
tags:
- name: Alarms
description: 'Price-alarm CRUD — the same alarms the web app manages. Alarms consume the key
owner''s alarm inventory balance, are TARGET-type on coins only, and an above/below
vs current-value guard blocks alarms that would self-trigger instantly. Key-scoped
(the API key sets the owner) and never response-cached.'
paths:
/api/v1/alarms:
get:
summary: List alarms
operationId: listAlarms
description: 'The key owner''s alarms, newest first, paginated. Filter by `status`, `direction`
or `notification` channel.'
parameters:
- in: query
name: page
description: Page number (1-based).
example: 1
required: false
schema:
type:
- integer
- 'null'
description: Page number (1-based).
example: 1
- in: query
name: per_page
description: Rows per page (1–100, default 25).
example: 25
required: false
schema:
type:
- integer
- 'null'
description: Rows per page (1–100, default 25).
example: 25
- in: query
name: status
description: 'Filter by state: `active` or `triggered`.'
example: active
required: false
schema:
type:
- string
- 'null'
description: 'Filter by state: `active` or `triggered`.'
example: active
- in: query
name: direction
description: 'Filter by trigger direction: `above` or `below`.'
example: above
required: false
schema:
type:
- string
- 'null'
description: 'Filter by trigger direction: `above` or `below`.'
example: above
- in: query
name: notification
description: 'Filter by delivery channel: `email`, `push` or `webhook`.'
example: email
required: false
schema:
type:
- string
- 'null'
description: 'Filter by delivery channel: `email`, `push` or `webhook`.'
example: email
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
example:
data:
- id: 42
name: BTC six figures
coin:
slug: bitcoin
symbol: BTC
name: Bitcoin
metric: rate
direction: above
target: '100000'
notification: email
status: active
created_at: '2026-06-21T09:15:00+00:00'
meta:
current_page: 1
per_page: 25
total: 3
last_page: 1
properties:
data:
type: array
example:
- id: 42
name: BTC six figures
coin:
slug: bitcoin
symbol: BTC
name: Bitcoin
metric: rate
direction: above
target: '100000'
notification: email
status: active
created_at: '2026-06-21T09:15:00+00:00'
items:
type: object
properties:
id:
type: integer
example: 42
name:
type: string
example: BTC six figures
coin:
type: object
properties:
slug:
type: string
example: bitcoin
symbol:
type: string
example: BTC
name:
type: string
example: Bitcoin
metric:
type: string
example: rate
direction:
type: string
example: above
target:
type: string
example: '100000'
notification:
type: string
example: email
status:
type: string
example: active
created_at:
type: string
example: '2026-06-21T09:15:00+00:00'
meta:
type: object
properties:
current_page:
type: integer
example: 1
per_page:
type: integer
example: 25
total:
type: integer
example: 3
last_page:
type: integer
example: 1
tags:
- Alarms
post:
summary: Create an alarm
operationId: createAnAlarm
description: 'Creates a TARGET alarm on a coin and spends one alarm slot from the key owner''s
balance. The target is checked against the coin''s current value so the alarm
cannot self-trigger instantly: an `above` alarm must target more than the current
value, a `below` alarm less.'
parameters: []
responses:
'201':
description: ''
content:
application/json:
schema:
type: object
example:
data:
id: 43
name: BTC six figures
coin:
slug: bitcoin
symbol: BTC
name: Bitcoin
metric: rate
direction: above
target: '100000'
notification: email
status: active
created_at: '2026-07-03T08:00:00+00:00'
properties:
data:
type: object
properties:
id:
type: integer
example: 43
name:
type: string
example: BTC six figures
coin:
type: object
properties:
slug:
type: string
example: bitcoin
symbol:
type: string
example: BTC
name:
type: string
example: Bitcoin
metric:
type: string
example: rate
direction:
type: string
example: above
target:
type: string
example: '100000'
notification:
type: string
example: email
status:
type: string
example: active
created_at:
type: string
example: '2026-07-03T08:00:00+00:00'
tags:
- Alarms
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: A label for the alarm (max 255 characters).
example: BTC six figures
coin:
type: string
description: The coin's slug identifier.
example: bitcoin
metric:
type: string
description: 'The watched metric: `rate`, `volume` or `marketcap`.'
example: rate
direction:
type: string
description: 'Trigger direction: `above` or `below`.'
example: above
target:
type: number
description: The threshold value (must sit on the `direction` side of the coin's current value).
example: 100000
notification:
type: string
description: 'Delivery channel: `email`, `push` or `webhook`.'
example: email
required:
- name
- coin
- metric
- direction
- target
- notification
/api/v1/alarms/{id}:
parameters:
- in: path
name: id
description: The alarm id.
example: 42
required: true
schema:
type: integer
delete:
summary: Delete an alarm
operationId: deleteAnAlarm
description: Deletes one of the key owner's alarms and refunds the alarm slot it consumed.
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
example:
data:
deleted: true
properties:
data:
type: object
properties:
deleted:
type: boolean
example: true
tags:
- Alarms
components:
securitySchemes:
default:
type: http
scheme: bearer
description: Create a Data API key in your developer console — keys are Bearer-only and carry the data-api ability. Keep them server-side; they are never meant for client-side embedding.