# API Documentation

> REST API for custom integrations with Serenza.

Serenza provides a REST API for integrating with other systems and building custom workflows.

## Overview

### Base URL
```
https://serenzaweddings.com/api/v1/
```

### Authentication
- Token-based authentication
- API keys per user
- Rate limiting applied

### Response Format
- JSON responses
- Consistent error handling
- Pagination support

## Endpoints

### Events
- `GET /api/v1/events/` — List events
- `GET /api/v1/events/{id}/` — Get event details
- `POST /api/v1/events/` — Create event
- `PUT /api/v1/events/{id}/` — Update event
- `DELETE /api/v1/events/{id}/` — Delete event

### Guests
- `GET /api/v1/events/{id}/guests/` — List guests
- `GET /api/v1/events/{id}/guests/{id}/` — Get guest
- `POST /api/v1/events/{id}/guests/` — Create guest
- `PUT /api/v1/events/{id}/guests/{id}/` — Update guest
- `DELETE /api/v1/events/{id}/guests/{id}/` — Delete guest
- `POST /api/v1/events/{id}/guests/import/` — Import guests (CSV)

### Vendors
- `GET /api/v1/vendors/` — List vendors
- `GET /api/v1/vendors/{id}/` — Get vendor
- `POST /api/v1/vendors/` — Create vendor
- `PUT /api/v1/vendors/{id}/` — Update vendor
- `DELETE /api/v1/vendors/{id}/` — Delete vendor

### Tasks
- `GET /api/v1/events/{id}/tasks/` — List tasks
- `GET /api/v1/events/{id}/tasks/{id}/` — Get task
- `POST /api/v1/events/{id}/tasks/` — Create task
- `PUT /api/v1/events/{id}/tasks/{id}/` — Update task
- `DELETE /api/v1/events/{id}/tasks/{id}/` — Delete task
- `PATCH /api/v1/events/{id}/tasks/{id}/toggle/` — Toggle complete

### Timeline
- `GET /api/v1/events/{id}/timeline/` — List timeline events
- `POST /api/v1/events/{id}/timeline/` — Create timeline event
- `PUT /api/v1/events/{id}/timeline/{id}/` — Update timeline event

### Seating
- `GET /api/v1/events/{id}/floor-plans/` — List floor plans
- `POST /api/v1/events/{id}/floor-plans/` — Create floor plan
- `GET /api/v1/events/{id}/floor-plans/{id}/` — Get floor plan
- `POST /api/v1/events/{id}/floor-plans/{id}/tables/` — Create table
- `POST /api/v1/events/{id}/floor-plans/{id}/assign/` — Assign seat

## Webhooks

### Supported Events
- `event.created` — New wedding created
- `event.updated` — Wedding updated
- `guest.rsvp_changed` — RSVP status changed
- `task.completed` — Task marked complete
- `vendor.rfq_sent` — RFQ sent to vendor
- `vendor.quote_received` — Quote received

### Webhook Payload
```json
{
  "event": "guest.rsvp_changed",
  "timestamp": "2026-01-15T10:30:00Z",
  "data": {
    "guest_id": 123,
    "event_id": 456,
    "old_status": "pending",
    "new_status": "confirmed"
  }
}
```

### Configuration
- Set webhook URL in settings
- Choose events to subscribe to
- Retry logic for failed deliveries
- Log all webhook attempts

## Rate Limits

- **Standard:** 100 requests per minute
- **Enterprise:** Custom limits
- **Burst:** 10 requests per second

## Error Handling

### Error Response
```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid guest email",
    "details": {
      "email": "Enter a valid email address."
    }
  }
}
```

### Common Error Codes
- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not found
- `429` — Rate limit exceeded
- `500` — Server error

## SDKs & Libraries

### Official
- Python SDK (coming soon)
- JavaScript SDK (coming soon)

### Community
- Community-maintained libraries welcome

## Support

- API documentation: `/api/docs/`
- Developer support: api@serenzaweddings.com
- Status page: status.serenzaweddings.com

## Related Features

- [Complete Features](features.md)
- [Getting Started](getting-started.md)
- [Pricing Plans](pricing.md)