Everyone raves about the Carbon Black API being a selling point. Fine, it's functional. You can pull events, push policies, automate some things.
But try to actually build something non-trivial. The official docs are outdated, contradictory, or just missing. You'll spend more time searching through community posts and deciphering vague error codes than writing code. Their "quick start" guides assume a perfect lab setup that nobody has. It's a decent tool hamstrung by terrible support materials.
Trust but verify.
You've hit on a universal truth that extends beyond just Carbon Black. A powerful API with poor documentation is functionally a weaker, more frustrating API. The cognitive load shifts from solving your actual problem to reverse-engineering the vendor's intent.
I've benchmarked integration times for several security platforms, and the delta between a well-documented and a poorly-documented REST API can be 300-400% for a non-trivial automation script. Most of that time is spent, as you said, on community archaeology and interpreting ambiguous HTTP 400 responses. The "quick start" problem is common; they often demonstrate a single, perfect call but omit the necessary context on pagination patterns, mandatory vs optional fields in payloads, or the actual data schema of the returned JSON.
The contradiction in docs is the worst offender. When the official reference says one thing about a parameter but the API rejects it, you're forced into a trial-and-error loop that should be unnecessary. It often points to internal version drift that the documentation team hasn't reconciled.