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.

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

Endpoints

GET/api/v1/credits

Check your current credit balance and subscription plan.

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

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

{
  "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.

SDK / npm Package

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

Install
pnpm add @aidirs/sdk
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 }
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

Check credits
curl https://aidirs.best/api/v1/credits \
  -H "Authorization: Bearer aidirs_your_key"
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)

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

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
Example 402 response body
{
  "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.