API Reference

Complete reference documentation for the CloudBooks REST API. Build powerful integrations and automate your workflows with our comprehensive API.

RESTful API
OAuth 2.0 & API Keys
JSON Responses

Quick Start

Get started with the CloudBooks API in minutes. Follow our comprehensive guides and examples to integrate CloudBooks into your applications.

RESTful architecture
JSON request and response format
Standard HTTP response codes
Rate limiting and pagination

Base URL

https://api.cloudbooks.com/v1

Authentication

Authorization: Bearer YOUR_API_KEY

Contents

Get Support

Getting Started

The CloudBooks API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Prerequisites

  • A CloudBooks account (sign up for free at cloudbooks.com)
  • An API key (generate from your dashboard)
  • Basic understanding of REST APIs and HTTP

Making Your First Request

Here's a simple example to get you started. This request retrieves your user profile:

curl
curl -X POST https://api.cloudbooks.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your_password"
  }'

Authentication

The CloudBooks API uses API keys to authenticate requests. You can view and manage your API keys in the CloudBooks Dashboard.

Security Best Practices

  • •Keep your API keys secure and never share them publicly
  • •Use environment variables to store API keys
  • •Rotate API keys regularly
  • •Use different keys for production and testing

Authentication Methods

API Key Authentication

Include your API key in the Authorization header of every request:

Authorization: Bearer sk_live_1234567890abcdef

OAuth 2.0

For applications that need to access user data on behalf of other users:

Authorization: Bearer user_access_token

API Endpoints

Authentication

POST/auth/login

Authenticate user and get access token

POST/auth/refreshAuth required

Refresh access token

POST/auth/logoutAuth required

Invalidate access token

Users

GET/users/meAuth required

Get current user profile

PUT/users/meAuth required

Update current user profile

GET/users/{id}Auth required

Get user by ID

DELETE/users/meAuth required

Delete current user account

Organizations

GET/organizationsAuth required

List all organizations

POST/organizationsAuth required

Create new organization

GET/organizations/{id}Auth required

Get organization by ID

PUT/organizations/{id}Auth required

Update organization

DELETE/organizations/{id}Auth required

Delete organization

Projects

GET/projectsAuth required

List all projects

POST/projectsAuth required

Create new project

GET/projects/{id}Auth required

Get project by ID

PUT/projects/{id}Auth required

Update project

DELETE/projects/{id}Auth required

Delete project

Code Examples

Here are examples in multiple programming languages to help you get started quickly:

JavaScript / Node.js

javascript
const response = await fetch('https://api.cloudbooks.com/v1/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'your_password'
  })
});

const data = await response.json();
console.log(data);

TypeScript

typescript
interface LoginRequest {
  email: string;
  password: string;
}

interface LoginResponse {
  token: string;
  user: User;
}

async function login(credentials: LoginRequest): Promise<LoginResponse> {
  const response = await fetch('https://api.cloudbooks.com/v1/auth/login', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(credentials)
  });

  if (!response.ok) {
    throw new Error('Login failed');
  }

  return response.json();
}

Python

python
import requests

url = 'https://api.cloudbooks.com/v1/auth/login'
payload = {
    'email': 'user@example.com',
    'password': 'your_password'
}

response = requests.post(url, json=payload)
data = response.json()
print(data)

Error Handling

CloudBooks uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success, codes in the 4xx range indicate an error from the provided information, and codes in the 5xx range indicate server errors.

200

OK

Request succeeded

201

Created

Resource successfully created

400

Bad Request

Invalid request parameters

401

Unauthorized

Authentication credentials missing or invalid

403

Forbidden

Authenticated but lacks permissions

404

Not Found

Requested resource does not exist

429

Too Many Requests

Rate limit exceeded

500

Internal Server Error

Something went wrong on our end

Error Response Format

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid email format",
    "details": {
      "field": "email",
      "issue": "Must be a valid email address"
    }
  }
}

Rate Limits

The CloudBooks API enforces rate limits to ensure system stability and fair usage across all customers. Rate limits vary based on your subscription plan.

Free

1,000

per hour

Pro

10,000

per hour

Enterprise

Custom

unlimited

Rate Limit Headers

Every API response includes headers to help you track your usage:

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9876
X-RateLimit-Reset: 1640995200

SDKs & Libraries

We provide official SDKs in popular programming languages to make integration easier. Each SDK includes type definitions, comprehensive documentation, and code examples.

📦

JavaScript / TypeScript

npm install @cloudbooks/sdk
🐍

Python

pip install cloudbooks-sdk
💎

Ruby

gem install cloudbooks
🐘

PHP

composer require cloudbooks/sdk
🔵

Go

go get github.com/cloudbooks/go-sdk
☕

Java

Maven / Gradle available