API Versions (v1 and v2)

ODXProxy has two API versions. They share the same x-api-key auth, the same headers, and the same JSON-RPC 2.0 response envelope; they differ in how the proxy talks to Odoo, and therefore in the request shape.

Which one to use

v1 is not deprecated: it is the only way to reach Odoo 18 and older, and it stays for as long as customers run those versions.

If you don't know an instance's version, ask the proxy once and cache the answer per URL:

curl -s -X POST http://localhost:6600/v2/odoo/version \
  -H "x-api-key: $PROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "id": "1", "url": "https://erp.example.com" }'

{ "jsonrpc": "2.0", "id": "1", "result": { "version_info": [20, 0, 0, "final", 0, "e"], "version": "20.0+e" } }

version_info[0] of 19 or more means v2 is available. Error -32006, or a major version below 19, means use v1. Don't probe before every call — the answer only changes when the instance is upgraded. Every SDK has a cached helper for this.

The same call on both

A search_read on v1:

{
  "id": "1",
  "action": "search_read",
  "model_id": "res.partner",
  "params": [[["is_company", "=", true]]],
  "keyword": { "fields": ["name", "email"], "limit": 10 },
  "odoo_instance": { "url": "https://erp.example.com", "db": "prod", "user_id": 2, "api_key": "<ODOO_USER_API_KEY>" }
}

and on v2:

{
  "id": "1",
  "model_id": "res.partner",
  "method": "search_read",
  "kwargs": {
    "domain": [["is_company", "=", true]],
    "fields": ["name", "email"],
    "limit": 10
  },
  "odoo_instance": { "url": "https://erp.example.com", "db": "prod", "api_key": "<ODOO_USER_API_KEY>" }
}

Three differences show up immediately:

• Named arguments only. v2 has no positional params and no keyword. Every argument goes in kwargs under the Odoo method's Python parameter name, so the domain is "domain" — the list itself, without v1's extra wrapping.
• Any public method. method names the Odoo method directly; there's no action allowlist and no fn_name. Odoo still refuses private (_-prefixed) methods, and every call still runs under the Odoo user's own permissions.
• No user_id. JSON-2 derives the user from the API key. A user_id sent by a v1-shaped client is ignored, so one instance object can serve both versions.

The response envelope is identical. See Actions and methods for the kwargs of every common method.

v2 in production: what to know

• Company context is explicit. Odoo applies no company selection unless the call's context carries allowed_company_ids; company_dependent fields then read as the API user's default company. Send it in kwargs.context.
• create always returns a list of ids — {"vals_list": [{...}]} → [42], even for one record. (On v1, creating from a single dict returns a bare id.)
• Arguments are checked against the method signature. An unknown or misspelled key, or ids sent to an @api.model method such as search or create, fails with error code 422. Keys are never camelCased: vals_list, not valsList.
• Errors carry Odoo's HTTP status. An Odoo-side error arrives on HTTP 200 with error.code set to 401, 403, 404, 409, 422, or 500, and error.data set to Odoo's error object. Only 409 (a lock conflict) is worth retrying. See Error codes.

Two Odoo 20 data changes apply to both versions, so they matter whichever you pick:

• Binary fields read as {"content": "<base64>", "filename": "...", "size": n} rather than a bare base64 string.
• Empty values are still false, not null, and datetimes are still UTC strings ("YYYY-MM-DD HH:MM:SS").

Migrating from v1 to v2

Most calls translate mechanically. ids and the values dict become named keys, and the domain loses one level of nesting:

For a method outside this table, look up its Python parameter names — on Odoo 19+, /doc/<model> in the web UI lists them — and send each one by name. Pass ids only when the method works on records.

Try it

• The Postman collection has a v2 folder that runs top to bottom: version, search_read, search_count, fields_get, create, read, write, both kinds of method call, and unlink (which deletes the record it created). Each request has saved example responses, including the typical errors.
• Every SDK supports both versions, with v2 as a separate session or namespace, so moving a call to v2 is mostly a constructor change.
• The full v2 endpoint schema is in the API reference.