Just spent the last three days trying to automate some basic indicator and group creation via the ThreatConnect API, and I'm starting to feel like I'm in a special kind of purgatory reserved for those who dare to move beyond the UI. The official docs have that uncanny valley feel of being *almost* complete, but missing the critical 10% that makes everything else work. It's the schema migration from hell, but without the clear-cut legacy system to blame.
Take something as fundamental as creating a Document with an associated file. The docs show you the multipart/form-data structure, but good luck figuring out the *exact* nesting of JSON within form fields for the metadata. Is it `attributes`? Is it `securityLabels` an array of objects, or just an array of names? The example snippets are fragments, not runnable code. I ended up reverse-engineering the network calls from the web UI, which feels like a defeat.
```python
# What the docs *hint* at:
files = {'file': open('report.pdf', 'rb')}
data = {'document': '{"name": "Test", "owner": "My Org"}'}
# What actually worked after hours of trial, error, and console inspection:
files = {'file': open('report.pdf', 'rb')}
data = {'document': '{"name": "Test", "fileName": "report.pdf", "owner": {"name": "My Org", "type": "Organization"}}'}
```
Notice the need for the nested `owner` object and the seemingly redundant `fileName`? That wasn't in the main API guide. Found it buried in a forum post from 2020.
And don't get me started on the pagination. The docs say it's offset/limit based, but the behaviour when you filter by tags or indicators seems inconsistent—sometimes returning empty pages before the expected data cut-off. My script now has to implement a paranoid "retry with adjusted parameters" logic that belongs in a legacy ETL job, not a modern REST API integration.
* **Inconsistent field naming** between the response when you GET a resource and the payload required to POST it.
* **Vague error codes** like "400 - Bad Request" with no supplementary message in the body about which field violated what rule.
* **"TBD" sections** in the official REST API documentation that have been sitting there for years.
I've wrangled with my share of painful APIs during CRM migrations (looking at you, legacy SAP), but this feels different. It's like the documentation assumes you're already a ThreatConnect internal developer. So, am I alone in this trench? Has anyone else built a working API client and have a post-mortem they're willing to share? Specifically around bulk operations and the more complex object types. I need to know if this is a "me" problem or a "we" problem before I commit to this migration path.
-warrior
Expect the unexpected