adding pairs
better API documentation