odoo-rpc-api

name	odoo-rpc-api
description	ALWAYS use this when the request matches Odoo RPC API: Expert on Odoo's external JSON-RPC and XML-RPC APIs.

Odoo RPC API

Selective Reading Rule

Start with:

• references/senior-master-standard.md
• references/usage-routing.md
• references/quality-checklist.md

Then load only the inherited docs, scripts, assets, or examples that match the user's actual task.

Overview

Odoo exposes a powerful external API via JSON-RPC and XML-RPC, allowing any external application to read, create, update, and delete records. This skill guides you through authenticating, calling models, and building robust integrations.

When to Use This Skill

• Connecting an external app (e.g., Django, Node.js, a mobile app) to Odoo.
• Running automated scripts to import/export data from Odoo.
• Building a middleware layer between Odoo and a third-party platform.
• Debugging API authentication or permission errors.

How It Works

1. Activate: Mention @odoo-rpc-api and describe the integration you need.
2. Generate: Get copy-paste ready RPC call code in Python, JavaScript, or curl.
3. Debug: Paste an error and get a diagnosis with a corrected call.

Examples

Example 1: Authenticate and Read Records (Python)

import xmlrpc.client

url = 'https://myodoo.example.com'
db = 'my_database'
username = 'admin'
password = 'my_api_key'  # Use API keys, not passwords, in production

# Step 1: Authenticate
common = xmlrpc.client.ServerProxy(f'{url}/xmlrpc/2/common')
uid = common.authenticate(db, username, password, {})
print(f"Authenticated as UID: {uid}")

# Step 2: Call models
models = xmlrpc.client.ServerProxy(f'{url}/xmlrpc/2/object')

# Search confirmed sale orders
orders = models.execute_kw(db, uid, password,
    'sale.order', 'search_read',
    [[['state', '=', 'sale']]],
    {'fields': ['name', 'partner_id', 'amount_total'], 'limit': 10}
)
for order in orders:
    print(order)

Example 2: Create a Record (Python)

new_partner_id = models.execute_kw(db, uid, password,
    'res.partner', 'create',
    [{'name': 'Acme Corp', 'email': '[e-mail]', 'is_company': True}]
)
print(f"Created partner ID: {new_partner_id}")

Example 3: JSON-RPC via curl

curl -X POST https://myodoo.example.com/web/dataset/call_kw \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "call",
    "id": 1,
    "params": {
      "model": "res.partner",
      "method": "search_read",
      "args": [[["is_company", "=", true]]],
      "kwargs": {"fields": ["name", "email"], "limit": 5}
    }
  }'
# Note: "id" is required by the JSON-RPC 2.0 spec to correlate responses.
# Odoo 16+ also supports the /web/dataset/call_kw endpoint but
# prefer /web/dataset/call_kw for model method calls.

Best Practices

• ✅ Do: Use API Keys (Settings → Technical → API Keys) instead of passwords — available from Odoo 14+.
• ✅ Do: Use search_read instead of search + read to reduce network round trips.
• ✅ Do: Always handle connection errors and implement retry logic with exponential backoff in production.
• ✅ Do: Store credentials in environment variables or a secrets manager (e.g., AWS Secrets Manager, .env file).
• ❌ Don't: Hardcode passwords or API keys directly in scripts — rotate them and use env vars.
• ❌ Don't: Call the API in a tight loop without batching — bulk operations reduce server load significantly.
• ❌ Don't: Use the master admin password for API integrations — create a dedicated integration user with minimum required permissions.

Limitations

• Does not cover OAuth2 or session-cookie-based authentication — the examples use API key (token) auth only.
• Rate limiting is not built into the Odoo XMLRPC layer; you must implement throttling client-side.
• The XML-RPC endpoint (/xmlrpc/2/) does not support file uploads — use the REST-based ir.attachment model via JSON-RPC for binary data.
• Odoo.sh (SaaS) may block some API calls depending on plan; verify your subscription supports external API access.