Unclear parameter definition in the API

Hey team,

Looking at docs.release section of the API reference, it’s a bit hard to figure out the meaning of specific required parameters.
Is there a chance you could please clarify in the spec what id and buildId are and where to get them from?

I’m asking because I used to use this endpoint to trigger a build and at some point, it stopped working.

Yes, I agree it’s confusing. We’ll update the spec to add clarity, but in general:

  • the id query parameter is for the “doc ID”, where a “doc” is basically a domain that you want to publish to. The two query parameters are optional, but, if you don’t know your doc ID off-hand, you can always just use the domain you’re publishing under (ie, example.docs.stoplight.io).

  • The buildId request parameter is actually optional (it is marked required in the spec), so you don’t actually need it in the request.

We have some documentation on how to integrate the publishing process into your build/CI pipeline here, which covers how to interact with this endpoint. I hope that’s helpful.