# 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](https://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:

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

### Authentication Endpoints

**Register**

```http
POST /auth/register
```

**Login**

```http
POST /auth/login
```

**Refresh Token**

```http
POST /auth/refresh
```

[View authentication details →](https://amistan.gitbook.io/aidp-docs/for-developers/authentication)

## Response Format

### Success Response

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

### Error Response

```json
{
  "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 →](https://amistan.gitbook.io/aidp-docs/for-developers/rate-limiting)

## Pagination

List endpoints support cursor-based pagination:

**Request**:

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

**Response**:

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

## API Endpoints

### Business API

Manage business profiles, services, and availability.

* [Business Profile](https://amistan.gitbook.io/aidp-docs/for-developers/api-reference/business)
  * Create, read, update, delete profiles
  * Manage services and pricing
  * Update availability and hours
  * Upload media

### Search API

Discover businesses with advanced filtering.

* [Search & Discovery](https://amistan.gitbook.io/aidp-docs/for-developers/api-reference/search)
  * Search businesses by location
  * Filter by category, rating, price
  * Sort and rank results
  * Get recommendations

### Booking API

Handle bookings and appointments.

* [Bookings](https://github.com/gugga7/aeo/blob/main/docs/gitbook/developers/api-reference/booking.md)
  * Check availability
  * Create bookings
  * Manage reservations
  * Handle cancellations

### Review API

Manage reviews and ratings.

* [Reviews & Ratings](https://github.com/gugga7/aeo/blob/main/docs/gitbook/developers/api-reference/review.md)
  * Submit reviews
  * Business responses
  * Moderation workflow
  * Rating aggregation

### Analytics API

Access upstream metrics and insights.

* [Analytics & Metrics](https://amistan.gitbook.io/aidp-docs/for-developers/api-reference/analytics)
  * Upstream metrics
  * Intent journeys
  * Competitive benchmarking
  * Attribution data

## SDKs

Official SDKs available:

**TypeScript/JavaScript**

```bash
npm install @aidp-protocol/core
```

**Python**

```bash
pip install aidp-sdk
```

[View SDK documentation →](https://amistan.gitbook.io/aidp-docs/for-developers/sdks)

## Code Examples

### TypeScript

```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

```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

```bash
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 →](https://amistan.gitbook.io/aidp-docs/for-developers/examples)

## Webhooks

Receive real-time notifications for events:

* Booking created/updated
* Review submitted
* Profile updated
* Payment processed

[Configure webhooks →](https://amistan.gitbook.io/aidp-docs/for-developers/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 →](https://amistan.gitbook.io/aidp-docs/for-developers/testing)

## Support

Need help with the API?

* 📚 **Documentation**: You're reading it!
* 💬 **GitHub Discussions**: [github.com/aidp/platform/discussions](https://github.com/aidp/platform/discussions)
* 📧 **Email**: <api@aidp.dev>
* 🐛 **Issues**: [GitHub Issues](https://github.com/aidp-platform/issues)

## Next Steps

* [Authentication Guide](https://amistan.gitbook.io/aidp-docs/for-developers/authentication)
* [Business API Reference](https://amistan.gitbook.io/aidp-docs/for-developers/api-reference/business)
* [Search API Reference](https://amistan.gitbook.io/aidp-docs/for-developers/api-reference/search)
* [Code Examples](https://amistan.gitbook.io/aidp-docs/for-developers/examples)