Endpoints

How to create, submit to, and retire a gopigeon endpoint. API surface is stable — llms.txt references the same commands.

Create

A single unauthenticated POST creates a live endpoint. No signup, no API key.

curl -X POST https://gopigeon.dev/new -d 'recipient=you@example.com'

Response shape

HTTP 201 with the live endpoint URL, the opaque form_id, an unclaimed flag, and a human-readable claim_note.

{
  "endpoint_url": "https://gopigeon.dev/f/f_abc123def456xyz0",
  "form_id": "f_abc123def456xyz0",
  "unclaimed": true,
  "claim_note": "Your first real form submission will arrive at the recipient email along with a one-click link to claim ownership of this endpoint."
}

Submit

POST form-encoded or JSON data to endpoint_url. Returns {"ok": true, "submission_id": "sub_..."} on success.

curl -X POST https://gopigeon.dev/f/f_abc123def456xyz0 \
  -d 'name=Jane&email=jane@somewhere.com&message=hello'

Lifecycle

• Unclaimed endpoints expire after 30 days of no submissions.
• Each unclaimed endpoint caps at 50 lifetime submissions before it freezes.
• The first real (non-spam) submission triggers a claim email; clicking it binds ownership and lifts the unclaimed caps to the owner’s plan.
• Owners can retire endpoints from the dashboard at any time.