// Getting Started

Dreabee API Reference

The Dreabee API is a RESTful HTTP API that gives you programmatic access to the full Dreabee influencer intelligence platform. All requests are made over HTTPS. All request and response bodies are JSON.

The base URL for all API requests is:

          https://api.dreabee.com/v1
        

💡

New here? Head to the Developer overview for a 4-step quickstart, or create a free account to get your API key.

// Authentication

API Key Authentication

All API requests require authentication using your API key. Pass your key in the X-API-Key request header. Never expose your key in client-side code.

You can generate, rotate, and revoke keys from your account dashboard. Each key can have scoped permissions (read-only, write, admin).

🔑

Required header on every request:
X-API-Key: db_live_xxxxxxxxxxxxxxxxxxxx

Test keys use the prefix db_test_ and only return mock data. Live keys use db_live_.

⚠️ Never commit your API key to version control. Store it in environment variables or a secrets manager. If a key is compromised, rotate it immediately from your dashboard — compromised keys will be automatically revoked.

// Errors

Error Codes

Dreabee uses standard HTTP status codes. All error responses include a JSON body with error.code (machine-readable) and error.message (human-readable).

Status	Code	Description
200	`ok`	Request succeeded
400	`invalid_params`	One or more request parameters are invalid or missing
401	`unauthorized`	API key missing, invalid, or revoked
403	`forbidden`	Your plan does not include access to this endpoint
404	`not_found`	The requested resource does not exist
429	`rate_limited`	Too many requests — see `X-RateLimit-Reset` header
500	`server_error`	Unexpected server error — our team is automatically alerted

// Rate Limits

Rate Limiting

Rate limits are enforced per API key. When exceeded, requests return 429 Too Many Requests. Three headers are returned on every response to help you manage limits proactively.

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets
`Retry-After`	Seconds to wait before retrying (only on 429 responses)

// Pagination

Cursor-based Pagination

All list endpoints use cursor-based pagination. Pass cursor from the previous response's next_cursor field to get the next page. Use limit to control page size (default: 20, max: 100).

Parameter	Type	Description
limit	integer	Results per page. Default: `20`, max: `100`
cursor	string	Opaque cursor from previous response's `next_cursor`

// Influencers

Search Influencers

Search the Dreabee creator database with filters. Returns a paginated list of creator profiles with summary analytics.

POST /influencers/search Filter & search creators

All parameters are optional. Passing none returns the top 20 creators by quality score.

Parameter	Type	Required	Description
platform	string	optional	`instagram` · `youtube` · `tiktok` · `linkedin`
niche	string	optional	Content niche e.g. `fashion`, `fitness`, `tech`
min_quality_score	integer	optional	Minimum audience quality score (0–100). Recommended: `75`
followers.min	integer	optional	Minimum follower count
followers.max	integer	optional	Maximum follower count
location	string	optional	Country code e.g. `IN`, `US`, `GB`
language	string	optional	ISO 639-1 language code e.g. `en`, `hi`
min_er	float	optional	Minimum engagement rate percentage
limit	integer	optional	Page size. Default `20`, max `100`
cursor	string	optional	Pagination cursor from previous response

200 OK

Returns { results: Creator[], total: number, next_cursor: string | null }

Get Creator Profile

Retrieve full profile data for a single creator by their platform handle.

GET /influencers/{platform}/{handle} Get full profile

Parameter	Type	Required	Description
platform	path	required	Platform: `instagram`, `youtube`, `tiktok`, `linkedin`
handle	path	required	Creator's username (without @)

200 OK 404 Not Found

Get Audience Quality Score

Run the Dreabee fake follower analysis on any public creator. Returns a breakdown of follower categories and an overall quality score.

POST /quality/analyse Fake follower analysis

Parameter	Type	Required	Description
platform	string	required	Social platform
handle	string	required	Creator username (without @)
refresh	boolean	optional	Force re-analysis instead of returning cached result. Default: `false`

Response includes: quality_score, real_pct, suspicious_pct, mass_follower_pct, bot_pct, analysed_at

200 OK 400 Private Account

// Webhooks

Create a Webhook

Subscribe to real-time events. Dreabee sends a signed POST request to your endpoint when an event fires. All payloads are signed using HMAC-SHA256 with your webhook secret.

POST /webhooks Subscribe to events

Parameter	Type	Required	Description
url	string	required	HTTPS endpoint to receive events
events	string[]	required	Array of event types to subscribe to (see Event Types)
secret	string	optional	Your signing secret for HMAC verification. Auto-generated if not provided.

Webhook Event Types

Event	Trigger
`campaign.post.published`	A tracked creator publishes a new campaign post
`campaign.metrics.updated`	Campaign performance metrics are refreshed (hourly)
`influencer.quality.changed`	A creator's quality score changes by more than 5 points
`influencer.followers.spike`	Sudden follower count change detected (±10% in 24h)
`brand.mention.detected`	A monitored brand is mentioned by a creator

// SDKs

Node.js SDK

The official Node.js SDK supports all v1 endpoints, automatic retries, and TypeScript types out of the box.

# Install
$ npm install
              dreabee
# Usage
import Dreabee from 'dreabee';
const db = new Dreabee(process.env.DREABEE_KEY);
const creators =
            await db.influencers.search({ niche: 'fitness' });
          
const score = await db.quality.analyse({ platform: 'instagram', handle: 'username' });

GitHub: dreabee/dreabee-node →