LogoAidirs

Developer API

Submit AI Tools Programmatically

Use the REST API or npm SDK to submit AI tools, check your credits, and attach optional promotional placements from your own workflow.

1. Get API Key

Create a key from the API Keys page

2. Check Credits

View balance and buy more from API Keys

3. Start Submitting

Call the API or use the SDK

Authentication

All API requests require a Bearer token in the Authorization header. Create your API key and manage your credits from the API Keys page.

http
Authorization header
Authorization: Bearer aidirs_your_api_key_here

Your API key is shown only once when generated. Store it securely and never expose it in client-side code.

Credits & Plans

API submissions use a base plan plus optional promotional add-ons. You can check your remaining credits and buy more from the API Keys page before submitting.

starter

1 credit

Base submission with standard review

Popular
pro

3 credits

Featured submission with stronger placement

add-ons

optional

Attach sidebar spotlight or hero sponsor placements

Promotion add-ons

sidebar_spotlight_7d
Sidebar Spotlight · 7 days
3 credits
sidebar_spotlight_30d
Sidebar Spotlight · 30 days
6 credits
sidebar_spotlight_365d
Sidebar Spotlight · 365 days
41 credits
hero_page_7d
Hero Sponsor · 7 days
6 credits
hero_page_30d
Hero Sponsor · 30 days
10 credits
hero_page_365d
Hero Sponsor · 365 days
71 credits

Endpoints

GET/api/v1/credits

Check your current credit balance and subscription plan.

json
Response
{
  "credits": 8,
  "plan": "free"
}
POST/api/v1/submit

Submit an AI tool to the directory. Name and description are automatically generated by AI.

json
{
  "url": "https://example.com",
  "plan": "starter",
  "addonIds": ["sidebar_spotlight_30d"]
}

Required fields: url, plan (starter | pro). Optional field: addonIds. Submissions always enter pending review, and product details are auto-filled by AI before admin review.

Optional promotion add-ons

sidebar_spotlight_7d
Sidebar Spotlight · 7 days
3 credits
sidebar_spotlight_30d
Sidebar Spotlight · 30 days
6 credits
sidebar_spotlight_365d
Sidebar Spotlight · 365 days
41 credits
hero_page_7d
Hero Sponsor · 7 days
6 credits
hero_page_30d
Hero Sponsor · 30 days
10 credits
hero_page_365d
Hero Sponsor · 365 days
71 credits

Credits are calculated as base plan + selected add-ons. Example:starter + sidebar_spotlight_30d = 10 credits.

SDK / npm Package

Use the official @aidirs/sdk package for a type-safe, zero-config experience in Node.js / TypeScript projects.

bash
Install
pnpm add @aidirs/sdk
typescript
Usage
import { Aidirs } from "@aidirs/sdk";

const client = new Aidirs({ apiKey: process.env.AIDIRS_API_KEY! });

// Check credits
const { credits, plan } = await client.credits();
console.log(`Credits: ${credits}, Plan: ${plan}`);

// Submit a tool
const result = await client.submit({
  url: "https://example.com",
  plan: "pro",
  addonIds: ["hero_page_30d"],
});

console.log(result);
// { status, url, reviewStatus, creditsUsed, creditsRemaining }
typescript
Batch submit
// Submit multiple tools — stops early on 402 (no credits)
const { results, errors } = await client.batchSubmit([
  { url: "https://tool-a.com", plan: "starter" },
  { url: "https://tool-b.com", plan: "pro", addonIds: ["sidebar_spotlight_30d"] },
  { url: "https://tool-c.com", plan: "starter", addonIds: ["hero_page_7d"] },
]);

console.log(`Submitted: ${results.length}, Errors: ${errors.length}`);

SDK Features

Full TypeScript types
Auto error parsing
Batch submit helper
Rate-limit aware retries
ESM & CJS dual build
Zero dependencies

Code Examples

cURL

bash
Check credits
curl https://aidirs.best/api/v1/credits \
  -H "Authorization: Bearer aidirs_your_key"
bash
Submit a tool
curl -X POST https://aidirs.best/api/v1/submit \
  -H "Authorization: Bearer aidirs_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "plan": "starter",
    "addonIds": ["sidebar_spotlight_30d"]
  }'

Node.js (fetch)

javascript
submit.mjs
const API_KEY = process.env.AIDIRS_API_KEY;
const BASE = "https://aidirs.best";

async function submitTool(url, plan = "starter", addonIds = []) {
  const res = await fetch(`${BASE}/api/v1/submit`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ url, plan, addonIds }),
  });

  if (!res.ok) {
    const err = await res.json();
    throw new Error(err.error || res.statusText);
  }

  return res.json();
}

const result = await submitTool("https://example.com", "pro", ["hero_page_30d"]);
console.log(result);

Python

python
submit.py
import os, requests

API_KEY = os.environ["AIDIRS_API_KEY"]
BASE = "https://aidirs.best"

def submit_tool(url: str, plan: str = "starter", addon_ids=None):
    addon_ids = addon_ids or []
    res = requests.post(
        f"{BASE}/api/v1/submit",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={"url": url, "plan": plan, "addonIds": addon_ids},
    )
    res.raise_for_status()
    return res.json()

result = submit_tool("https://example.com", "pro", ["hero_page_30d"])
print(result)

Error Handling

400Invalid request body or URL
401Missing or invalid API key
402Insufficient credits
409URL already submitted
429Rate limit exceeded
json
Error response format
{
  "error": "Insufficient credits",
  "required": 2,
  "available": 1
}

Rate Limits

10 requests / minute

Per API key. Exceeding this limit returns a 429 status code. Retry after 60 seconds.