API Reference

Access BuoyForms programmatically with our REST API.

Authentication

All API requests require an API key passed in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Create API keys in Settings > API Keys.

Base URL

https://api.buoyforms.com/v1

Rate Limits

Rate limits vary by plan and are enforced per API key:

Rate Limit Headers

Every API response includes rate limit headers:

Handling Rate Limits

When rate limited, the API returns HTTP 429 with a Retry-After header indicating seconds to wait.

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests",
  "retryAfter": 45
}

Best practices:

• Implement exponential backoff on 429 responses
• Cache responses where possible
• Batch operations when supported
• Monitor your X-RateLimit-Remaining header

Endpoints

Forms

List Forms

GET /forms

Query Parameters:

• limit (integer, default 50): Results per page
• offset (integer, default 0): Pagination offset
• status (string): Filter by draft or published

Response:

{
  "data": [
    {
      "id": "form_abc123",
      "title": "Contact Form",
      "slug": "contact",
      "status": "published",
      "createdAt": "2025-01-15T10:00:00Z",
      "updatedAt": "2025-01-20T14:30:00Z"
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 50,
    "offset": 0
  }
}

Get Form

GET /forms/:formId

Create Form

POST /forms

Body:

{
  "title": "Survey Form",
  "description": "Customer feedback survey",
  "slug": "survey"
}

Update Form

PATCH /forms/:formId

Delete Form

DELETE /forms/:formId

Submissions

List Submissions

GET /forms/:formId/submissions

Query Parameters:

• limit (integer, default 50): Results per page
• offset (integer, default 0): Pagination offset
• startDate (ISO date): Filter by submission date
• endDate (ISO date): Filter by submission date

Get Submission

GET /submissions/:submissionId

Create Submission

POST /forms/:formId/submissions

Used for programmatic form submissions. Bypasses CAPTCHA.

Body:

{
  "fields": {
    "email": "user@example.com",
    "message": "Hello!"
  },
  "metadata": {
    "source": "api"
  }
}

Delete Submission

DELETE /submissions/:submissionId

Fields

List Form Fields

GET /forms/:formId/fields

Create Field

POST /forms/:formId/fields

Update Field

PATCH /fields/:fieldId

Delete Field

DELETE /fields/:fieldId

Webhooks

List Webhooks

GET /webhooks

Create Webhook

POST /webhooks

Body:

{
  "url": "https://your-app.com/webhook",
  "events": ["submission.created"],
  "formId": "form_abc123"
}

Update Webhook

PATCH /webhooks/:webhookId

Delete Webhook

DELETE /webhooks/:webhookId

Error Responses

Errors return appropriate HTTP status codes with JSON body:

{
  "error": "validation_error",
  "message": "Invalid request body",
  "details": [
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ]
}

Webhooks Signature Verification

Verify webhook authenticity using the X-Signature header:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

SDK Support

Official SDKs coming soon:

• JavaScript/TypeScript
• Python
• Ruby
• Go

Changelog

• 2025-11-27: Added rate limiting headers and documentation
• 2025-11-20: Initial API release