add speculative API documentation for discussion