GET-Action Pattern

GET-Action is an bounded writable fallback for clients that can build only simple URLs. It is separate from Minimal Access and it is not a replacement for POST JSON APIs.

Route pattern#

GET /api/{version}/{resource}/{action}?param1=value&idempotency_key=stable-key

Required companion#

Every GET-Action endpoint that can change state should have a matching POST endpoint for L2 and higher clients. The POST path owns richer request bodies, structured errors, authentication flows, and ordinary API behavior.

Required controls#

• Idempotency: every write-capable GET-Action requires a stable idempotency_key.
• Consent: the action must be public-safe or explicitly human-approved before execution.
• Auditability: store the normalized action, caller class, result, timestamp, idempotency key, and public-safe evidence.
• Rate limits: enforce crawler-safe and abuse-resistant limits before action execution.
• Robots and crawlers: keep actions out of sitemaps and deny crawler-triggered execution where possible.
• Live GET fallback: if the action URL requires live dynamic HTTP GET, provide a no-op or review URL for indexed-only fetchers.
• No secrets in query strings: never place tokens, passwords, API keys, patient IDs, private messages, or payment data in the URL.

Response shape#

{
  "status": "accepted",
  "action_executed": false,
  "resource_id": "public-record-id",
  "machine_data": {},
  "human_readable_url": "https://example.org/review/action/",
  "next_actions": ["human_review_required"]
}

Allowed use#

• Simple public-safe preference, acknowledgement, review-request, or queue-intake actions when POST is unavailable to the client.
• Actions that can be repeated safely with the same idempotency key.
• Actions that expose no secret, regulated, financial, medical, or private identifier in the URL.

Forbidden use#

• Payments, account changes, destructive actions, publication, irreversible writes, medical actions, or regulated operations without a stronger authenticated POST path and explicit review.
• Any endpoint that depends on a query-string secret.
• Any broad claim that writable actions should generally be exposed as GET endpoints.

Related records#

• GET-Action SecurityDetailed security checklist and no-secret rules.
• Agent Consent BoundariesHuman approval rules for action-capable agents.
• Advanced Agent SupportPOST-first and evidence-bearing behavior for L2+ clients.