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

See Authentication for details.

Available Endpoints

Domain Validation

Check Single Domain

Validate a single domain and get detailed results.

Endpoint: POST /v1/check

Request:

curl -X POST https://api.status-check.io/v1/check \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com"
  }'

Response:

{
  "domain": "example.com",
  "status": "valid",
  "http_status": 200,
  "ssl_valid": true,
  "response_time": 145,
  "final_url": "https://www.example.com",
  "score": 95,
  "timestamp": "2025-03-02T10:30:00Z"
}

Fields:

domain (string): The validated domain
status (string): Validation status (valid, invalid, unknown)
http_status (number): HTTP response code
ssl_valid (boolean): Whether SSL certificate is valid
response_time (number): Response time in milliseconds
final_url (string): Final URL after redirects
score (number): Quality score (0-100)
timestamp (string): Validation timestamp

Batch Domain Check

Validate multiple domains in a single request.

Endpoint: POST /v1/batch

Request:

curl -X POST https://api.status-check.io/v1/batch \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "domains": [
      "example.com",
      "acme.org",
      "test-site.io"
    ]
  }'

Response:

{
  "job_id": "batch_abc123",
  "status": "processing",
  "total": 3,
  "created_at": "2025-03-02T10:30:00Z"
}

Get Batch Status

Check the status of a batch validation job.

Endpoint: GET /v1/batch/{job_id}

Request:

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

Response:

{
  "job_id": "batch_abc123",
  "status": "completed",
  "total": 3,
  "processed": 3,
  "completed": 3,
  "progress": 100,
  "results": [
    {
      "domain": "example.com",
      "status": "valid",
      "score": 95
    },
    {
      "domain": "acme.org",
      "status": "valid",
      "score": 88
    },
    {
      "domain": "test-site.io",
      "status": "invalid",
      "score": 20
    }
  ]
}

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"
}

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

API Keys - Detailed guide on managing API keys
Authentication - Authentication methods
Batch Processing - Bulk validation
Rate Limiting - Rate limit details

Support

Need help with the API?

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

Base URL​

Authentication​

Available Endpoints​

Domain Validation​

Check Single Domain​

Batch Domain Check​

Get Batch Status​

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​

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

Domain Validation

Check Single Domain

Batch Domain Check

Get Batch Status

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

Health & Status

Health Check

Readiness Probe

Liveness Probe

Error Responses

Common Error Codes

Rate Limits

Generating Interactive API Docs

Quick Links

Next Steps

Support