API access

PLANA Business Cloud exposes an API for programmatic access — useful for integrations, automations, custom dashboards, and migrations.

Two API surfaces

Surface	Protocol	Authentication
PLANA Workspace API	REST + JSON	Authorization: Bearer pa_live_… (workspace API key)
Direct Odoo XML-RPC	XML-RPC	Username + password (or API key) of an Odoo user

For most automation work, use the Workspace API — it's designed for external callers, has clearer error messages, and respects workspace scoping.

For Odoo-specific operations (creating records of arbitrary models, reading raw fields), the XML-RPC API is the right tool. It is what Odoo's own ecosystem (third-party Odoo addons, Odoo Studio) uses.

Workspace API

Documented at BOS → API keys and Platform → API keys.

Sample call:

curl -s "https://my.planapulse.ai/api/portal/odoo/<your-workspace>/kpis" \
  -H "Authorization: Bearer pa_live_…"

Endpoints cover:

• KPIs, cashflow, alerts
• Banking (PSD2 data)
• AI agent invocation
• Webhook registration

XML-RPC

The Odoo XML-RPC endpoint:

https://<your-workspace>.planapulse.app/xmlrpc/2/common
https://<your-workspace>.planapulse.app/xmlrpc/2/object

Standard Odoo XML-RPC. Auth flow:

import xmlrpc.client

url = 'https://acme.planapulse.app'
db  = 'acme.planapulse.app'   # same as the hostname
username = 'api-user@acme.bg'
password = 'a-secret-from-your-vault'

common = xmlrpc.client.ServerProxy(f'{url}/xmlrpc/2/common')
uid = common.authenticate(db, username, password, {})

models = xmlrpc.client.ServerProxy(f'{url}/xmlrpc/2/object')
partners = models.execute_kw(
    db, uid, password,
    'res.partner', 'search_read',
    [[['customer_rank', '>', 0]]],
    {'fields': ['name', 'email', 'phone'], 'limit': 10}
)

Standard Odoo's ORM exposed — same patterns as documented for Odoo generally.

Why JSON-RPC is blocked

Some third-party Odoo clients use JSON-RPC (/web/dataset/call_kw). This is blocked on PLANA tenants by the OCA auth_session_timeout module — JSON-RPC endpoints require an authenticated session, and external callers don't easily establish one.

Use XML-RPC instead. It's a one-line change for most clients.

Recommended pattern: API user

Don't reuse a human user's credentials for an automation. Instead:

1. Create a dedicated API User in Odoo (Settings → Users)
2. Give it only the permissions it needs
3. Generate a long random password
4. Store the password in SOPS / Vaultwarden
5. Configure the automation to use this account

Audit trail then shows clearly which actions came from automation.

Rate limits

PLANA enforces fair-use rate limits:

Limit	Value
Workspace API requests	100 req/sec burst, 30 req/sec sustained
XML-RPC execute_kw	No hard limit, but a single huge query may time out at 60s
AI agent invocation	10 req/min per workspace key

Exceeding limits returns 429 (Too Many Requests). For higher limits (bulk data imports, etc.), talk to your account manager — a short-term lift is possible.

Webhooks

For event-driven integrations, configure PLANA to send webhooks on specific events:

Settings → Technical → Webhooks → Add:

• Event (invoice posted, payment received, stock change, etc.)
• URL (your endpoint)
• Secret (for signing — verify on receipt)

Webhooks are sent asynchronously; failures are retried with exponential backoff.

For events not in the standard list, the platform-wide pulse-events bus may have what you need.

Where to read more

• BOS → API keys
• Platform → API keys
• Platform → pulse-events — for event-driven flows
• Glossary