Status

Table of Contents

Blueberry IDP API Reference

Welcome to the Blueberry Internal Developer Platform API documentation. This section provides comprehensive reference for all REST API endpoints.

API Overview

The Blueberry API is built with FastAPI and provides REST endpoints for managing environments, configurations, webhooks, and platform operations.

  • Base URL: https://blueberry.florenciacomuzzi.com/api
  • Authentication: Firebase ID tokens or API tokens
  • Content Type: application/json
  • Version: v1 (default), v2 (beta)

Authentication

Firebase ID Tokens

For web UI and interactive usage:

Authorization: Bearer <firebase_id_token>

API Tokens

For CI/CD and automated usage:

Authorization: Bearer blb_<api_token>

Token Scopes:
- ENV_CREATE - Create and manage environments
- ENV_READ - Read environment information
- CONFIG_READ - Read configuration data
- CONFIG_WRITE - Manage configuration sets

API Endpoints

🌍 Environments

Core environment lifecycle management
- POST /api/environments - Create environment
- GET /api/environments - List environments
- GET /api/environments/{id} - Get environment details
- PUT /api/environments/{id} - Update environment
- DELETE /api/environments/{id} - Delete environment
- POST /api/environments/{id}/reconcile-status - Force status reconciliation

⚙️ Configuration Sets

Configuration management for environments
- GET /api/config-sets - List configuration sets
- POST /api/config-sets - Create configuration set
- GET /api/config-sets/{id} - Get configuration set
- PUT /api/config-sets/{id} - Update configuration set
- DELETE /api/config-sets/{id} - Delete configuration set

🔑 API Tokens

API token management
- GET /api/tokens - List user's API tokens
- POST /api/tokens - Create new API token
- DELETE /api/tokens/{id} - Revoke API token
- GET /api/tokens/{id}/value - Get token value

🔗 Webhooks

External integrations and event handling
- POST /api/webhooks/generic - Generic webhook endpoint
- POST /api/webhooks/gitlab/pipeline - GitLab pipeline webhook
- POST /api/webhooks/github - GitHub webhook
- POST /api/webhooks/environment/event - Environment event webhook

📊 Observability

Monitoring, metrics, and cost tracking
- GET /api/observability/costs/dashboard - Cost dashboard
- GET /api/observability/costs/summary - Cost summary
- GET /api/observability/metrics - Platform metrics
- GET /api/observability/slo/status - SLO status

📈 Insights

Analytics and dashboard views
- GET /api/insights/dashboard - Main insights dashboard
- GET /api/insights/environments/analytics - Environment analytics
- GET /api/insights/users/activity - User activity insights
- GET /api/insights/costs/analysis - Cost analysis

📚 Repositories

Repository configuration management
- GET /api/repos - List available repositories
- GET /api/repos/{id} - Get repository configuration
- POST /api/repos/reload - Reload repository configurations

🏥 Health

Service health and status endpoints
- GET /api/health - Basic health check
- GET /api/ready - Readiness probe
- GET /api/status - Detailed health status

🔐 Authentication

User authentication and management
- POST /api/auth/password-reset - Request password reset
- GET /api/auth/user - Get current user info

🎛️ Helm

Helm chart configuration helpers
- GET /api/helm/config-template - Get Helm values template

🎪 Demos

Demo and example endpoints
- GET /api/demos/dashboard - Demo dashboard
- POST /api/demos/sample-environment - Create demo environment

API Versions

v1 (Current)

  • Endpoint: /api/*
  • Status: Stable
  • Authentication: Firebase tokens primarily

v2 (Beta)

  • Endpoint: /api/v2/*
  • Status: Beta
  • Authentication: Unified (Firebase + API tokens)
  • Features: Enhanced authentication support

Response Format

Success Response

{
  "status": "success",
  "data": { ... },
  "timestamp": "2024-01-01T00:00:00Z"
}

Error Response

{
  "detail": "Error message",
  "status_code": 400,
  "timestamp": "2024-01-01T00:00:00Z"
}

HTTP Status Codes

  • 200 - Success
  • 201 - Created
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 409 - Conflict
  • 429 - Rate Limited
  • 500 - Internal Server Error
  • 503 - Service Unavailable

Rate Limiting

API requests are rate limited:
- Authenticated requests: 100 requests/minute
- Unauthenticated requests: 10 requests/minute
- Webhook endpoints: 1000 requests/minute

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Common Parameters

Query Parameters

  • limit - Maximum number of results (default: 50, max: 100)
  • offset - Number of results to skip (default: 0)
  • search - Search query string
  • status - Filter by status
  • created_after - ISO timestamp filter
  • created_before - ISO timestamp filter

Headers

  • Content-Type: application/json - Required for POST/PUT requests
  • Authorization: Bearer <token> - Authentication token
  • X-Request-ID: <uuid> - Optional request tracing ID

SDK and Clients

Python SDK

pip install blueberry-sdk

JavaScript/TypeScript

npm install @blueberry/sdk

CLI Tool

curl -sSL https://install.blueberry.com | sh

Getting Started

  1. Get API Token: Create an API token in the web UI
  2. Test Connection: curl -H "Authorization: Bearer <token>" https://blueberry.florenciacomuzzi.com/api/health
  3. Create Environment: See Environment API guide
  4. Explore Endpoints: Use the interactive API docs at /docs

Interactive Documentation

  • Swagger UI: https://blueberry.florenciacomuzzi.com/docs
  • ReDoc: https://blueberry.florenciacomuzzi.com/redoc

Support

  • 📚 Guides - Conceptual documentation
  • 📋 Workflows - Step-by-step procedures
  • 🐛 Troubleshooting - Common issues
  • 💬 Slack: #blueberry-support
  • 📧 Email: platform-team@example.com

Last Updated: January 2024 | API Version: v1.0.0

Document ID: reference/api/README