Skip to main content

​
Introduction

The deployERP API is a RESTful interface that allows you to programmatically manage your Odoo infrastructure. Build custom integrations, automate deployments, and manage resources at scale.

Base URL

https://api.deployerp.com/v1

​
Quick Start

1

Get API Key

Generate an API key from your dashboard settings
2

Make First Request

Test your connection with a simple GET request
3

Explore Endpoints

Browse available endpoints and operations

​
Example Request

curl -X GET https://api.deployerp.com/v1/servers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

​
Core Concepts

​
Resources

The API provides access to these primary resources:
ResourceDescriptionBase Path
ServersVirtual machines hosting Odoo/servers
InstancesOdoo installations/instances
BackupsBackup snapshots/backups
ProvidersCloud provider connections/providers
TeamsTeam and user management/teams
InvoicesBilling and invoices/invoices

​
Request Format

All requests must include:
  • Authorization header with Bearer token
  • Content-Type header set to application/json
  • JSON body for POST/PUT/PATCH requests

​
Response Format

{
  "success": true,
  "data": {
    // Response data
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "request_id": "req_abc123"
  }
}

​
Authentication

​
API Keys

Generate and manage API keys from your dashboard:
  1. Navigate to Settings → API Keys
  2. Click “Generate New Key”
  3. Set key permissions and expiry
  4. Store the key securely
API keys are shown only once. Store them securely and never commit them to version control.

​
Using API Keys

Include your API key in the Authorization header: 
Authorization: Bearer YOUR_API_KEY

​
Key Permissions

API keys can have different permission levels:
LevelPermissions
ReadView resources only
WriteCreate and update resources
DeleteRemove resources
AdminFull access including billing

​
Rate Limiting

API requests are subject to rate limits:
PlanRequests/HourBurst Limit
Starter1,000100/minute
Professional5,000500/minute
EnterpriseUnlimitedCustom

​
Rate Limit Headers

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

​
Handling Rate Limits

When rate limited, you’ll receive: 
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests",
    "retry_after": 60
  }
}

​
Pagination

List endpoints support pagination:

​
Query Parameters

ParameterDescriptionDefaultMax
pagePage number1-
per_pageItems per page20100
sortSort fieldcreated_at-
orderSort order (asc/desc)desc-

​
Paginated Response

{
  "data": [...],
  "pagination": {
    "current_page": 1,
    "per_page": 20,
    "total_pages": 5,
    "total_items": 100,
    "has_next": true,
    "has_previous": false
  }
}

​
Filtering

Filter results using query parameters: 
# Filter servers by status
GET /v1/servers?status=running

# Filter by multiple criteria
GET /v1/instances?version=17.0&edition=enterprise

# Date range filtering
GET /v1/backups?created_after=2024-01-01&created_before=2024-01-31

​
Webhooks

Configure webhooks to receive real-time notifications:

​
Webhook Events

EventDescription
server.createdServer provisioned
server.deletedServer removed
instance.deployedInstance ready
instance.stoppedInstance stopped
backup.completedBackup finished
backup.failedBackup error

​
Webhook Payload

{
  "event": "instance.deployed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "instance_id": "inst_abc123",
    "server_id": "srv_xyz789",
    "status": "running"
  }
}

​
Error Handling

​
Error Response Format

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Invalid request parameters",
    "details": {
      "field": "name",
      "reason": "Required field missing"
    }
  }
}

​
Common Error Codes

CodeHTTP StatusDescription
unauthorized401Invalid or missing API key
forbidden403Insufficient permissions
not_found404Resource not found
validation_error422Invalid request data
rate_limit_exceeded429Too many requests
internal_error500Server error

​
Idempotency

Ensure safe retries with idempotency keys: 
curl -X POST https://api.deployerp.com/v1/servers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique-key-123" \
  -d '{"name": "production-server"}'

​
API Versioning

The API uses URL versioning:
  • Current version: v1
  • Version in URL: https://api.deployerp.com/v1/...
  • Deprecation notice: 6 months minimum

​
SDKs & Libraries

Official SDKs available:

Python SDK

pip install deployerp

Node.js SDK

npm install @deployerp/sdk

PHP SDK

composer require deployerp/sdk

Go SDK

go get github.com/deployerp/go-sdk

​
API Playground

Test API endpoints directly in your browser:

API Playground

Interactive API testing environment with live responses

​
Best Practices

Always paginate when fetching lists to avoid timeouts and reduce load.
When rate limited, wait progressively longer between retries.
Use environment variables or secret management systems.
Check response status and implement proper error handling.
Instead of polling, use webhooks for event-driven updates.

​
Support

Need help with the API?