Quickstart
Create a working endpoint in a single curl. This is the same flow the llms.txt file serves to agents.
Create an endpoint
curl -X POST https://api.gopigeon.dev/new -d '[email protected]'
The response is JSON with endpoint_url, form_id, unclaimed: true, and a claim_note. Use endpoint_url directly as the action of an HTML form or the target of a fetch() call — do not rewrite the form_id.
Verify before you submit (optional but recommended)
Two zero-side-effect routes let you confirm an endpoint is wired correctly before you spend the one-shot claim event on a verification submission:
- Claim-status probe —
GET /f/${FORM_ID}/statusreturns{exists, claimed, active}(no PII, no submission counts). Use it to confirmcreate_endpointsucceeded and the endpoint is ready.
curl "https://api.gopigeon.dev/f/${FORM_ID}/status"
# → {"exists": true, "claimed": false, "active": true}- Dry-run submission — append
?dry_run=1to the form URL. Runs the full guard cascade and returns a routing preview without sending anything. No submission, no claim email, no quota counter increment.
curl -X POST "https://api.gopigeon.dev/f/${FORM_ID}?dry_run=1" \
-H "Content-Type: application/json" -d '{"hello":"world"}'
# → 200 {"dry_run": true, "would_route_to": [...], "claim_status": {...}, ...}Both routes are free for all tiers and never count toward your monthly quota. See /docs/curl for the full response shape and the queue-publish variant. Dry-run is a routing preview only — sends nothing. It is NOT sandbox mode.
Agent path: create_endpoint → probe /status → dry-run a sample payload → send the real submission. The one-shot claim email fires only on the first real submission, so verification with probe + dry-run keeps the claim event reserved for when traffic actually starts arriving.
Submit to the endpoint
curl -X POST https://api.gopigeon.dev/f/f_abc123def456xyz0 \ -d 'name=Jane&[email protected]&message=hello'
Accepts application/x-www-form-urlencoded or application/json. Returns {"ok": true, "submission_id": "sub_..."} on success, or an HTTP 303 redirect to the form’s redirect_url if configured.
After your first submission: check the inbox you set as recipient. Gopigeon sends a one-click claim link on the first real submission — clicking it binds this endpoint to a Gopigeon account so you can set a thank-you redirect, lock down allowed origins, see history, and upgrade to Pro. More on the claim flow.
Configure a thank-you redirect (redirect_url)
By default the submitter sees raw JSON. To send them to a thank-you page instead, claim the endpoint (above), then set redirect_url in the dashboard — the endpoint detail page has a redirect_url field. Once set, every successful submission responds with HTTP 303 to that URL. No code change to your form.
Managing your endpoint
Once claimed, manage your endpoint with the gopigeon MCP tools: update_endpoint updates name, redirect URL, allowed origins, or pauses the endpoint; add_destination, list_destinations, and remove_destination control fan-out targets (email, webhook, Slack). All four tools require GOPIGEON_API_KEY. See curl & MCP for the full owned-mode walkthrough and destination type reference.