updates to API spec and diagrams