Skip to content
Markdown
GuideForDeveloperWith or without Foxden Admin

Use the Pampas API ​

This page lets you work with Pampas forms from your own code: list and create forms, publish them, read their responses, export them as CSV and invite people to fill them in. For what Pampas is, see Pampas.

The API lives on Pampas's own address under /api/v1, for example https://forms.example.com/api/v1. Two descriptions come with it, both behind a key:

  • GET /api/v1/openapi.json: the OpenAPI 3.1 document.
  • /api/docs: a page that lists every endpoint and which key scope it needs. Someone signed in to Pampas can open it in the browser without a key.

Before you start ​

  • Someone who can manage Pampas creates the key, in Pampas's Settings, under Server.

Create a key ​

  1. In Pampas, open Settings.
  2. Under API keys, enter a Label for what will use the key.
  3. Choose a Scope: read can only fetch; readwrite can also create and change.
  4. Select Create key. The key starts with pfk_ and is shown once: copy it now.

A key acts as the person who made it. It stops working (401) when that person is removed or loses access to Pampas, and at once when the key is revoked.

bash
export PAMPAS=https://forms.example.com/api/v1
export KEY=pfk_...
curl -s "$PAMPAS/forms" -H "Authorization: Bearer $KEY"

Read forms and responses ​

CallWhat it returns
GET /formsEvery form, newest first: id, key, name, status (draft, published, closed), testMode, publishedVersion.
GET /forms/{id}One form with its workingDefinition and definitionRevision.
GET /forms/{id}/responsesIts responses, newest first: id, status, submittedAt, testMode, suspectedSpam, verifiedEmail, recipientEmail.
GET /forms/{id}/responses/{rid}One response with its answers (fieldKey, label, text, and signed download links for uploaded files).
GET /forms/{id}/summaryThe same numbers as the form's summary in Pampas.

The forms, responses and deliveries lists come 25 to a page (limit up to 100); pass nextCursor back as cursor for the next page.

On GET /forms/{id}/responses:

  • filter is all (the default), spam or deleted;
  • verified=yes or verified=no keeps responses with or without a verified email;
  • recipient_id keeps one invited person's responses;
  • q searches the answer text (2 to 200 characters, up to 50 results, no paging).

The responses list includes test responses. The summary leaves them out of a live form, and a CSV export always leaves them out.

Export responses as CSV ​

  1. Start the export:

    bash
    curl -s -X POST "$PAMPAS/forms/$FORM/exports" -H "Authorization: Bearer $KEY"

    The answer is { "id": ..., "status": "pending" }. A read key can do this.

  2. Ask for its status with GET /exports/{id} until status is done (or failed).

  3. Download the CSV from the url in that answer. The URL is signed and needs no key; it expires with the file, seven days after the export finishes (expiresAt).

The CSV leaves out test responses and includes suspected spam.

Create and publish a form ​

These calls need a readwrite key.

  1. Create the form:

    bash
    curl -s "$PAMPAS/forms" -H "Authorization: Bearer $KEY" \
      -H "content-type: application/json" \
      -d '{"name":"Event sign-up"}'

    key (the form's address name: lower-case letters, digits and _, starting with a letter) comes from name when you leave it out; a key already in use is a 409. test_mode: true creates it in test mode. You can also pass a definition: anything Pampas does not recognise is removed and listed in the answer's stripped. Without one, the form starts empty.

  2. Change the definition with PUT /forms/{id}/definition, sending the whole definition and the revision you last read (definitionRevision). If someone saved in between, the answer is 409 revision_conflict: read the form again and retry. The shape of a definition is the workingDefinition that GET /forms/{id} returns.

  3. Publish it with POST /forms/{id}/publish. Publishing needs a decision on how long to keep responses: pass {"retention": {"responseDays": 365}} ("responseDays": null keeps them indefinitely), or save one in Pampas first. Without one the answer is 422 retention_required.

POST /forms/{id}/unpublish closes the form to new responses.

Invite people to fill it in ​

  • POST /forms/{id}/recipients adds up to 1000 people at once in recipients, each with email and an optional name. auth_mode is required: link or otp (a code by email). Optionally add single_use, expires_at and prefill (answers filled in in advance, by field key). Bad addresses and people already on the form are counted, not refused. Adding people sends nothing yet.
  • POST /forms/{id}/reminders sends now: it invites everyone not yet invited and reminds those who have not answered.
  • GET /forms/{id}/recipients lists them.

Invitations go by email, so email must be set up on the server. See email on the server.

Destinations ​

Destinations (where each response is sent, such as a webhook) are set up in Pampas. The API can list them (GET /forms/{id}/destinations, with addresses shortened and no secrets), turn one on or off or change a Fennec destination's field mapping (PATCH /forms/{id}/destinations/{did} with enabled or mapping only), and read the delivery log (GET /forms/{id}/deliveries).

Limits and errors ​

  • Each key may make 120 calls a minute. Deleting a response and closing a form share a stricter limit of 20 an hour. Every answer to a valid key carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers, and a 429 says how long to wait.
  • A body that carries a form definition may be up to 2 MB.
  • Errors are application/problem+json (RFC 9457). Problems a program can act on carry a code, such as revision_conflict, retention_required or definition_invalid. A 403 with a read key means the call needs readwrite.

Agents connected through the AI gateway reach the same actions as tools: see Pampas agent tools.

Foxden is open source under Apache-2.0.