API Endpoints

Explore the complete Forest SEO API through our interactive OpenAPI documentation. Test endpoints directly from this page with your API key.

---

🔌 Base URL

Base URL: https://api.forestseo.com

Use this URL for all integrations and API requests.

---

📡 Interactive API Explorer

The sections below provide comprehensive documentation for all API endpoints, generated from our OpenAPI specification.

How to Use This Documentation

1. Browse endpoints — Expand sections to view available operations
2. View schemas — See request/response models with type information
3. Try it out — Test endpoints directly (requires authentication)
4. Copy examples — Use generated code samples for your integration

---

🚀 Quick Start

Making Your First Request

# Replace YOUR_API_KEY and proj_abc123 with your actual credentials
curl -X GET "https://api.forestseo.com/v1/projects" \
  -H "Authorization: API-Key YOUR_API_KEY" \
  -H "Content-Type: application/json"

Required Headers

All authenticated requests must include:

Authorization: API-Key YOUR_API_KEY_HERE
Content-Type: application/json

For project-scoped endpoints, also include:

X-Project-ID: proj_abc123

---

📚 API Reference

---

🌐 API Versioning

Forest SEO API uses URL-based versioning:

https://api.forestseo.com/v1/*

Version Policy

• Current Version: v1 (stable)
• Backward Compatibility: We maintain backward compatibility within major versions
• Deprecation Notice: At least 6 months notice before removing any endpoint
• Version Support: Each major version supported for at least 12 months after successor release

---

📊 Response Format

All responses return data directly in JSON format:

Success Response (Single Resource)

{
  "id": "content_abc123",
  "slug": "example-article",
  "title": "Example Article",
  "status": "draft",
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:00:00Z",
  "locale": "en"
}

Paginated Response (List)

{
  "items": [
    {
      "id": "content_1",
      "title": "Article 1",
      "status": "draft"
    },
    {
      "id": "content_2",
      "title": "Article 2",
      "status": "published"
    }
  ],
  "total": 100,
  "page": 1,
  "size": 20,
  "pages": 5
}

Error Response

Validation Errors (HTTP 422):

{
  "detail": [
    {
      "loc": ["body", "title"],
      "msg": "field required",
      "type": "value_error.missing"
    },
    {
      "loc": ["body", "locale"],
      "msg": "invalid language code",
      "type": "value_error"
    }
  ]
}

General Errors (HTTP 400, 401, 403, 404, 500):

{
  "detail": "Resource not found"
}

or

{
  "detail": {
    "message": "Insufficient permissions",
    "code": "forbidden"
  }
}

---

🔍 Query Parameters

Common Pagination Parameters

Example:

GET /v1/contents?page=2&size=50&sort=-created_at

Filtering

Many endpoints support filtering via query parameters:

# Filter contents by status
GET /v1/contents?status=published

# Filter by language
GET /v1/contents?language=en

# Multiple filters
GET /v1/contents?status=published&language=en&page=1&size=20

---

⚡ Rate Limits

API requests are rate-limited based on your subscription plan:

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 115
X-RateLimit-Reset: 1640000000

Handling Rate Limits

When rate limited (HTTP 429), wait before retrying:

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please try again in 60 seconds.",
  "retry_after": 60
}

Best practices:

• Implement exponential backoff
• Cache responses when appropriate
• Batch operations where possible
• Monitor X-RateLimit-Remaining header

---

🛠️ Common Use Cases

1. List All Projects

curl -X GET "https://api.forestseo.com/v1/projects" \
  -H "Authorization: API-Key YOUR_API_KEY"

2. Create Content

curl -X POST "https://api.forestseo.com/v1/contents" \
  -H "Authorization: API-Key YOUR_API_KEY" \
  -H "X-Project-ID: proj_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "10 Tips for Better SEO",
    "language": "en",
    "keyword_cluster_id": "cluster_xyz789"
  }'

3. Publish Content

curl -X POST "https://api.forestseo.com/v1/publications" \
  -H "Authorization: API-Key YOUR_API_KEY" \
  -H "X-Project-ID: proj_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "content_id": "content_abc123",
    "integration_id": "int_wordpress_456"
  }'

4. List Published Content

curl -X GET "https://api.forestseo.com/v1/publications?status=published" \
  -H "Authorization: API-Key YOUR_API_KEY" \
  -H "X-Project-ID: proj_abc123"

5. Schedule Automated Generation

curl -X POST "https://api.forestseo.com/v1/schedules" \
  -H "Authorization: API-Key YOUR_API_KEY" \
  -H "X-Project-ID: proj_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Content Generation",
    "cron_expression": "0 9 * * *",
    "generation_count": 5,
    "language": "en",
    "enabled": true
  }'

---

🧪 Testing & Development

Using Postman

Import our OpenAPI spec into Postman:

1. Open Postman
2. Import → Link
3. Paste: https://api.forestseo.com/openapi.json
4. Configure authentication → API Key → Header: Authorization, Value: API-Key YOUR_KEY

Using Insomnia

Similar process for Insomnia REST client:

1. Create new Request Collection
2. Import → URL
3. Paste: https://api.forestseo.com/openapi.json
4. Add auth header to all requests

Interactive Documentation

Explore and test the API directly in your browser:

• Swagger UI: https://api.forestseo.com/docs/
• ReDoc: https://api.forestseo.com/redoc/

---

🔐 Security

HTTPS Required

All production API requests must use HTTPS. HTTP requests are rejected:

# ❌ This will fail in production
http://api.forestseo.com/v1/projects

# ✅ Always use HTTPS
https://api.forestseo.com/v1/projects

API Key Security

Secure practices:

• Store keys in environment variables
• Use backend-to-backend authentication
• Rotate keys regularly
• Disable unused keys immediately

---

📖 Related Documentation

Learn how to create and manage API keys

Platform-specific integration tutorials

Real-time webhooks for content delivery

Common API errors and solutions

---

🆘 Support

---

📝 Changelog

Stay updated with API changes:

• v1.2.0 (2024-03) — Added content scheduling endpoints
• v1.1.0 (2024-02) — Multi-language support for content generation
• v1.0.0 (2024-01) — Initial stable release