# 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 →](/aidp-docs/for-developers/authentication.md)

## 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 →](/aidp-docs/for-developers/rate-limiting.md)

## 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](/aidp-docs/for-developers/api-reference/business.md)
  * Create, read, update, delete profiles
  * Manage services and pricing
  * Update availability and hours
  * Upload media

### Search API

Discover businesses with advanced filtering.

* [Search & Discovery](/aidp-docs/for-developers/api-reference/search.md)
  * 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](/aidp-docs/for-developers/api-reference/analytics.md)
  * 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 →](/aidp-docs/for-developers/sdks.md)

## 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 →](/aidp-docs/for-developers/examples.md)

## Webhooks

Receive real-time notifications for events:

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

[Configure webhooks →](/aidp-docs/for-developers/webhooks.md)

## 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 →](/aidp-docs/for-developers/testing.md)

## 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](/aidp-docs/for-developers/authentication.md)
* [Business API Reference](/aidp-docs/for-developers/api-reference/business.md)
* [Search API Reference](/aidp-docs/for-developers/api-reference/search.md)
* [Code Examples](/aidp-docs/for-developers/examples.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://amistan.gitbook.io/aidp-docs/for-developers/api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.