Machines API OAS

Having an OAS makes it so much easier to communicate changes and even iterate with API design ideas before releasing them. If you publish the OAS via git, it would also be easy to trace changes.
Postman collection would also be useful.
The docs you have are ok but don’t replace an API specification.

What does the fly team think about this?

At the moment, we’re working on better human readable API docs, then we may tackle machine readable API docs. Automating doc generation is currently a pain, but it’ll help us keep user facing docs good so it makes sense for us to get there.