api

KLYQ API Docs

Integrate influencer discovery and campaign creation directly into your platform.

Base URLhttps://api.klyqcollective.com/api/v1

Test URLhttps://backend-dev-b58f.up.railway.app/api/v1

1. Authentication

KLYQ uses two authentication mechanisms depending on the integration type.

Mechanism	Header	Purpose
JWT	Authorization: Bearer <token>	Brand dashboard login, key management
API Key	X-API-Key: klyq_test_xxx	External app-to-server integration

2. API Key Management

2.1 Generate a Test Key

bash

curl -X POST https://api.klyqcollective.com/api/v1/brand/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Development Sandbox",
    "key_env": "test"
  }'

201Response

json

{
  "api_key": "klyq_test_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
  "key_prefix": "klyq_test_a1b2",
  "name": "Development Sandbox",
  "uid": "key-uid-abc-123",
  "message": "store this key securely — it will not be shown again"
}

warningTest keys (klyq_test_*): No real money, uses Paystack sandbox. Campaigns flagged is_test: true.

2.2 Generate a Live Key

bash

curl -X POST https://api.klyqcollective.com/api/v1/brand/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Key",
    "key_env": "live"
  }'

201Response

json

{
  "api_key": "klyq_live_z9y8x7w6v5u4t3s2r1q0p9o8n7m6l5k4j3i2h1",
  "key_prefix": "klyq_live_z9y8",
  "name": "Production Key",
  "uid": "key-uid-def-456",
  "message": "store this key securely — it will not be shown again"
}

Live keys (klyq_live_*): Real money, real campaigns.

2.3 List All API Keys

bash

curl -X GET https://api.klyqcollective.com/api/v1/brand/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

200Response

json

[
  {
    "uid": "key-uid-abc-123",
    "name": "Development Sandbox",
    "key_env": "test",
    "key_prefix": "klyq_test_a1b2",
    "is_active": true,
    "last_used": "2026-07-21T14:22:00Z",
    "created_at": "2026-07-15T10:35:00Z"
  }
]

2.4 Revoke an API Key

bash

curl -X POST https://api.klyqcollective.com/api/v1/brand/api-keys/key-uid-abc-123/revoke \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

200

json

{"message": "api key revoked"}

3. Marketplace Discovery

3.1 Get Paystack Config

bash

curl -X GET https://api.klyqcollective.com/api/v1/marketplace/paystack-config

200Response

json

{
  "public_key": "pk_test_abc123...",
  "test_mode": true,
  "enabled": true
}

Use public_key to initialize Paystack inline JS. If enabled: false, handle gracefully.

3.2 List Verified Influencers (Directory)

bash

curl -X GET "https://api.klyqcollective.com/api/v1/marketplace/directory?platform=instagram&location=Lagos&niche=fashion&min_rating=3&page=1&limit=10"

Query Parameters

Param	Type	Description
platform	string	twitter, instagram, tiktok, facebook
location	string	City/State (partial match)
niche	string	Niche (partial match)
gender	string	male, female
min_followers	int	Minimum follower count
max_followers	int	Maximum follower count
min_rating	float	Minimum 1-5 rating
page	int	Default 1
limit	int	Default 20, max 100
seed	string	Stable random shuffle seed

No prices are shown. Pricing only surfaces in cart (5+ influencers) or checkout.

3.3 AI Campaign Match

bash

curl -X POST https://api.klyqcollective.com/api/v1/marketplace/ai-match \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_description": "Streetwear brand launching in Lagos...",
    "budget": 150000,
    "platforms": ["instagram", "tiktok"],
    "min_influencers": 10
  }'

Request Body

Field	Type	Required	Description
campaign_description	string	Yes	Free-text campaign description
budget	float	No	Max budget in Naira. Hard cap — count becomes a target.
platforms	[]string	No	Preferred platforms to prioritize
min_influencers	int	No	Target count (5 min if omitted). Strict only when no budget.

200Response

json

{
  "matches": [
    {
      "influencer_uid": "a1b2c3d4-...",
      "influencer_name": "Amara Styles",
      "platform": "instagram",
      "reason": "Lagos-based streetwear influencer with 15K engaged Gen Z followers on Instagram",
      "follower_count": 15000,
      "profile_image": "https://res.cloudinary.com/klyq/...",
      "niche": "fashion",
      "location": "Lagos"
    }
  ],
  "summary": "Selected 8 Lagos-based fashion and lifestyle influencers. 2 short of target due to budget constraints."
}

Budget too tight: {"message": "budget too tight: 10 influencers cost at least ₦250,000 but your budget is ₦150,000"}

Not enough matches: {"message": "AI could only match 3 influencers — checkout requires at least 5. Try a broader campaign description or increase budget."}

3.4 List Platforms

bash

curl -X GET https://api.klyqcollective.com/api/v1/marketplace/platforms

200

json

["twitter", "instagram", "tiktok", "facebook"]

4. Creating Campaigns (Checkout)

4.1 Via API Key (External Integration)

POST/api/v1/api/campaigns/create

Auth: X-API-Key

bash

curl -X POST https://api.klyqcollective.com/api/v1/api/campaigns/create \
  -H "X-API-Key: klyq_test_a1b2c3d4e5f6...a9b0" \
  -H "Content-Type: application/json" \
  -d '{
    "brief": "Launch our new streetwear collection — casual fits, bold colors...",
    "items": [
      {"influencer_uid": "a1b2c3d4-...", "platform": "instagram", "post_count": 1},
      {"influencer_uid": "b2c3d4e5-...", "platform": "instagram", "post_count": 1},
      {"influencer_uid": "c3d4e5f6-...", "platform": "tiktok", "post_count": 1},
      {"influencer_uid": "d4e5f6a7-...", "platform": "instagram", "post_count": 1},
      {"influencer_uid": "e5f6a7b8-...", "platform": "tiktok", "post_count": 1}
    ]
  }'

Request Body

Field	Type	Required	Description
brief	string	Yes	Campaign brief (objectives, creative direction)
items[].influencer_uid	string	Yes	Influencer UID from directory or AI match
items[].platform	string	Yes	twitter, instagram, tiktok, facebook
items[].post_count	int	Yes	Number of posts (min 1)

Minimum 5 unique influencers required.

200Response (Test key)

json

{
  "message": "proceed to payment",
  "campaign_uid": "camp-a1b2c3d4-...",
  "total_quote": 32500,
  "rate_applied": "30% partnership",
  "is_test": true,
  "authorization_url": "https://checkout.paystack.com/abc123def456",
  "reference": "klyq_campa1b2_78901234"
}

Pricing Example (30% partnership):

Instagram 15K followers: Walk-in ₦25,000, ActualPay ₦10,000, KLYQ Cut ₦15,000
You Pay: ₦10,000 + (0.30 × 15,000) = ₦14,500

Errors

Code	Body
400	{"message": "select 5 at least"}
401	{"message": "invalid api key"}
404	{"message": "influencer not found"}

4.2 Via JWT (Brand Dashboard)

POST/api/v1/brand/checkout

Auth: Bearer <brand_jwt>

Same request/response format as 4.1, but uses Authorization: Bearer instead of X-API-Key. Does not include is_test in response.

5. Payment

5.1 Verify Payment

bash

curl -X GET https://api.klyqcollective.com/api/v1/brand/payments/klyq_campa1b2_78901234/verify \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

200Success

json

{
  "payment_status": "success",
  "amount_paid": 32500,
  "reference": "klyq_campa1b2_78901234"
}

On success, campaign auto-transitions to in_progress.

200Pending

json

{
  "payment_status": "pending",
  "amount_paid": 0,
  "reference": "klyq_campa1b2_78901234"
}

200Failed

json

{
  "payment_status": "failed",
  "amount_paid": 32500,
  "reference": "klyq_campa1b2_78901234"
}

6. Test Cards (Paystack Sandbox)

Scenario	Card Number
Success	4084 0840 8408 4081
Decline	4000 0000 0000 0002

CVV

Any 3 digits

Expiry

Any future date

OTP

123456

7. End-to-End Integration Flow

TEST MODE

bash

# 1. Generate test key (one-time)
TOKEN=$(curl -s -X POST https://api.klyqcollective.com/api/v1/auth/brand/login ... | jq -r .token)
TEST_KEY=$(curl -s -X POST https://api.klyqcollective.com/api/v1/brand/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name":"Sandbox","key_env":"test"}' | jq -r .api_key)

# 2. Discover influencers
curl -s "https://api.klyqcollective.com/api/v1/marketplace/directory?platform=instagram&limit=50" \
  | jq '.influencers[].uid' > influencers.txt

# 3. Get AI recommendations
curl -s -X POST https://api.klyqcollective.com/api/v1/marketplace/ai-match \
  -H "Content-Type: application/json" \
  -d '{"campaign_description":"My campaign...","min_influencers":10}' \
  | jq '.matches[].influencer_uid' >> influencers.txt

# 4. Pick 5+ unique influencers, create campaign
curl -s -X POST https://api.klyqcollective.com/api/v1/api/campaigns/create \
  -H "X-API-Key: $TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brief": "Testing integration flow",
    "items": [
      {"influencer_uid":"uid1","platform":"instagram","post_count":1},
      {"influencer_uid":"uid2","platform":"instagram","post_count":1},
      {"influencer_uid":"uid3","platform":"tiktok","post_count":1},
      {"influencer_uid":"uid4","platform":"instagram","post_count":1},
      {"influencer_uid":"uid5","platform":"tiktok","post_count":1}
    ]
  }' > checkout.json

# 5. Extract payment URL and redirect user
AUTH_URL=$(jq -r .authorization_url checkout.json)
CAMPAIGN_UID=$(jq -r .campaign_uid checkout.json)
echo "Send user to: $AUTH_URL"

# 6. After payment, verify
curl -s "https://api.klyqcollective.com/api/v1/brand/payments/$(jq -r .reference checkout.json)/verify" \
  -H "Authorization: Bearer $TOKEN"

8. Campaign Lifecycle

pending

→

paymentspayment verified

→

in_progress

→

admin marks complete

→

completed

9. Error Format

All errors follow this shape:

json

{
  "code": 400,
  "message": "human-readable message",
  "logMsg": "internal detail (only in dev)"
}

Common status codes: 400 401 403 404 409 500

10. Rate Limits

publicPublic endpoints: 100 requests/minute per IP
keyAPI key endpoints: Shared IP-based limit (per-key limits coming soon)

Headers on all responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset