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
- In Pampas, open Settings.
- Under API keys, enter a Label for what will use the key.
- Choose a Scope:
readcan only fetch;readwritecan also create and change. - 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.
export PAMPAS=https://forms.example.com/api/v1
export KEY=pfk_...
curl -s "$PAMPAS/forms" -H "Authorization: Bearer $KEY"Read forms and responses
| Call | What it returns |
|---|---|
GET /forms | Every 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}/responses | Its 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}/summary | The 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:
filterisall(the default),spamordeleted;verified=yesorverified=nokeeps responses with or without a verified email;recipient_idkeeps one invited person's responses;qsearches 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
Start the export:
bashcurl -s -X POST "$PAMPAS/forms/$FORM/exports" -H "Authorization: Bearer $KEY"The answer is
{ "id": ..., "status": "pending" }. Areadkey can do this.Ask for its status with
GET /exports/{id}untilstatusisdone(orfailed).Download the CSV from the
urlin 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.
Create the form:
bashcurl -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 fromnamewhen you leave it out; akeyalready in use is a 409.test_mode: truecreates it in test mode. You can also pass adefinition: anything Pampas does not recognise is removed and listed in the answer'sstripped. Without one, the form starts empty.Change the definition with
PUT /forms/{id}/definition, sending the wholedefinitionand therevisionyou last read (definitionRevision). If someone saved in between, the answer is 409revision_conflict: read the form again and retry. The shape of a definition is theworkingDefinitionthatGET /forms/{id}returns.Publish it with
POST /forms/{id}/publish. Publishing needs a decision on how long to keep responses: pass{"retention": {"responseDays": 365}}("responseDays": nullkeeps them indefinitely), or save one in Pampas first. Without one the answer is 422retention_required.
POST /forms/{id}/unpublish closes the form to new responses.
Invite people to fill it in
POST /forms/{id}/recipientsadds up to 1000 people at once inrecipients, each withemailand an optionalname.auth_modeis required:linkorotp(a code by email). Optionally addsingle_use,expires_atandprefill(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}/reminderssends now: it invites everyone not yet invited and reminds those who have not answered.GET /forms/{id}/recipientslists 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-RemainingandRateLimit-Resetheaders, 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 acode, such asrevision_conflict,retention_requiredordefinition_invalid. A 403 with areadkey means the call needsreadwrite.
Agents connected through the AI gateway reach the same actions as tools: see Pampas agent tools.