API Reference

Complete API reference documentation for Status Check.

Base URL

https://api.status-check.io

Authentication

All API requests require authentication via API Key:

curl -H "X-API-Key: sk_your_api_key" https://api.status-check.io/v1/check-website

See Authentication for details.

Available Endpoints

For detailed standalone validation endpoints, see the Validation API documentation.

API Key Management

Create API Key

Generate a new API key.

Endpoint: POST /v1/auth/keys

Request:

curl -X POST https://api.status-check.io/v1/auth/keys \
  -H "Authorization: Bearer your_firebase_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Server",
    "description": "Main production API key"
  }'

Response:

{
  "key_id": "key_abc123",
  "api_key": "sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "name": "Production Server",
  "created_at": "2025-03-02T10:30:00Z",
  "message": "Save this API key now. It will not be shown again."
}

warning

API keys are only displayed once during creation. Save them securely immediately.

List API Keys

Get all your API keys.

Endpoint: GET /v1/auth/keys

Request:

curl -X GET https://api.status-check.io/v1/auth/keys \
  -H "Authorization: Bearer your_firebase_token"

Response:

{
  "keys": [
    {
      "key_id": "key_abc123",
      "name": "Production Server",
      "partial_key": "sk_...abc123",
      "created_at": "2025-03-02T10:30:00Z",
      "last_used": "2025-03-02T15:45:00Z"
    },
    {
      "key_id": "key_def456",
      "name": "Development",
      "partial_key": "sk_...def456",
      "created_at": "2025-03-01T09:00:00Z",
      "last_used": null
    }
  ]
}

Revoke API Key

Permanently disable an API key.

Endpoint: DELETE /v1/auth/keys/{key_id}

Request:

curl -X DELETE https://api.status-check.io/v1/auth/keys/key_abc123 \
  -H "Authorization: Bearer your_firebase_token"

Response:

{
  "message": "API key revoked successfully",
  "key_id": "key_abc123"
}

Leads Management

Create Lead

Add a new lead to your account.

Endpoint: POST /v1/leads

Request:

curl -X POST https://api.status-check.io/v1/leads \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "domain": "example.com",
    "company": "Example Corp"
  }'

Response:

{
  "lead_id": "lead_abc123",
  "domain": "example.com",
  "status": "new",
  "created_at": "2025-03-02T10:30:00Z"
}

Query Leads

Retrieve leads with filtering and pagination.

Endpoint: GET /v1/leads

Parameters:

status (optional): Filter by validation status
min_score (optional): Minimum quality score
max_score (optional): Maximum quality score
limit (optional): Number of results (default: 50, max: 100)
offset (optional): Pagination offset

Request:

curl -X GET "https://api.status-check.io/v1/leads?status=verified&min_score=80&limit=20" \
  -H "X-API-Key: sk_your_api_key"

Response:

{
  "leads": [
    {
      "lead_id": "lead_abc123",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "domain": "example.com",
      "company": "Example Corp",
      "status": "verified",
      "score": 95,
      "created_at": "2025-03-02T10:30:00Z",
      "validated_at": "2025-03-02T10:31:00Z"
    }
  ],
  "total": 150,
  "limit": 20,
  "offset": 0
}

Get Lead

Retrieve detailed information for a specific lead.

Endpoint: GET /v1/leads/{lead_id}

Request:

curl -X GET https://api.status-check.io/v1/leads/lead_abc123 \
  -H "X-API-Key: sk_your_api_key"

Response:

{
  "lead_id": "lead_abc123",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "domain": "example.com",
  "company": "Example Corp",
  "status": "verified",
  "score": 95,
  "validation": {
    "http_status": 200,
    "ssl_valid": true,
    "response_time": 145,
    "final_url": "https://www.example.com",
    "email_deliverable": true,
    "email_provider": "Google Workspace"
  },
  "created_at": "2025-03-02T10:30:00Z",
  "validated_at": "2025-03-02T10:31:00Z"
}

Update Lead

Update lead information.

Endpoint: PUT /v1/leads/{lead_id}

Request:

curl -X PUT https://api.status-check.io/v1/leads/lead_abc123 \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Smith",
    "company": "New Company Name"
  }'

Response:

{
  "lead_id": "lead_abc123",
  "first_name": "Jane",
  "last_name": "Smith",
  "company": "New Company Name",
  "updated_at": "2025-03-02T11:00:00Z"
}

Archive Lead

Soft delete a lead.

Endpoint: DELETE /v1/leads/{lead_id}

Request:

curl -X DELETE https://api.status-check.io/v1/leads/lead_abc123 \
  -H "X-API-Key: sk_your_api_key"

Response:

{
  "message": "Lead archived successfully",
  "lead_id": "lead_abc123"
}

Bulk Create Leads

Create multiple leads in one request.

Endpoint: POST /v1/leads/bulk

Request:

curl -X POST https://api.status-check.io/v1/leads/bulk \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "leads": [
      {
        "first_name": "John",
        "last_name": "Doe",
        "email": "john@example.com",
        "domain": "example.com"
      },
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@acme.org",
        "domain": "acme.org"
      }
    ]
  }'

Response:

{
  "created": 2,
  "lead_ids": ["lead_abc123", "lead_def456"]
}

Validate Leads

Trigger validation for one or more leads.

Endpoint: POST /v1/leads/validate

Request:

curl -X POST https://api.status-check.io/v1/leads/validate \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "lead_ids": ["lead_abc123", "lead_def456"]
  }'

Response:

{
  "job_id": "validation_xyz789",
  "total_leads": 2,
  "status": "processing"
}

See Also:

Lead Statistics - Detailed statistics and counts for all your leads

Credits

Get Credit Balance

Check your current credit balance.

Endpoint: GET /v1/credits

Request:

curl -X GET https://api.status-check.io/v1/credits \
  -H "X-API-Key: sk_your_api_key"

Response:

{
  "userId": "user_abc123",
  "credits": 1500.0,
  "updatedAt": "2026-06-20T15:30:00Z"
}

Pricing:

Website check: 0.001 stored credits (1 display credit)
Email check: 0.001 stored credits (1 display credit)
Lead validation: 0.002 stored credits (2 display credits)

See Also:

Credits API - Complete credit balance documentation
Validation API - Standalone website and email validation

Health & Status

Health Check

Check API health status.

Endpoint: GET /health

Request:

curl https://api.status-check.io/health

Response:

{
  "status": "healthy",
  "timestamp": "2025-03-02T10:30:00Z"
}

Readiness Probe

Check if API is ready to serve requests.

Endpoint: GET /readiness

Liveness Probe

Check if API is alive.

Endpoint: GET /liveness

Error Responses

All errors follow a consistent format:

{
  "error": "error_code",
  "message": "Human-readable error message",
  "details": {
    "field": "Additional context"
  }
}

Common Error Codes

Status Code	Error	Description
400	Bad Request	Invalid request format or parameters
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn't exist
429	Rate Limit Exceeded	Too many requests
500	Internal Server Error	Server-side error
503	Service Unavailable	API temporarily unavailable

Rate Limits

60 requests per minute
1,000 requests per hour

See Rate Limiting for details.

Generating Interactive API Docs

To generate interactive API reference from the OpenAPI specification:

Start your API server:

cd api
uvicorn main:app --host 0.0.0.0 --port 8080

Fetch the OpenAPI spec:

cd docs-site
curl http://localhost:8080/openapi.json > static/openapi.json

Generate API docs:
```
npm run docusaurus gen-api-docs all
```
Rebuild the site:
```
npm run build
```

Quick Links

Live API Documentation - Interactive Swagger UI
OpenAPI Spec - Raw OpenAPI JSON
ReDoc - Alternative API documentation

Next Steps

Validation API - NEW! Standalone website and email validation
API Keys - Detailed guide on managing API keys
Authentication - Authentication methods
Batch Processing - Bulk validation
Rate Limiting - Rate limit details
Webhooks - Real-time event notifications
Lead Statistics - Aggregate lead statistics
Credits - Credit balance and usage

Support

Need help with the API?

Email: support@status-check.io
Dashboard: app.status-check.io

Base URL​

Authentication​

Available Endpoints​

API Key Management​

Create API Key​

List API Keys​

Revoke API Key​

Leads Management​

Create Lead​

Query Leads​

Get Lead​

Update Lead​

Archive Lead​

Bulk Create Leads​

Validate Leads​

Credits​

Get Credit Balance​

Health & Status​

Health Check​

Readiness Probe​

Liveness Probe​

Error Responses​

Common Error Codes​

Rate Limits​

Generating Interactive API Docs​

Quick Links​

Next Steps​

Support​

Base URL

Authentication

Available Endpoints

API Key Management

Create API Key

List API Keys

Revoke API Key

Leads Management

Create Lead

Query Leads

Get Lead

Update Lead

Archive Lead

Bulk Create Leads

Validate Leads

Credits

Get Credit Balance

Health & Status

Health Check

Readiness Probe

Liveness Probe

Error Responses

Common Error Codes

Rate Limits

Generating Interactive API Docs

Quick Links

Next Steps

Support