API Design¶

Subscribe Flow follows RESTful API design principles with OpenAPI 3.1 documentation.

Base URL¶

1

https://api.subscribeflow.net/v1

Local: http://localhost:8000/api/v1

Authentication¶

All API requests (except Health Check) require authentication:

1
2

curl -H "Authorization: Bearer sf_live_xxxxx" \
  https://api.subscribeflow.net/v1/subscribers

1
2

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  https://api.subscribeflow.net/v1/subscribers

Request/Response Format¶

Content-Type¶

• Request: application/json
• Response: application/json

Response Envelope¶

All responses follow a consistent format:

1
2
3
4
5
6

{
  "data": {
    "id": "uuid",
    "email": "user@example.com"
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "data": [
    {"id": "uuid1", "email": "user1@example.com"},
    {"id": "uuid2", "email": "user2@example.com"}
  ],
  "meta": {
    "total": 100,
    "page": 1,
    "per_page": 20
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  "error": {
    "code": "validation_error",
    "message": "Invalid email format",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address"
      }
    ]
  }
}

Endpoints¶

Subscribers¶

Tags¶

Preference Center¶

Webhooks¶

Pagination¶

List endpoints support pagination:

1

GET /api/v1/subscribers?page=2&per_page=50

Response:

1
2
3
4
5
6
7
8
9

{
  "data": [...],
  "meta": {
    "total": 1000,
    "page": 2,
    "per_page": 50,
    "total_pages": 20
  }
}

Filtering¶

Filters are passed as query parameters:

1
2
3
4
5
6
7
8

# Filter subscribers by status
GET /api/v1/subscribers?status=active

# Filter tags by category
GET /api/v1/tags?category=newsletter

# Combined filters
GET /api/v1/subscribers?status=active&tag=product-updates

Sorting¶

1
2
3
4
5
6
7
8

# Ascending (default)
GET /api/v1/subscribers?sort=created_at

# Descending
GET /api/v1/subscribers?sort=-created_at

# Multiple fields
GET /api/v1/subscribers?sort=-created_at,email

Rate Limiting¶

Rate Limit Headers:

1
2
3

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

Error Codes¶

Idempotency¶

POST requests can be made idempotent:

1
2
3

curl -X POST /api/v1/subscribers \
  -H "Idempotency-Key: unique-request-id" \
  -d '{"email": "user@example.com"}'

Versioning¶

The API version is included in the URL path:

1
2

/api/v1/subscribers  # Version 1
/api/v2/subscribers  # Version 2 (future)

OpenAPI Documentation¶

• Swagger UI: /docs
• ReDoc: /redoc
• OpenAPI JSON: /openapi.json