Developer Documentation

API Reference

Complete REST API for AI agents and developers. Browse public data with read-only keys, or manage listings and subscriptions with write keys.

Authentication

All API requests require an API key passed in the Authorization header. There are two types of keys:

id_xxxRead-Only Key

Access public data: listings, articles, categories, cities. Anyone can generate one — no login required.

idw_xxxWrite Key

Full partner operations: create listings, manage clients, purchase subscriptions. Requires an active Marketing Agent account.

# Pass your API key in the Authorization header
curl -H "Authorization: Bearer id_your_key_here" \
     https://intelldirectories.com/api/v1/listings

Rate limit: 30 requests per hour per key. Rate limit headers are included in every response.

Key Management

POST

/api/v1/api-keys

Generate a read-only API key (3 per day per IP)

Public

POST

/api/v1/api-keys/write

Generate a write API key (requires active Marketing Agent)

Session

GET

/api/v1/api-keys

List your API keys

Session

DELETE

/api/v1/api-keys

Revoke an API key

Session

Read Endpoints

Public data accessible with any API key (read-only or write).

GET

/api/v1/listings

Search and list business listings

Any key

GET

/api/v1/listings/{id}

Get full listing details with articles and reviews

Any key

GET

/api/v1/articles

List published articles

Any key

GET

/api/v1/articles/{slug}

Get article with full content

Any key

GET

/api/v1/categories

List all categories with listing counts

Any key

GET

/api/v1/cities

List all cities with listing counts

Any key

Example: Search Listings

curl -H "Authorization: Bearer id_xxx" \
     "https://intelldirectories.com/api/v1/listings?q=restaurant&city=London&limit=10"

# Response:
{
  "data": [
    {
      "id": "uuid",
      "businessName": "The Italian Kitchen",
      "category": "Restaurants",
      "city": "London",
      "slug": "the-italian-kitchen-london",
      "rating": 4.5,
      ...
    }
  ],
  "meta": { "total": 42, "page": 1, "limit": 10, "totalPages": 5 }
}

Write Endpoints — Listings

Manage listings and client accounts. Requires a write key (idw_xxx).

POST

/api/v1/listings

Create listing + client account (3-day free trial)

Write key

GET

/api/v1/listings/mine

List your partner's listings with subscription status

Write key

PATCH

/api/v1/listings/{id}

Update listing details (businessName, websiteUrl, city, category, phone, address)

Write key

DELETE

/api/v1/listings/{id}

Deactivate a listing (soft delete)

Write key

Example: Create a Listing

curl -X POST -H "Authorization: Bearer idw_xxx" \
     -H "Content-Type: application/json" \
     -d '{
       "clientName": "John Smith",
       "clientEmail": "[email protected]",
       "businessName": "Smith Bakery",
       "websiteUrl": "https://smithbakery.com",
       "city": "Amsterdam",
       "category": "Bakeries"
     }' \
     https://intelldirectories.com/api/v1/listings

# Response (201):
{
  "data": {
    "userId": "uuid",
    "listingId": "uuid",
    "clientEmail": "[email protected]",
    "temporaryPassword": "Abc123xyz",
    "trialEndsAt": "2026-02-19T12:00:00.000Z",
    "upgradeLink": "https://intelldirectories.com/upgrade/uuid"
  }
}

Write Endpoints — Partner

GET

/api/v1/partner/profile

Get your partner profile and dashboard stats

Write key

PATCH

/api/v1/partner/pricing

Update pricing tiers (must be >= base price)

Write key

Payment Methods & Subscriptions

Save a payment method to enable auto-charging when purchasing subscriptions via the API. You pay the base price (wholesale) per tier.

POST

/api/v1/payment-methods/setup

Create Stripe SetupIntent to save a card

Write key

POST

/api/v1/payment-methods/confirm

Confirm and save payment method as default

Write key

GET

/api/v1/payment-methods

List saved payment methods

Write key

DELETE

/api/v1/payment-methods/{id}

Remove a saved payment method

Write key

POST

/api/v1/subscriptions

Purchase/upgrade subscription (auto-charges saved card)

Write key

Pricing

Tier 1: Starter

25 EUR

5 articles/month

Tier 2: Professional

50 EUR

15 articles/month

Tier 3: Enterprise

80 EUR

30 articles/month

Example: Purchase Subscription

curl -X POST -H "Authorization: Bearer idw_xxx" \
     -H "Content-Type: application/json" \
     -d '{ "listingId": "uuid", "tier": 2 }' \
     https://intelldirectories.com/api/v1/subscriptions

# Response (201):
{
  "data": {
    "listingId": "uuid",
    "tier": 2,
    "planName": "Professional",
    "articlesPerMonth": 15,
    "status": "ACTIVE",
    "amountCharged": 50,
    "currency": "EUR",
    "stripePaymentIntentId": "pi_xxx"
  }
}

Error Codes

Status	Meaning
401	Invalid or missing API key
402	Payment required or failed (no saved card, card declined)
403	Read-only key on write endpoint, or inactive partner
404	Resource not found or not owned by your account
409	Conflict (duplicate email, already active subscription)
429	Rate limit exceeded (30 req/hour)

PreviousDashboard Guide Next What is AI SEO?

curl -H "Authorization: Bearer id_xxx" \ "https://intelldirectories.com/api/v1/listings?q=restaurant&city=London&limit=10" # Response: { "data": [ { "id": "uuid", "businessName": "The Italian Kitchen", "category": "Restaurants", "city": "London", "slug": "the-italian-kitchen-london", "rating": 4.5, ... } ], "meta": { "total": 42, "page": 1, "limit": 10, "totalPages": 5 } }

curl -X POST -H "Authorization: Bearer idw_xxx" \ -H "Content-Type: application/json" \ -d '{ "clientName": "John Smith", "clientEmail": "[email protected]", "businessName": "Smith Bakery", "websiteUrl": "https://smithbakery.com", "city": "Amsterdam", "category": "Bakeries" }' \ https://intelldirectories.com/api/v1/listings # Response (201): { "data": { "userId": "uuid", "listingId": "uuid", "clientEmail": "[email protected]", "temporaryPassword": "Abc123xyz", "trialEndsAt": "2026-02-19T12:00:00.000Z", "upgradeLink": "https://intelldirectories.com/upgrade/uuid" } }

curl -X POST -H "Authorization: Bearer idw_xxx" \ -H "Content-Type: application/json" \ -d '{ "listingId": "uuid", "tier": 2 }' \ https://intelldirectories.com/api/v1/subscriptions # Response (201): { "data": { "listingId": "uuid", "tier": 2, "planName": "Professional", "articlesPerMonth": 15, "status": "ACTIVE", "amountCharged": 50, "currency": "EUR", "stripePaymentIntentId": "pi_xxx" } }

Error Codes

Status	Meaning
401	Invalid or missing API key
402	Payment required or failed (no saved card, card declined)
403	Read-only key on write endpoint, or inactive partner
404	Resource not found or not owned by your account
409	Conflict (duplicate email, already active subscription)
429	Rate limit exceeded (30 req/hour)