REST API Reference

Submit URL-checking jobs over JSON, poll for completion, fetch paginated results. Standard bearer-token auth, OpenAPI spec published, five endpoints. Same backend as the web UI and the MCP integration.

Create API key →OpenAPI spec Postman collection Recipes →Want MCP instead? →

Authentication

Every request must carry an Authorization: Bearer uck_live_YOUR_KEY header. Generate a key from the dashboard , we show the plaintext value once, then store only an irreversible hash. Lose it and you regenerate, no recovery.

Quickstart

Pythonpip install bulkurlcheckerPyPI →GitHub →

Node.jsnpm install bulkurlcheckernpm →GitHub →

1# pip install bulkurlchecker
2from bulkurlchecker import Client
3
4client = Client(api_key="uck_live_YOUR_KEY")
5results = client.check_urls([
6    "https://example.com",
7    "https://example.org",
8])
9
10for r in results.results:
11    print(r.status_code, r.url, "BROKEN" if r.is_broken else "ok")
12
13# Broken-link convenience accessor:
14broken = results.broken  # list of URLResult where is_broken == True

Endpoints

Method	Path	Description
POST	/api/v2/jobs	Submit URLs. Returns job_id. Idempotency-Key supported.
GET	/api/v2/jobs/{id}	Status + progress.
GET	/api/v2/jobs/{id}/results	Paginated results (limit/offset or cursor).
DELETE	/api/v2/jobs/{id}	Cancel + refund unchecked credits.
GET	/api/v2/usage	Current credit balance.
POST	/api/v2/webhooks/endpoints	Register an outbound webhook URL.
GET	/api/v2/webhooks/endpoints	List your webhook endpoints.
DELETE	/api/v2/webhooks/endpoints/{id}	Revoke a webhook endpoint.

POST/api/v2/jobs
Submit URLs. Returns job_id. Idempotency-Key supported.
GET/api/v2/jobs/{id}
Status + progress.
GET/api/v2/jobs/{id}/results
Paginated results (limit/offset or cursor).
DELETE/api/v2/jobs/{id}
Cancel + refund unchecked credits.
GET/api/v2/usage
Current credit balance.
POST/api/v2/webhooks/endpoints
Register an outbound webhook URL.
GET/api/v2/webhooks/endpoints
List your webhook endpoints.
DELETE/api/v2/webhooks/endpoints/{id}
Revoke a webhook endpoint.

Full request/response schemas, error codes, and examples are in the OpenAPI spec. Drop it into Postman, Stoplight, or the SDK generator of your choice.

Pagination

GET /api/v2/jobs/{id}/results supports two modes. Offset/limit is the default (?limit=100&offset=200): simple but page contents shift if results land mid-export. Cursor is stable under concurrent writes (recommended for full exports of big jobs): pass ?cursor= from a previous response's next_cursor field. next_cursor: null means the last page.

Cursor: opaque, stable id-asc, immune to result-landing race conditions. Use for full exports.
Offset: classic limit + offset. Use when you only need the first page or a fixed window.
Page size: up to 1000 per request. SDKs default to 1000; iter_results() / iterResults() use cursor mode under the hood.

Idempotency

Send an Idempotency-Key header on POST /api/v2/jobs to make retries safe. Generate one UUIDv4 per logical request and reuse it on retries. If the network fails mid-call and you retry with the same key within 24 hours, you get back the original response without creating a duplicate job.

Same key, same body: returns the cached response (same job_id, same credits allocated).
Same key, different body: returns 409 Conflict with error.code = "idempotency_key_mismatch". Use a new key for a new request.
TTL: 24 hours. After that the key can be reused.
Scope: per API-key owner. Keys are isolated across customers.

Webhooks

Register an HTTPS endpoint and we POST job-completion events to it as they happen. No polling, no cron. Sign-verified with HMAC-SHA256 so you can trust the body without an extra fetch.

Register via dashboard or POST /api/v2/webhooks/endpoints. The signing secret is returned once. Store it somewhere safe; rotating means deleting + recreating.
Event types: job.completed (more coming). Empty subscription list = all events.
Signature header: Bulkurlchecker-Signature: t=<ts>,v1=<hex> where hex = HMAC-SHA256(secret, "<ts>.<raw_body>"). Stripe-compatible format. Verify with bulkurlchecker.verify_signature() (Python) or verifySignature() (Node). Both ship in the SDKs.
Retry policy: exponential backoff at 0s, 30s, 5m, 30m, 2h, 12h, 24h then marked failed. Endpoints that respond non-2xx or time out get retried.
Headers we send: also Bulkurlchecker-Event-Id, Bulkurlchecker-Event-Type, and Bulkurlchecker-Delivery-Id. Dedupe on Event-Id if you care about exactly-once semantics.
Recommended timeout on your endpoint: return 2xx within 5s. Do the actual work async (queue, background job). We treat slow responses the same as failures and will retry.

Rate limits

60 requests per minute per key (burst).
10,000 requests per day per key (soft cap).
Exceed a limit and you get HTTP 429 with a Retry-After header plus X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (unix epoch). Back off and retry.
Need higher limits for production workloads? Reach out and we'll tune per key.

Pricing

One credit per URL checked. New accounts get a free tier on signup; additional credits are pay-as-you-go through billing. Cancelling a job mid-run refunds unchecked credits. The REST API and the MCP integration share the same balance, no separate quota.

Create API key →MCP integration →