Authentication

Bearer token via API key. Generate keys from your developer dashboard.

Rate limits

Standard keys get 10 requests per minute. Premium keys get 60. Upgrade from your developer dashboard. Rate-limit headers are on every response.

Base URL

https://www.aidirectori.es/api/v1

1. 1 Get your API key

   Go to the developer dashboard and create an API key. Keys start with aid_. Store it securely — you won't be able to see the full key again.

   Acceptable use is required

   Creating a key requires agreement to the API Acceptable Use Policy. Cloning businesses, rebuilding AI Directories, bulk republication, unauthorized public SEO pages, abusive targeting, credential sharing, and access-control evasion are prohibited and can result in a permanent platform ban.

2. 2 Make your first request

   Pass your key as a Bearer token in the Authorization header. X-API-Key is also accepted, on every endpoint. The two are interchangeable — what a key can reach depends on the key, not the header it arrives in. A dashboard aid_ key still gets 403 on the partner endpoints when sent as X-API-Key; if you are seeing 403, you need a different key, not a different header.

   bashCopy

   curl -s "https://www.aidirectori.es/api/v1/tools?q=ai&limit=5" \
     -H "Authorization: Bearer aid_your_api_key"

3. 3 Parse the response

   Successful reads return { success: true, data }. List endpoints also include pagination — its fields and the limit-clamping rules are worth reading before you write a paging loop. Watch X-RateLimit-Remaining.

   jsonCopy

   {
     "success": true,
     "data": [
       {
         "slug": "transclipper",
         "name": "TransClipper",
         "website": "https://transclipper.ai"
       }
     ]
   }

Partner keys

Directory partners who send us tools for the submission service still use an issued key for POST /submit-ai-tool, status, webhooks, and support. Those keys also work on catalog reads. See Got a directory?.

A partnership is not a catalog API key. It is a way for your directory to offer our directory submission service next to your own listing.

You send the tool information from your server. We list it on AI Directories and submit it to other directories on the founder’s behalf. Founders stay on your product — they do not fill our form.

Who this is for

Startup directories, AI directories, and launch platforms that already collect a product listing and founder email. If you want to resell or bundle “get listed on 30 / 60 / 100+ directories,” this is the integration.

Searching the catalog does not need a partnership — any signed-in user can create an aid_ key. MCP cannot submit tools.

What you send

POST https://www.aidirectori.es/api/v1/submit-ai-tool with an issued X-API-Key. The body is the tool: name, website, tagline, description, category, pricing, founder name and email, tags — plus, when you have them, package, slug, icon, screenshots.

paymentType is the directory package, not the product’s pricing: starter (30+), pro (60+), premium (100+). Omit it only if the package will be set later in our admin.

Keep the key on your server. Collect founder email and marketing consent before you POST. Field lists and curl are on Submit & partners.

What you get back

• An AI Directories listing for that tool
• Directory submissions for the package you sent — we do the form work
• GET https://www.aidirectori.es/api/v1/ai-tools/status — poll by id, slug, or website while work is in progress
• A webhook to your HTTPS URL when we mark the job Done, with the directories we submitted to
• Optional POST /support/ask — your customers can ask about their submission; we answer from your product

Rules

• Server-side X-API-Key only (or Authorization: Bearer)
• MCP accepts a catalog aid_ key for reads and cannot submit
• You collect founder email and consent — we never show founder emails on the public catalog
• Do not send the key from a webpage, app binary, or public repo

Discovery lives at GET / and the OpenAPI document at GET /openapi.json. Field notes for catalog responses are on AI tools and Directories.

Envelope, pagination, and limits

Every response is the same envelope. data is an array on searches and an object on single-item lookups. Check success before reading data.

{ "success": true, "data": [], "pagination": { "page": 1, "limit": 20, "total": 0, "pages": 0 } }

{ "success": false, "error": "Invalid or revoked API key." }

GET /tools and GET /directories return a pagination object. The taxonomy endpoints — /categories, /tags, /directory-categories — return the whole list and no pagination key at all.

An oversized limit is clamped, not rejected. Ask for more than the maximum and you get the maximum, with a 200 — no error tells you it happened. /tools and /directories default to 20 and cap at 100; /categories and /tags cap at 500. A missing, zero, negative, or non-numeric limit falls back to the default, and page floors at 1. So read pagination.limit back from the response rather than assuming you got the page size you asked for — that assumption is what turns a paging loop into an infinite one.

page=1
while :; do
  body=$(curl -s "https://www.aidirectori.es/api/v1/tools?limit=100&page=$page" \
    -H "Authorization: Bearer $AID_KEY")
  echo "$body" | jq -e '.success' >/dev/null || { echo "$body"; break; }
  echo "$body" | jq -c '.data[]'
  pages=$(echo "$body" | jq '.pagination.pages')
  [ "$page" -ge "$pages" ] && break
  page=$((page + 1))
  sleep 6   # stay under 10 req/min on a standard key
done

AI tools

Browse, search, and filter the live catalog, or fetch one listing by slug. Maps to MCP search_tools, get_top_tools, get_tool, list_categories, and list_tags.

curl -s "https://www.aidirectori.es/api/v1/categories" \
  -H "Authorization: Bearer aid_your_api_key"

curl -s "https://www.aidirectori.es/api/v1/tools/top?limit=10&category=image" \
  -H "Authorization: Bearer aid_your_api_key"

curl -s "https://www.aidirectori.es/api/v1/tools?q=ai&limit=5" \
  -H "Authorization: Bearer aid_your_api_key"

curl -s "https://www.aidirectori.es/api/v1/tools/transclipper" \
  -H "Authorization: Bearer aid_your_api_key"

curl -s "https://www.aidirectori.es/api/v1/tags" \
  -H "Authorization: Bearer aid_your_api_key"

Directories

The submission-directory catalog — Domain Rating, cost, badge, and categories. Maps to MCP search_directories, get_directory, and list_directory_categories.

curl -s "https://www.aidirectori.es/api/v1/directories?cost=Free&limit=10" \
  -H "Authorization: Bearer aid_your_api_key"

curl -s "https://www.aidirectori.es/api/v1/directories/theres-an-ai-for-that" \
  -H "Authorization: Bearer aid_your_api_key"

curl -s "https://www.aidirectori.es/api/v1/directory-categories" \
  -H "Authorization: Bearer aid_your_api_key"

Partner

Write and status endpoints need an issued X-API-Key. Keep it on your server. MCP does not call these. Full field lists live under Submit & partners.

curl -s -X POST "https://www.aidirectori.es/api/v1/submit-ai-tool" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Tool",
    "website": "https://mytool.com",
    "tagline": "One-line pitch",
    "description": "What the product does.",
    "category": "productivity",
    "pricing": "FREE",
    "paymentType": "pro",
    "founderName": "Jane Founder",
    "founderEmail": "jane@mytool.com",
    "tags": ["ai", "productivity"],
    "icon": "https://mytool.com/icon.png",
    "frame": "https://mytool.com/screenshot.png",
    "screenshots": ["https://mytool.com/gallery-1.png"]
  }'

curl -s "https://www.aidirectori.es/api/v1/ai-tools/status?slug=my-ai-tool" \
  -H "X-API-Key: YOUR_API_KEY"

These are not anonymous. We issue a key per partner. MCP does not call them.

Submit a tool

POST https://www.aidirectori.es/api/v1/submit-ai-tool

Creates a listing. Send paymentType to queue directory submissions for that package. Omit it and the tool is created as waiting so the package can be set later in admin.

curl -s -X POST "https://www.aidirectori.es/api/v1/submit-ai-tool" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Tool",
    "website": "https://mytool.com",
    "tagline": "One-line pitch",
    "description": "What the product does.",
    "category": "productivity",
    "pricing": "FREE",
    "paymentType": "pro",
    "founderName": "Jane Founder",
    "founderEmail": "jane@mytool.com",
    "tags": ["ai", "productivity"],
    "icon": "https://mytool.com/icon.png",
    "frame": "https://mytool.com/screenshot.png",
    "screenshots": ["https://mytool.com/gallery-1.png"]
  }'

Poll submission status

GET https://www.aidirectori.es/api/v1/ai-tools/status — look up a tool your key submitted with exactly one of id, slug, or website. Other clients’ tools return 404.

Use this anytime — not only when a webhook fires. Poll while summary.isComplete is false, then stop (or wait for Done). submissionState is IN_QUEUE, ASSIGNED, IN_PROGRESS, REVIEW, DONE, or null when there is no directory workflow.

curl -s "https://www.aidirectori.es/api/v1/ai-tools/status?slug=my-ai-tool" \
  -H "X-API-Key: YOUR_API_KEY"

Webhook

We POST JSON to an HTTPS URL stored on your API client — not sent on each submit. Give us the URL when you apply; we store it as webhookUrl and send you a signing secret. Both directory-Done and support replies hit that same endpoint.

The directory event fires when an admin clicks Done on a tool your key submitted and webhookUrl is set. Missing URL: we send nothing. Your endpoint down or non-2xx: the tool is still marked Done. We do not retry yet — poll status if you need a fallback.

Request

Verify the signature

HMAC-SHA256 over the raw request body with the secret we gave you. Compare the hex digest to X-AI-Directories-Signature after stripping the sha256= prefix. Use a timing-safe compare.

const crypto = require("crypto");

function verifySignature(rawBody, signatureHeader, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const received = String(signatureHeader || "").replace(/^sha256=/, "");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));
}

Payload

submissions only includes directories we actually submitted. Each row can include the live listingUrl, proof screenshot, domain rating, and who submitted it (ADMIN or OWNER). Return 2xx to acknowledge.

{
  "event": "directory_submissions.completed",
  "occurredAt": "2026-09-01T13:00:00.000Z",
  "tool": {
    "id": "64a1b2c3d4e5f6789012345",
    "name": "My AI Tool",
    "slug": "my-ai-tool",
    "website": "https://myaitool.com",
    "paymentStatus": "prolist",
    "paymentLabel": "Pro · 60+",
    "targetDirectoriesCount": 60
  },
  "summary": {
    "submittedCount": 62,
    "recordedSubmissions": 62,
    "notes": "All high-DR directories completed"
  },
  "submissions": [
    {
      "name": "There's An AI For That",
      "slug": "theres-an-ai-for-that",
      "url": "https://theresanaiforthat.com",
      "listingUrl": "https://theresanaiforthat.com/ai/my-ai-tool",
      "domainRating": 81,
      "isSubmitted": true,
      "submittedBy": "ADMIN",
      "submittedAt": "2026-09-01T12:00:00.000Z"
    }
  ]
}

Customer support

Forward a question from your product UI; we answer from your knowledge base when we can, or a human replies in our dashboard. Off by default — until we enable it, POST /support/ask returns 403. Same X-API-Key as submit. MCP cannot call this.

Default mode is hybrid: AI answers when it can, otherwise the conversation stays pending for a human. We can set the client to human-only (no AI). Without product knowledge, questions wait for a person.

Send a question

POST https://www.aidirectori.es/api/v1/support/ask

curl -s -X POST "https://www.aidirectori.es/api/v1/support/ask" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "How do I cancel my subscription?",
    "externalId": "ticket-123",
    "customer": { "name": "Ada", "email": "ada@example.com" }
  }'

Hybrid/AI: 200 with status: "answered" means reply is ready (replySource is ai or human). pending means poll or wait for the webhook.

{
  "success": true,
  "data": {
    "id": "64a1b2c3d4e5f6789012345",
    "status": "answered",
    "externalId": "ticket-123",
    "reply": "You can cancel from Settings → Billing.",
    "replySource": "ai",
    "messages": [
      { "role": "customer", "content": "How do I cancel my subscription?" },
      { "role": "assistant", "content": "You can cancel from Settings → Billing.", "source": "ai" }
    ]
  }
}

Human-only clients get a slim envelope — no history, customer, or messages[]. message is null until a human replies, then a single agent message.

{
  "success": true,
  "data": {
    "id": "64a1b2c3d4e5f6789012345",
    "externalId": "ticket-123",
    "status": "pending",
    "message": null
  }
}

Poll a conversation

GET https://www.aidirectori.es/api/v1/support/conversations/:id — or list with ?id=, ?externalId=, or ?status=pending. Suggested interval while pending: 5–15 seconds. Hybrid list results omit the full messages array; human-only returns the same slim shape as ask.

curl -s "https://www.aidirectori.es/api/v1/support/conversations/64a1b2c3d4e5f6789012345" \
  -H "X-API-Key: YOUR_API_KEY"

Webhook when a reply is ready

If webhookUrl is set, we POST support.replied — same HMAC as directory Done. Hybrid/AI payload uses reply / replySource. Human-only uses a singular conversation.message with role: "agent" and source: "human".

{
  "event": "support.replied",
  "occurredAt": "2026-09-09T09:01:00.000Z",
  "conversation": {
    "id": "64a1b2c3d4e5f6789012345",
    "status": "answered",
    "externalId": "ticket-123",
    "reply": "You can cancel from Settings → Billing.",
    "replySource": "human"
  }
}

{
  "event": "support.replied",
  "occurredAt": "2026-09-11T12:00:00.000Z",
  "conversation": {
    "id": "64a1b2c3d4e5f6789012345",
    "externalId": "ticket-123",
    "status": "answered",
    "message": {
      "id": "...",
      "role": "agent",
      "source": "human",
      "content": "Thanks — here's how to cancel…",
      "createdAt": "2026-09-11T12:00:00.000Z"
    }
  }
}

Email support@thedirectori.es for a key, webhook URL, signing secret, or support access — or apply from Got a directory?.