you're right you should mainly use org.kie.api classes in your code. The java docs is definitely outdated so would like to ask you to file jira for this so it gets updated. Use of kie.internal is actually allowed as well as this is sort of "baking time" place for api. It still might change before it gets promoted to public api but usually it is kept backward compatible. Though when using it you need to keep in mind it might change in future.