API Documentation — DomainsVault - Secure Domain Marketplace

Authentication

Bearer Token Auth

Every API request must include your personal access token in the Authorization header. Tokens are tied to your account — keep them secret and never expose them in client-side code.

Tokens are generated in your Profile Settings. You can create multiple tokens with different names (e.g., one per application). Revoke any token at any time from the same settings page.

Security: Your secret token is shown only once at generation time. Store it securely (e.g., in an environment variable). If lost, revoke and regenerate.

Request HeaderAuthorization: Bearer YOUR_SECRET_TOKEN

cURL Examplecurl -H "Authorization: Bearer YOUR_SECRET_TOKEN" \ -H "Accept: application/json" \ https://domainsvault.com/api/domains

JavaScript (fetch)const res = await fetch('https://domainsvault.com/api/domains', { headers: { 'Authorization': 'Bearer YOUR_SECRET_TOKEN', 'Accept': 'application/json' } }); const data = await res.json();

Endpoints

Available Endpoints

All endpoints are read-only and return application/json. The base URL is https://domainsvault.com/api.

GET /api/domains

List your domain portfolio. Results are paginated and can be filtered by status or TLD.

Query Parameters

Parameter	Type	Description
`status`	integer	Filter by status code (1 = For Sale, 3 = Lease)
`tld`	string	Filter by extension, e.g. `com` or `.io`
`per_page`	integer	Results per page (1–100, default 25)
`page`	integer	Page number (default 1)

Example Response (truncated){ "current_page": 1, "data": [ { "id": 42, "domain_name": "example.com", "tld": ".com", "status": "For Sale", "price": 2500.00, "is_verified": true, "registration_date": "2020-01-15", "expiration_date": "2026-01-15", "views": 1420, "unique_views": 387, "created_at": "2024-03-10T08:30:00Z" } ], "per_page": 25, "total": 47, "last_page": 2 }

GET /api/domains/{id}

Retrieve full details for a single domain by its numeric ID. Only returns domains belonging to your account.

Path Parameter

Parameter	Type	Description
`id`	integer	Numeric domain ID from the list endpoint

Example Response{ "id": 42, "domain_name": "example.com", "tld": ".com", "sld": "example", "status": "For Sale", "status_code": 1, "price": 2500.00, "description": "Short, memorable .com domain.", "is_verified": true, "is_featured": false, "registrar": "Namecheap", "registration_date": "2020-01-15", "expiration_date": "2026-01-15", "auto_renew": true, "nameservers": ["ns1.example.com", "ns2.example.com"], "categories": ["Technology", "Brandable"], "views": 1420, "unique_views": 387, "inquiry_count": 12, "created_at": "2024-03-10T08:30:00Z", "updated_at": "2025-11-02T14:05:22Z" }

GET /api/stats

Aggregate statistics for your account: domain counts, total views, pending offers, and current subscription plan.

No parameters required. Returns a single JSON object.

Example Response{ "total_domains": 47, "active_domains": 31, "total_views": 18204, "total_unique_views": 5093, "pending_offers": 3, "plan": "Pro" }

Domain Statuses

Status Reference

The status_code field in domain responses maps to the following states:

Code	Label
`0`	Inactive
`1`	For Sale
`2`	Not For Sale
`3`	Available for Lease
`4`	Leased
`5`	Sold
`6`	Parked

Error Responses

Error Handling

The API returns standard HTTP status codes. All error bodies include a message field.

Status	Meaning
`401`	Missing or invalid token
`403`	Token exists but account lacks API access (free tier)
`404`	Domain not found or does not belong to your account
`429`	Rate limit exceeded (60 req/min)
`500`	Server error

401 Example{ "message": "Unauthenticated." }

Limits & Access

Rate Limits & Requirements

Rate Limit

60 requests per minute per IP address, enforced at the network level. Burst of 10 allowed. Exceeding the limit returns 429 Too Many Requests.

Account Requirement

An active Starter, Pro, or Enterprise subscription is required to generate API tokens. Free accounts cannot access the API.

Read Only

All endpoints are read-only. The API returns data for domains belonging to the authenticated account only. No write operations are available.

DomainsVault REST API