ArkWatch API Documentation

Base URL: https://watch.arkforge.fr

Quick Start

Register — POST /api/v1/auth/register with your email to get an API key
Verify — Check your email for a 6-digit code, then POST /api/v1/auth/verify-email
Create a watch — POST /api/v1/watches with a URL to monitor
Get reports — GET /api/v1/reports to retrieve AI-generated change summaries

All authenticated requests require the header: Authorization: Bearer YOUR_API_KEY

Authentication

POST /api/v1/auth/register Register & get API key

Create a free account. Returns an API key immediately.

Request:

{

  "email": "you@example.com",

  "name": "Your Name",

  "privacy_accepted": true

}

Response:

{

  "api_key": "ak_...",

  "email": "you@example.com",

  "tier": "free",

  "message": "Check your email for verification code"

}

Rate limited: 3 registrations per hour per IP.

POST /api/v1/auth/verify-email Verify email with code

Verify your email using the 6-digit code sent to your inbox.

Request:

{

  "email": "you@example.com",

  "code": "123456"

}

Watches

POST /api/v1/watches Auth Create a new watch

Start monitoring a URL. Requires a verified account.

Request:

{

  "url": "https://example.com/pricing",

  "name": "Competitor pricing page",

  "check_interval": 3600,

  "notify_email": "alerts@example.com",

  "min_change_ratio": 0.05

}

check_interval: seconds between checks (min depends on tier). min_change_ratio: 0.0–1.0, minimum change % to trigger notification (default 5%).

GET /api/v1/watches Auth List your watches

Returns all watches for your account. Optional query: ?status=active

GET /api/v1/watches/{watch_id} Auth Get a specific watch

Returns details for a single watch. You must own the watch.

PATCH /api/v1/watches/{watch_id} Auth Update a watch

Update watch settings. All fields optional.

{

  "name": "New name",

  "check_interval": 1800,

  "notify_email": "new@example.com",

  "status": "paused",

  "min_change_ratio": 0.1

}

DELETE /api/v1/watches/{watch_id} Auth Delete a watch

Permanently delete a watch and all its reports.

Reports

GET /api/v1/reports Auth List change reports

Returns AI-generated change reports for your watches.

Query params: ?watch_id=xxx (filter by watch), ?limit=100

Report fields include:

{

  "id": "rpt_...",

  "watch_id": "w_...",

  "changes_detected": true,

  "change_ratio": 0.12,

  "ai_summary": "Pricing increased by 20% on Pro tier...",

  "checked_at": "2026-02-06T10:00:00Z"

}

GET /api/v1/reports/{report_id} Auth Get a specific report

Returns full details for a single change report.

Billing

GET /api/v1/billing/subscription Auth Get subscription status

Returns your current tier, subscription status, and billing period.

POST /api/v1/billing/checkout Auth Upgrade your plan

Creates a Stripe checkout session to upgrade.

{ "tier": "pro" } // starter, pro, or business

GET /api/v1/billing/usage Auth Check usage & limits

Returns current usage vs. your tier limits (watches, API calls, check intervals).

Account Management (GDPR)

GET /api/v1/auth/account/data Auth Export your data (Art. 15)

Export all your personal data: account info, watches, and reports.

PATCH /api/v1/auth/account Auth Update your account (Art. 16)

Update your account information (e.g. name).

{ "name": "New Name" }

DELETE /api/v1/auth/account Auth Delete your account (Art. 17)

Permanently delete your account and all associated data (watches, reports, credentials).

Tier Limits

Feature	Free	Starter	Pro (9€/mo)	Business (29€/mo)
Watches	3	10	50	1,000
Min check interval	24h	1h	5 min	1 min
API calls/day	1,000	Unlimited	Unlimited	Unlimited
AI summaries	Yes	Yes	Yes	Yes
Email alerts	Yes	Yes	Yes	Yes

Errors

All errors follow a consistent format:

{ "detail": "Error description" }

Status	Meaning
`401`	Missing or invalid API key
`403`	Email not verified or insufficient permissions
`404`	Resource not found
`422`	Invalid request body
`429`	Rate limit exceeded