Skip to main content

​
Welcome to Cloud API

Cloud API provides a comprehensive REST API for building AI-powered web applications. Our platform enables developers to implement user authentication, project management, API key administration, and AI image generation capabilities with minimal setup.

​
Base URLs

The API is available on two production servers with identical functionality:
  • Dev Kit for AI: https://api.devkit4ai.com
  • Vibe Coding Platform: https://api.vibecoding.ad
Both servers are production-ready and offer the same features. Choose based on your preferred domain or use one as primary and the other as backup.

​
Authentication & Authorization

Cloud API uses a role-based access control (RBAC) system with three distinct user roles. Authentication is handled via JWT tokens combined with role-specific headers.

​
User Roles

​
platform_operator
role
Platform Operators manage the entire Dev Kit for AI platform. They have full access to all resources and can create developer accounts. Operators are created directly in the backend database.
​
developer
role
Developers build AI-powered applications using the Starter Kit. They can create projects, generate API keys, manage end users, and access the Cloud Admin console. Developers register via Register Developer endpoint with an operator key.
​
end_user
role
End Users are users of applications built with the Starter Kit. They are scoped to specific projects and can access project-specific features. End users register via the Starter Kit’s registration flow.

​
Authentication Methods

​
JWT Bearer Tokens

All authenticated requests require a JWT access token obtained from the Login endpoint: 
curl -X GET https://api.vibecoding.ad/api/v1/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Token Lifecycle:
  • Access Tokens: Expire after 30 minutes
  • Refresh Tokens: Expire after 7 days
  • Use Refresh Token endpoint to obtain new access tokens

​
Role-Specific Headers

Different operations require specific headers based on your role: Platform Operators: 
X-User-Role: platform_operator
X-Operator-Key: <your_operator_key>
Developers: 
X-User-Role: developer
X-Developer-Key: <your_developer_key>
End Users (Project-Scoped): 
X-User-Role: end_user
X-Developer-Key: <project_developer_key>
X-Project-ID: <project_uuid>
X-API-Key: <project_api_key>
Always include the appropriate role header (X-User-Role) and authentication credentials for your user type. Missing or incorrect headers will result in 403 Forbidden errors.

​
API Keys

​
Developer Keys

Developer keys authenticate API requests with developer-level permissions. Format: ak_ + 32 characters. Management: Limits: Maximum 10 active developer keys per account.

​
Project API Keys

Project-scoped keys authenticate end user operations within a specific project. Management: (((REPLACE_THIS_WITH_IMAGE: cloud-api-authentication-flow.png: Diagram showing authentication flow from registration through login to API calls with JWT tokens and role headers)))

​
Rate Limits & Quotas

Cloud API implements rate limiting to ensure fair usage and system stability. Limits vary by subscription tier and endpoint category.

​
Rate Limit Headers

Every API response includes rate limit information: 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1670425200
  • X-RateLimit-Limit: Maximum requests per window
  • X-RateLimit-Remaining: Requests remaining in current window
  • X-RateLimit-Reset: Unix timestamp when limit resets

​
Subscription Tiers

Free Starter

1,000 requests/day
  • Basic AI generation (100/month)
  • 1 project
  • Community support

Cloud Starter

10,000 requests/day
  • Advanced AI generation (1,000/month)
  • 5 projects
  • Email support
  • Priority processing

Cloud Premium

100,000 requests/day
  • Unlimited AI generation
  • Unlimited projects
  • Priority support
  • Dedicated infrastructure
  • Source code access (on-demand)

​
Rate Limit by Endpoint Category

CategoryFree TierCloud StarterCloud Premium
Authentication100/hour500/hour2,000/hour
Project Management1,000/day10,000/dayUnlimited
AI Generation100/month1,000/monthUnlimited
Anonymous Generation10/dayN/AN/A

​
Rate Limit Exceeded Response

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "detail": "Rate limit exceeded. Try again in 3600 seconds.",
  "retry_after": 3600
}
Best Practice: Implement exponential backoff when receiving 429 responses. Wait for the duration specified in retry_after or the X-RateLimit-Reset header.

​
Quota Management

Monitor your usage via the Cloud Admin console or programmatically through the Project Stats endpoint.

​
API Categories

Health Check

Monitor system health and component status

Authentication

User registration, login, and email verification

Project Management

Manage projects and API keys

AI Generation

Create and manage AI-powered image generations

​
Getting Started

1

Register as Developer

Create your developer account via Cloud Admin or Register endpoint.
2

Obtain Developer Key

After registration, you’ll receive your developer key, project ID, and project API key.
3

Clone Starter Kit

Clone the Starter Kit repository to build your application.
4

Configure Environment

Set up your environment variables with your credentials. See Environment Config.
5

Make Your First API Call

Follow the Quick Start guide for a hands-on tutorial.

​
Response Format

All API responses follow a consistent structure with proper HTTP status codes.

​
Success Response (2xx)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Project",
  "is_active": true,
  "created_at": "2025-12-08T10:30:00Z"
}

​
Error Response (4xx, 5xx)

{
  "detail": "Authentication credentials were not provided"
}

​
Validation Error (422)

{
  "detail": [
    {
      "loc": ["body", "email"],
      "msg": "value is not a valid email address",
      "type": "value_error.email"
    }
  ]
}

​
API Version

Current Version: 1.5.0 The API version is included in all endpoint paths (e.g., /api/v1/auth/login). Breaking changes will increment the major version number.

​
OpenAPI Specification

The complete API specification is available in OpenAPI 3.1.0 format. You can:
  • View Interactive Docs: Use the built-in API playground in each endpoint page
  • Download Spec: Available at /cloud-api/openapi.json
  • Import to Tools: Compatible with Postman, Insomnia, and other OpenAPI clients

​
Support & Resources

Quick Start

Get started with hands-on examples

Starter Kit Guide

Build your first application

Cloud Admin Console

Manage projects via web interface

Platform Overview

Understand the Dev Kit architecture
Need Help?
For production deployments, always use HTTPS endpoints and store API keys securely in environment variables or secrets managers.