"The endpoint is ready, give it a try." A curl command lands in the group chat right after.

You paste it into a terminal. 401 Unauthorized. A token shows up in the thread. You try again and get a parameter error. A few more questions later, you learn that warehouseId in the request body has to come from a different endpoint, and the whole thing only works against the staging environment.

By the time the request finally succeeds, the context needed to make it work is scattered across a dozen messages. The next engineer who integrates this API gets to rediscover all of it. A runnable request is the beginning of a handoff, not the end of one. The next person needs something they can understand, reproduce, and maintain.

Accept the material people already have

API material in the wild is rarely tidy. Some teams hand over an OpenAPI file, others send a Postman collection, and many have nothing but a curl command. Powerduck imports all three, along with Git repositories and URLs, and upgrades older Swagger or OpenAPI documents to a current version in the process.

For the inventory lookup integration, import the request you were given instead of retyping it. Check the URL, headers, parameters, and auth in the Request workspace, and put the environment differences — staging host, test credentials — into an environment rather than search-and-replacing them on every run. The personal debugging base URL stays out of the contract; it lives in a local environment, while the document's declared servers stay read-only.

Turn the verbal addenda into a contract that sticks

After the request runs, there is a short list of things worth pinning down immediately:

  • Which parameters are required, and what does each one mean?
  • When no inventory is found, does the endpoint return an empty result or an error?
  • Does the quantity field mean sellable stock or physical stock?
  • What auth does a caller need, and where do they get the credentials?

The assistant can turn the answers into descriptions and spec edits against the imported document; someone who knows the business then checks them. One successful response cannot prove that every field will always be present or enumerate every error case, so the more valuable move is having the assistant mark what is missing rather than invent a confident-looking complete answer.

When the request is worth keeping, promote the scratch request into the OpenAPI document and file it in the right folder. A one-off troubleshooting session becomes project material the next person can actually use.

Verify, save, and deliver without changing tools

Debugging and spec editing live in the same workspace. Adjust a parameter, send the request again, notice a documentation gap, fix it, and save the file — the loop never leaves the application.

The saved YAML or JSON goes into the repository like any other source file. Internal developers serve it to their coding agents through the dev MCP server; external partners get hosted documentation through Cloud. One reviewed specification serves four different readers: developers reading definitions, QA reproducing requests, AI tools querying structure, and partners reading the published docs.

If you would rather hand an agent the contract than a chat history, the same workflow applies — we walked through that integration in giving the coding agent the spec instead of another curl.

A good handoff means fewer questions for the next person

The thing worth keeping is never just "I got this request to work." It is why the request is shaped this way, when it fails, and how to read the result when it succeeds.

Next time a curl command shows up in the chat, take it one step further: import it, verify it, and write the things you had to ask about back into the specification. Leave the lesson in a file instead of leaving it in the thread.