Hooksbase

Channels / April 7, 2026

Let users trigger your agent through an embedded form

Form ingest endpoint

When a human filling out a form should wake up your agent, you have two options: build a backend to receive the form, or use Hooksbase form ingest.

What you get

  • POST /v1/form/:publicId accepting application/x-www-form-urlencoded and multipart/form-data
  • CORS headers so browser-side submissions work from any origin
  • GET /v1/form/:publicId serving a minimal embeddable HTML form (zero-code option)
  • File uploads up to 15 MB per file (50 MB per ingest) on paid tiers, with signed URLs and an authenticated retrieval endpoint; free tier receives metadata only

Option A: embed the built-in form

Easiest path — point a link or iframe at the built-in form URL:

https://hooks.hooksbase.com/v1/form/YOUR_PUBLIC_ID

Users fill it in, submit, the agent fires. Zero code on your side.

Option B: build your own form

Submit directly to the ingest URL from your site:

<form
  action="https://hooks.hooksbase.com/v1/form/YOUR_PUBLIC_ID"
  method="POST"
  enctype="multipart/form-data"
>
  <input name="email" type="email" required />
  <textarea name="message"></textarea>
  <input name="attachment" type="file" />
  <button type="submit">Send to agent</button>
</form>

CORS is enabled by default, so fetch() from your frontend also works.

The payload shape

Your agent receives structured JSON:

{
  "source": "form",
  "fields": {
    "email": "user@example.com",
    "message": "..."
  },
  "files": [
    {
      "fieldName": "attachment",
      "filename": "screenshot.png",
      "contentType": "image/png",
      "size": 442120,
      "fileRef": {
        "key": "files/abc/def/0",
        "url": "https://hooks.hooksbase.com/v1/files/eyJ..."
      }
    }
  ]
}

On free tier, fileRef is omitted; files are metadata-only.

Common agent recipes

  • Support intake form: customer describes issue + uploads screenshot → agent classifies, writes Linear ticket, replies with ETA
  • Lead qualification form: visitor fills out "tell us about your use case" → agent scores lead, routes to correct sales rep
  • Custom request intake: anything where a form is the UX but an agent should process it

Security considerations

  • Form submissions are typically unauthenticated. Use CAPTCHA, rate limiting, or a honeypot field upstream if abuse is a concern.
  • Prevent double-submit in your own form UI if users can click Submit repeatedly; form ingest does not currently dedupe browser submissions by Idempotency-Key.

What next

Related guides

Back to guides