API Reference

Complete reference for the AIDP Platform REST API.

Base URL

Production: https://api.aidp.dev/v1
Staging: https://staging-api.aidp.dev/v1
Development: http://localhost:3000/api/v1

Authentication

All API requests require authentication using JWT tokens.

Getting an API Key

1. Sign up at platform.aidp.dev

2. Navigate to Settings > API Keys

3. Create a new API key

4. Store securely (never commit to version control)

Using API Keys

Include your API key in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.aidp.dev/v1/businesses/search

Authentication Endpoints

Register

POST /auth/register

Login

POST /auth/login

Refresh Token

POST /auth/refresh

View authentication details →

Response Format

Success Response

{
  "success": true,
  "data": {
    // Response data
  },
  "meta": {
    "timestamp": "2025-12-07T10:30:00Z",
    "requestId": "req_abc123"
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "field": "email",
      "issue": "Invalid email format"
    }
  },
  "meta": {
    "timestamp": "2025-12-07T10:30:00Z",
    "requestId": "req_abc123"
  }
}

Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
429	Too Many Requests
500	Internal Server Error

Rate Limiting

Limits:

• Free tier: 100 requests/hour

• Professional: 1,000 requests/hour

• Enterprise: 10,000 requests/hour

Headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1638360000

Learn more about rate limiting →

Pagination

List endpoints support cursor-based pagination:

Request:

GET /businesses/search?limit=20&cursor=eyJpZCI6ImJpel8xMjMifQ

Response:

{
  "success": true,
  "data": {
    "businesses": [...],
    "pagination": {
      "hasMore": true,
      "nextCursor": "eyJpZCI6ImJpel8xNDMifQ",
      "total": 150
    }
  }
}

API Endpoints

Business API

Manage business profiles, services, and availability.

• Business Profile

  • Create, read, update, delete profiles

  • Manage services and pricing

  • Update availability and hours

  • Upload media

Search API

Discover businesses with advanced filtering.

• Search & Discovery

  • Search businesses by location

  • Filter by category, rating, price

  • Sort and rank results

  • Get recommendations

Booking API

Handle bookings and appointments.

• Bookings

  • Check availability

  • Create bookings

  • Manage reservations

  • Handle cancellations

Review API

Manage reviews and ratings.

• Reviews & Ratings

  • Submit reviews

  • Business responses

  • Moderation workflow

  • Rating aggregation

Analytics API

Access upstream metrics and insights.

• Analytics & Metrics

  • Upstream metrics

  • Intent journeys

  • Competitive benchmarking

  • Attribution data

SDKs

Official SDKs available:

TypeScript/JavaScript

npm install @aidp-protocol/core

Python

pip install aidp-sdk

View SDK documentation →

Code Examples

TypeScript

import { AIDPClient } from '@aidp-protocol/core';

const client = new AIDPClient({
  apiKey: process.env.AIDP_API_KEY,
  environment: 'production',
});

// Search businesses
const results = await client.businesses.search({
  location: { city: 'Portland', country: 'USA' },
  category: 'restaurants',
  filters: { verified: true, openNow: true },
});

console.log(results.businesses);

Python

from aidp import AIDPClient

client = AIDPClient(
    api_key=os.environ['AIDP_API_KEY'],
    environment='production'
)

# Search businesses
results = client.businesses.search(
    location={'city': 'Portland', 'country': 'USA'},
    category='restaurants',
    filters={'verified': True, 'open_now': True}
)

print(results['businesses'])

cURL

curl -X GET \
  'https://api.aidp.dev/v1/businesses/search?city=Portland&category=restaurants' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json'

View more examples →

Webhooks

Receive real-time notifications for events:

• Booking created/updated

• Review submitted

• Profile updated

• Payment processed

Configure webhooks →

Testing

Sandbox Environment

Test your integration without affecting production:

Sandbox: https://sandbox-api.aidp.dev/v1

Test Data

Use test API keys for development:

Test Key: sk_test_abc123...

Learn about testing →

Support

Need help with the API?

• 📚 Documentation: You're reading it!

• 💬 GitHub Discussions: github.com/aidp/platform/discussions

• 📧 Email: [e-mail]

• 🐛 Issues: GitHub Issues

Next Steps

• Authentication Guide

• Business API Reference

• Search API Reference

• Code Examples