Quick Start Guide

Get your first API response in under two minutes. This guide walks you through registration, authentication, and making your first request.

Prerequisites: You need a tool that can make HTTP requests — curl, Postman, Insomnia, or any programming language with an HTTP client.

Step 1: Register for an Account

Create a new account by sending a POST request to the registration endpoint, or sign up through the web portal.

bash
curl -X POST /api/register \
  -H "Content-Type: application/json" \
  -d '{
    "login": "yourname",
    "email": "you@company.com",
    "password": "YourSecureP@ssw0rd",
    "langKey": "en"
  }'
Response — 201 Created
(empty body — check your email for the activation link)

Password requirements: Minimum 8 characters, at least one uppercase letter, one lowercase letter, one digit, and one special character.

Step 2: Verify Your Email

Click the activation link sent to your email address. The link contains a one-time activation key:

Activation URL
/api/activate?key=a1b2c3d4e5f6...

You can also activate programmatically:

bash
curl -X GET "/api/activate?key=a1b2c3d4e5f6"

Step 3: Log In & Get a JWT Token

Authenticate to receive a JWT access token. Tokens are valid for 5–15 minutes and are validated locally by each service (no central auth server).

bash
curl -X POST /api/authenticate \
  -H "Content-Type: application/json" \
  -d '{
    "username": "yourname",
    "password": "YourSecureP@ssw0rd",
    "rememberMe": false
  }'
Response — 200 OK
{
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ5b3VybmFtZSIsImF1dCI..."
}

Note: For API access, you primarily use your API Key (step 4). JWT tokens are used for portal access and admin operations. Most public API endpoints only require the X-API-Key header.

Step 4: Create an API Key

Generate an API key through the portal dashboard, or via the admin API using your JWT token:

bash
curl -X POST /api/v1/admin/keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -d '{
    "name": "my-first-key",
    "description": "Development testing"
  }'
Response — 201 Created
{
  "id": 1,
  "name": "my-first-key",
  "key": "apk_live_7f3a9b2c4d1e8f6a0b5c3d7e9f2a4b6c",
  "createdAt": "2026-03-25T10:00:00Z"
}

Important: Copy your API key immediately. It is only displayed once at creation time. The platform stores a SHA-256 hash — the raw key cannot be retrieved later. If you lose it, generate a new one.

Step 5: Make Your First API Call

Now use your API key to call any service. Here are examples for several services:

Disposable Email Check

bash
curl -X POST /api/v1/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: apk_live_7f3a9b2c4d1e8f6a0b5c3d7e9f2a4b6c" \
  -d '{"email": "test@guerrillamail.com"}'
Response — 200 OK
{
  "email": "test@guerrillamail.com",
  "domain": "guerrillamail.com",
  "disposable": true,
  "score": 0.98,
  "reasons": ["static_blocklist", "mx_known_disposable"],
  "checkedAt": "2026-03-25T12:00:00Z"
}

DNS Lookup

bash
curl -X POST /api/v1/dns/lookup \
  -H "Content-Type: application/json" \
  -H "X-API-Key: apk_live_7f3a9b2c4d1e8f6a0b5c3d7e9f2a4b6c" \
  -d '{"domain": "example.com", "recordTypes": ["A", "MX", "TXT"]}'
Response — 200 OK
{
  "domain": "example.com",
  "records": {
    "A": ["93.184.216.34"],
    "MX": [{"priority": 10, "exchange": "mail.example.com"}],
    "TXT": ["v=spf1 include:_spf.example.com ~all"]
  },
  "queriedAt": "2026-03-25T12:01:00Z"
}

Password Breach Check

bash
# Uses k-anonymity: only a SHA-1 prefix is sent, never the full password
curl -X POST /api/v1/passwords/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: apk_live_7f3a9b2c4d1e8f6a0b5c3d7e9f2a4b6c" \
  -d '{"password": "P@ssword123"}'
Response — 200 OK
{
  "breached": true,
  "occurrences": 12847,
  "message": "This password has appeared in known data breaches."
}

Standard Response Envelope

All API services return JSON responses. Successful responses return the resource directly. Error responses follow the RFC 7807 Problem Detail format:

Success response
HTTP/1.1 200 OK
Content-Type: application/json

{
  // Resource-specific fields
  "field1": "value1",
  "field2": "value2"
}
Error response (RFC 7807)
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "/problems/invalid-email",
  "title": "Invalid Email",
  "status": 400,
  "detail": "The provided email 'not-an-email' is not a valid email address.",
  "instance": "/api/v1/check"
}

Error Handling

The platform uses standard HTTP status codes. Here are the most common ones you will encounter:

Status Meaning What to Do
200 OK Request succeeded. Parse the response body.
201 Created Resource created successfully.
400 Bad Request Check the detail field for validation errors.
401 Unauthorized Missing or invalid API key. Check the X-API-Key header.
403 Forbidden Valid key but insufficient permissions for this endpoint.
404 Not Found The resource or endpoint does not exist. Check the URL.
429 Too Many Requests Rate limit exceeded. Wait and retry. Check Retry-After header.
500 Internal Server Error Platform issue. Retry with exponential backoff.

Next Steps

📖

API Reference

Explore all 20 services with detailed endpoint documentation, request/response schemas, and code examples.

 💰

Pricing Plans

Compare plan tiers, rate limits, batch sizes, and features to find the right fit for your workload.

 🔐

Authentication Deep Dive

Learn about JWT tokens, API key rotation, scopes, and the dual-auth security model.

Try the API Live

Ready to see the API in action? Use our interactive explorer to send real requests directly from your browser — no setup required.

The API Explorer lets you select any of the 19 services, edit the request body, and see live responses with timing and rate limit information.