What we do
Tools
Industries
Department
How we workLet's talk →
Home/Odoo/Odoo API Documentation by Version and Call Style
Odoo developer reference

Odoo API Documentation: Which Page Matches Your Version, and How to Read It

Open Odoo's developer docs on the 19.0 tab and the API page talks about JSON-2 and bearer keys. Switch to 17.0 and it's XML-RPC with execute_kw. Both are right for their version, which is why tutorials disagree. The model and method names are the same underneath, so once you know which page applies, the rest of the reference carries over.

The Odoo doc page to open first

Your setup Read this Watch for
Odoo 19 or later, new code External JSON-2 API, under Developer, Reference, in the 19.0 docs. On Odoo Online, external API access is only on the Custom plan, not One App Free or Standard. Self-hosted Community and Enterprise don't have that rule.
Odoo 19 or later, older code External RPC API for what the code does now, and the Migrating from XML-RPC / JSON-RPC section of the JSON-2 page for where it's going. /xmlrpc, /xmlrpc/2 and /jsonrpc are scheduled for removal in Odoo Online 21.1 (winter 2027) and Odoo 22 (fall 2028).
Odoo 17 or 18 The External API page in that version's developer reference, which documents XML-RPC. Tutorials written for 19 won't work here. JSON-2 arrived with 19.
Any version, your own fields The ORM API reference for methods and domains, then your own database for field names. Custom fields only exist in your database, so no public page lists them. See the models list in developer mode, or call fields_get.

JSON-2 next to XML-RPC and JSON-RPC

Same models, same methods, different envelope.

Odoo 19+

JSON-2

  • One POST per call to /json/2/<model>/<method>.
  • Authorization: bearer <API key> header. No separate login step.
  • Body holds ids, an optional context, and the method's own parameters by name, such as domain and fields for search_read.
  • X-Odoo-Database only when the server hosts several databases and can't tell them apart by host name.
  • Errors come back as an HTTP 4xx or 5xx with a JSON object.
Deprecated

XML-RPC and JSON-RPC

  • Log in at /xmlrpc/2/common to get a user ID, then call /xmlrpc/2/object.
  • Every call goes through execute_kw with database, user ID, password or API key, model, method, then positional and keyword arguments.
  • JSON-RPC wraps the same services in a JSON envelope at /jsonrpc.
  • Still documented, still working, and scheduled for removal.

New work belongs on JSON-2 if your version has it. Moving old code is mostly a change to how each call is addressed and authenticated, since the model and method names carry over.

Models and methods most Odoo integrations touch

Technical names, the ones the API expects. Labels in the Odoo screens can differ.

01

People and companies

  • res.partner holds customers, vendors and their contacts in one model.
  • Filter with is_company to separate companies from people.
02

Sales

  • sale.order for the order, sale.order.line for its lines.
  • Confirming an order is a method on the order, not a field you set.
03

Invoices, bills and journal entries

  • All of them are account.move.
  • move_type tells an invoice from a bill or a credit note.
04

Products and stock

  • product.template is the product, product.product each variant.
  • stock.quant holds quantities per location.
05

The methods you call on them

  • search_read and search_count to read.
  • create, write and unlink to change records.
  • fields_get to list a model's fields, custom ones included.

Reading what the Odoo API sends back

A successful JSON-2 call returns HTTP 200 and whatever the method returns, as JSON. A failure returns a 4xx or 5xx and an object with name, message, arguments, context and debug, the last being the server's traceback. The name is usually the quickest clue: an access error, a validation error from a required field, or a missing record.

The API applies the same access rights, record rules and field permissions as the Odoo screens, so an access error usually means the key's user lacks a group, not that the endpoint is wrong. Odoo's docs recommend a dedicated user for integrations rather than a person's login.

Keys have rules of their own. A key lasts at most three months. Generating keys from code through res.users.apikeys needs Settings administration rights unless an admin allows other users, and each user can generate 10 that way by default; an eleventh returns HTTP 422. On 19, Odoo's docs also point to a /doc page on your own database that lists its models, fields and methods. The docs mark that section as under construction.

n-frames writes and maintains Odoo integrations from this reference for companies already running Odoo: the connector to an outside system, the move off XML-RPC, and the monitoring that catches an expiring key before the sync stops. The Odoo API overview walks through a first JSON-2 request, and Odoo integrations covers what usually gets connected.

Questions people ask

Where is the official Odoo API documentation?

In the developer reference at odoo.com/documentation, under the version tab you run. On 19.0 it's the External JSON-2 API page, with the older calls on External RPC API. On 17.0 and 18.0 it's a page called External API. Your own fields aren't in any public page, so check your database.

Does Odoo have a REST API in the usual sense?

Not resource by resource. JSON-2 on Odoo 19 is the closest: plain JSON over HTTPS with a bearer key, but every call is a POST that names a model and a method. Older versions use XML-RPC and JSON-RPC, which can read, write and search the same models.

Can I call Odoo's API from Python?

Yes. For JSON-2 any HTTP library works, such as requests, posting JSON with the bearer header. For XML-RPC, Python's standard xmlrpc.client is what Odoo's own examples use. Other languages work the same way, since it's all HTTP.

Is Odoo's API available on the free Community edition?

Yes, when you host Community yourself the external API comes with it. The catch is Odoo Online: there, Odoo's docs say external API access needs the Custom plan, so the free One App plan and Standard don't get it. Which models you can reach depends on the apps installed.

Does the Odoo API work with custom modules?

Yes. Custom models and custom fields answer to the same methods as standard ones, by their technical names. Call fields_get on the model to see them, since the public docs can't list fields that only exist in your database.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.