Publisher Guide

🚀 Getting Started

Publishing your API on ARDF takes less than 5 minutes and gives you instant access to AI agents searching for services like yours.

Quick Overview

1. Create an ARDF account (free)
2. Submit your API details via POST endpoint
3. Wait for automatic verification (1-24 hours)
4. Your API appears in semantic search results
5. Track usage and analytics in your dashboard

📋 Requirements

📝 How to Submit Your API

Step 1: Get Your API Key

First, register for an ARDF account and generate your API key:

# Register
curl -X POST http://127.0.0.1:3001/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "username": "yourcompany",
    "password": "secure_password"
  }'

# Login to get JWT
curl -X POST http://127.0.0.1:3001/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "secure_password"
  }'

# Generate API key (using JWT from login)
curl -X POST http://127.0.0.1:3001/api/auth/api-key \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Step 2: Submit Your Skill

Use the /api/skills/publish endpoint with your API key:

curl -X POST http://127.0.0.1:3001/api/skills/publish \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Your API Name",
    "description": "Detailed description for semantic search. Include use cases and key features.",
    "long_description": "Extended explanation of what your API does, how it works, and why agents should use it.",
    "category": "api",
    "capabilities": ["email", "transactional", "notifications"],
    "tags": ["nodejs", "python", "email", "saas"],
    "endpoint": "https://api.yourservice.com/v1",
    "auth_type": "api_key",
    "docs_url": "https://docs.yourservice.com",
    "homepage_url": "https://yourservice.com",
    "github_url": "https://github.com/yourorg/api",
    "pricing_model": "freemium",
    "cost_estimate": "Free up to 1000 requests/month, then $29/mo",
    "code_snippet": "const result = await yourAPI.send({ to: \"[email protected]\" });"
  }'

Step 3: Verification

Our automated system will:

• Verify your endpoint is accessible
• Check SSL certificate validity
• Test documentation links
• Generate semantic embeddings for your description
• Assign initial trust score (based on domain age, SSL, docs quality)

Verification typically takes 1-24 hours. You'll receive an email when complete.

📖 Field Descriptions

💎 Best Practices for Semantic Discovery

1. Write AI-First Descriptions

❌ Bad: "Modern email API"

✅ Good: "Send transactional emails, password resets, notifications, and marketing campaigns with high deliverability"

2. Include Use Cases

Mention specific scenarios where your API shines:

• "Perfect for password resets"
• "Ideal for processing credit cards"
• "Great for authenticating users with social logins"

3. List Comprehensive Capabilities

The capabilities array is crucial for matching. Be specific:

// Generic (less discovery)
"capabilities": ["email"]

// Specific (more discovery)
"capabilities": [
  "email",
  "transactional",
  "marketing",
  "templates",
  "smtp",
  "webhooks",
  "notifications",
  "password_reset",
  "welcome_emails"
]

4. Provide Clear Pricing

Agents need to know costs upfront:

• ✅ "Free up to 100 emails/day, then $20/month"
• ✅ "$0.001 per API call"
• ✅ "Free forever for open source projects"
• ❌ "Contact sales"

5. Add Quality Code Snippets

Show the simplest possible usage:

// Quick, clear, copy-pasteable
import { YourAPI } from '@yourapi/sdk';

const api = new YourAPI('API_KEY');
const result = await api.send({
  to: '[email protected]',
  subject: 'Password Reset',
  template: 'password-reset'
});

🛡️ Trust Score & Verification

Your trust score determines ranking in search results. It's calculated using:

trust_score = (success_rate * 40) +
              (uptime_7d * 30) +
              (rating * 20) +
              (verified * 10)

How to Improve Your Trust Score

• Maintain High Uptime: Keep your API available 99.5%+
• Fast Response Times: Average < 500ms is ideal
• Get Verified: Complete manual verification (+10 points)
• Gather Reviews: Encourage users to rate your API
• Usage Success: Low error rates boost your score
• Quality Documentation: Comprehensive docs = higher trust

💰 Publisher Pricing Tiers

Start with Free Listing. Upgrade anytime to boost visibility.

📊 Analytics & Insights

Once published, you get access to:

• Discovery Metrics: How many times your API appeared in search results
• Click-Through Rate: Percentage of searchers who clicked your listing
• Popular Queries: What intents led agents to your API
• Usage Tracking: API calls made through ARDF referrals
• Success Rate: Percentage of successful API calls
• Average Latency: Response time metrics
• Trust Score Trends: How your score changes over time

Access your dashboard at: /ardf/dashboard

💬 Support & Community

Need Help?

• Documentation: API Reference
• Email: [email protected]
• Discord: Join our community (link)
• GitHub: Report issues and request features

Frequently Asked Questions

Q: How long does verification take?

A: Automated verification: 1-24 hours. Manual verification (for badge): 2-5 business days after you request it.

Q: Can I update my listing?

A: Yes! Use the same POST endpoint with your API key. Updates are reflected immediately.

Q: Does ARDF handle billing for my API?

A: No. Publishers handle their own billing and authentication. ARDF provides discovery and routing only. You keep 100% of your revenue.

Q: Can I remove my listing?

A: Yes, anytime. Contact support or use the DELETE endpoint with your skill ID.

Q: What if my API changes endpoint or pricing?

A: Submit an update via the publish endpoint. We'll re-verify and update your listing within 24 hours.