API tweaks

Initial work on API and looking at indexes for query patterns.
yeah - good point, i'll amend and update.