DEV Community

LaunchSignal
LaunchSignal

Posted on

Let the agent ask before it writes: dry runs for submit APIs

Most of my notes on agent-facing APIs have been about what happens after a submit: the status codes, the pending state, the retry rules. Lately I've been rewriting the machine-readable docs for a small listing site I work on, and I keep coming back to the step before the first write. An agent that's about to submit something on a person's behalf has one chance to do it cleanly. Everything it can learn before that request saves a mess afterwards.

So this note covers what I now think a submit endpoint should tell an agent up front, and where the idea comes from. None of it is new. Infrastructure APIs have done it for years.

Borrowing "validate only" from infrastructure APIs

Kubernetes has a stable dry-run mode for the HTTP verbs that change things. Its docs say dry run "helps to evaluate a request through the typical request stages (admission chain, validation, merge conflicts) up until persisting objects to storage," that "The response body for the request is as close as possible to a non-dry-run response," and that "Kubernetes guarantees that dry-run requests will not be persisted in storage or have any other side effects." You trigger it with a dryRun query parameter.

Google's API design guidance says the same thing in general terms. AIP-163 starts from "Occasionally, a user wants to validate an intended change to see what the result will be before actually making the change," and says APIs "may provide an option to validate, but not actually execute, a request, and provide the same response (status code, headers, and response body) that it would have provided if the request was actually executed." The suggested field is validate_only.

The part I care about is "the same response." A dry run that returns a different shape from the real thing is one more contract for the agent to learn. A dry run that returns exactly what the real submit would return lets the agent use the same branching logic it already has, just without the side effect.

What I put in front of the submit endpoint

On the site I work on, the docs now say these things before an agent ever has to send a real request:

There's a dry run, and it runs every check. You add a flag to the same endpoint and the same body. It runs validation, the content policy check, the duplicate check and the "previously rejected" check, and reads the rate limit without counting against it. It creates nothing and sends no email. If everything passes, it says the submit would be accepted. If not, it returns the exact error a real submit would. I made it public and unauthenticated on purpose. A real submit already gives the same answer, so the dry run reveals nothing new. It just stops the agent from finding out by writing.

Which refusals are permanent. This is the one I underrated. RFC 9110 describes 409 Conflict as a code "used in situations where the user might be able to resolve the conflict and resubmit the request." That's a reasonable default reading, and it's the wrong lesson for an agent when the conflict is "a person already reviewed this domain and said no." So the docs name that case separately, say resubmissions aren't accepted, explain which hosts it covers, and end with the instruction an agent actually needs: don't retry, tell your human. Rate limits are the opposite case. RFC 6585 says a 429 response "SHOULD include details explaining the condition," so the docs spell out what the limit is scoped to and that waiting for review is the fix, not retrying.

The order the checks run in. Validation first, then policy, then duplicates, then previous rejections, then the rate limit. It's one line. It tells the agent that a validation error says nothing yet about whether the domain would be accepted, so fixing a typo and getting a 409 next isn't a contradiction.

What "accepted" can still mean. A submit can be accepted and still be held for a closer manual look, for example when several submissions arrive close together. The dry run says whether that would happen. The docs say plainly that it isn't a rejection and isn't a reason to resubmit.

Where it's written matters

Writing it down was only half the job. The other half was putting it where an agent looks first. The llms.txt proposal describes the problem well: "Agents are best served by concise, expert-level information gathered in a single, accessible location." For a submit endpoint, that means the dry-run flag, the permanent refusals and the check order sit in plain text right next to the endpoint description, not three clicks into a docs site. The OpenAPI description carries the same rules, because an agent that reads both shouldn't find two versions of them.

Idempotency is the other half

Dry runs answer "would this work?" They don't answer "did my last request go through?" after a timeout. Stripe's idempotent requests are the usual reference for that: "use an idempotency key. Then, if a connection error occurs, you can safely repeat the request without risk of creating a second object." The listing API I work on doesn't document an idempotency key. Instead, a second submit for the same host returns a duplicate error, and the docs tell the agent to keep the identifier from the first response rather than resubmitting. That covers the double-submit case for a one-listing-per-host site. It's a narrower guarantee than a key, and I'd rather say so than imply more.

What I'd check on any site before letting an agent submit

  • Is there a validate-only or dry-run option, and does it return the same response as the real thing?
  • Do the docs say which errors are permanent and which can be fixed?
  • Is a rate limit explained, or does the agent just get a bare 429?
  • Is "accepted" separated from "live," and from "accepted but held"?
  • Is any of this in a plain-text file an agent will actually fetch?

Most submit forms I've used don't answer these, and a person filling one in doesn't need them to. An agent does, because it can't see a red outline or read a moderator's tone. It only has what the docs said before it pressed the button.

I drafted this with help from an AI assistant and checked every quote against the linked pages on November 22, 2026.

Top comments (0)