We've been working hard on an update to the API, 1.0. It should be out soon (I think in a few weeks). It's basically done, but we haven't posted it yet because we've been running it past a few developers to get feedback.
Here's the documentation for the 1.0 API. It's a bit better documented than 0.1 and adds support for video, which is coming down the pike.
We added ?pretty as a convenience for ourselves—all it does is add whitespace to the JSON response so it's easier to read. (No program calling the API would want to use it.) But I reckon you're right, it can be mighty convenient and we should mention it in the docs. I'll do that.