Is there somene some documentation of the OpenDB API ? Sometime I can sort of figure it out just using auto-completion but ... sometime it's really not all that clear how it works.

The OpenDB API is documented in db.h. This provides the C++ interface, but everything there is automatically converted to Tcl (and Python, I believe?) using SWIG. So for example if you have the following in C++

dbSite site;
cout << site.getHeight();

Would be equivalent to the following Tcl

puts [$site getHeight]

after going through all the accessors to get the chip, block, tech, etc.

Thanks for the pointer ! Usueful reference for the future for the API itself. But I was looking also for a higher layer description, like ... what's the difference between TechVia and BoxVia or what's a SWire and why is it different from a normal wire, that kind of high level description of the concepts involved.

OpenDB follows the LEF/DEF conventions somewhat closely, so if you take a look at the LEF/DEF reference manual or even some OpenAccess docs, there may be better explanations