API Documentation

Create Account

Creates a new account with workspace and returns an API key. This endpoint is public and does not require authentication. Rate limited to 3 requests per hour per IP.

{
  "data": {
    "user_id": "a1b2c3d4-...",
    "workspace_id": "e5f6g7h8-...",
    "api_key": "bf_k1_...",
    "api_key_id": "i9j0k1l2-...",
    "api_key_prefix": "bf_k1_xxxxxxxx",
    "plan": "free",
    "email_verified": false,
    "verification_email_sent": true,
    "rate_limit": 10,
    "message": "Account created. Verify your email to unlock full API rate limits (currently 10 req/min)..."
  }
}

Check verification status

Returns whether the account's email has been verified. Requires Bearer token authentication.

{
  "data": {
    "email_verified": false
  }
}

Resend verification email

Sends a new verification email. Rate limited to 3 requests per hour. If already verified, returns success with email_verified: true.

{
  "data": {
    "email_verified": false,
    "message": "Verification email sent. Check your inbox and click the link to verify."
  }
}

List all forms

Returns all forms in your workspace.

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Customer Feedback",
      "slug": "customer-feedback",
      "status": "published",
      "response_count": 42,
      "public_url": "https://bionicforms.com/f/customer-feedback",
      "created_at": "2026-03-01T10:00:00Z",
      "updated_at": "2026-03-05T14:30:00Z"
    }
  ],
  "meta": { "total_count": 1 }
}

Create a form

Creates a new draft form. Optionally include fields to set up the form schema immediately.

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Customer Feedback",
    "description": "Quick feedback survey",
    "slug": "customer-feedback",
    "status": "draft",
    "response_count": 0,
    "public_url": "https://bionicforms.com/f/customer-feedback",
    "created_at": "2026-03-05T15:30:00Z",
    "updated_at": "2026-03-05T15:30:00Z",
    "fields": [ ... ]
  }
}

Get a form

Returns a single form with its current field schema.

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Customer Feedback",
    "status": "published",
    "fields": [
      {
        "type": "email",
        "key": "your_email",
        "label": "Your Email",
        "required": true
      },
      {
        "type": "rating",
        "key": "how_satisfied_are_you",
        "label": "How satisfied are you?",
        "required": true,
        "properties": { "max_rating": 5, "icon": "star" }
      }
    ]
  }
}

Update a form

Updates the form title and/or description. Does not affect fields.

{ "data": { "updated": true } }

Delete a form

Permanently deletes a form and all its responses.

No response body

Update form fields

Replaces the form's field schema. See Field Types for supported types.

{ "data": { "updated": true, "field_count": 3 } }

Publish a form

Creates a published version so respondents can submit. The form must have at least one field.

{
  "data": {
    "published": true,
    "public_url": "https://bionicforms.com/f/customer-feedback"
  }
}

List responses

Returns paginated form submissions. Use query parameters for pagination and search.

{
  "data": [
    {
      "id": "resp-uuid-001",
      "data": {
        "your_email": "john@example.com",
        "how_satisfied_are_you": "5",
        "comments": "Great product!"
      },
      "created_at": "2026-03-05T10:15:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total_count": 150,
    "has_more": true,
    "field_map": {
      "your_email": "Your Email",
      "how_satisfied_are_you": "How satisfied are you?",
      "comments": "Comments"
    }
  }
}

Get a response

Returns a single form submission by ID.

{
  "data": {
    "id": "resp-uuid-001",
    "data": {
      "your_email": "john@example.com",
      "how_satisfied_are_you": "5"
    },
    "created_at": "2026-03-05T10:15:00Z"
  }
}

Delete a response

Permanently deletes a single form submission.

No response body

Trigger analysis

Starts an AI analysis run on the form's responses. Requires at least 5 responses and a Standard or Pro plan.

{
  "data": {
    "run_id": "run-uuid-001",
    "status": "processing",
    "submission_count": 50,
    "created_at": "2026-03-05T10:20:00Z"
  }
}

Get analysis results

Returns the latest analysis results including sentiment, themes, urgency, and quantitative data. All data is fetched in parallel for fast responses.

{
  "data": {
    "run_id": "run-uuid-001",
    "status": "completed",
    "created_at": "2026-03-05T10:20:00Z",
    "completed_at": "2026-03-05T10:21:30Z",
    "summary": { "text": "Overall positive feedback..." },
    "sentiment": {
      "positive": 30,
      "neutral": 15,
      "negative": 5
    },
    "themes": [
      {
        "theme": "Ease of use",
        "description": "Users appreciate the intuitive interface",
        "count": 18,
        "quotes": ["Very easy to set up", "Intuitive design"]
      }
    ],
    "urgency": {
      "distribution": { "low": 20, "medium": 20, "high": 10 },
      "urgent_items": [
        {
          "response_id": "resp-uuid",
          "urgency_level": "high",
          "reason": "Customer reports data loss"
        }
      ]
    },
    "quantitative": [
      {
        "field_key": "field_2",
        "field_label": "Satisfaction",
        "field_type": "rating",
        "average": 4.2,
        "median": 5,
        "min": 1,
        "max": 5
      }
    ]
  }
}

Query with natural language

Ask a question about your form responses in plain English. Requires a prior analysis run. Costs 1 credit per query.

{
  "data": {
    "query": "What are the top 3 pain points?",
    "answer": {
      "text": "Based on the responses, the top pain points are..."
    }
  }
}

List webhooks

Returns all webhooks configured for your workspace.

{
  "data": [
    {
      "id": "wh-uuid-001",
      "url": "https://example.com/webhook",
      "secret": "whsec_...",
      "event_types": ["response.created"],
      "is_active": true,
      "description": "Production webhook",
      "form_ids": [],
      "created_at": "2026-03-01T10:00:00Z"
    }
  ],
  "meta": { "total_count": 1 }
}

Create a webhook

Registers a new webhook endpoint. Optionally filter to specific form IDs.

{
  "data": {
    "id": "wh-uuid-002",
    "url": "https://example.com/webhook",
    "secret": "whsec_...",
    "event_types": ["response.created"],
    "is_active": true,
    "description": "Production notifications",
    "form_ids": ["FORM_ID_1", "FORM_ID_2"],
    "created_at": "2026-03-05T15:00:00Z"
  }
}

Update a webhook

Updates webhook properties. Only include fields you want to change.

{ "data": { "updated": true } }

Delete a webhook

Permanently removes a webhook. It will no longer receive notifications.

No response body

Get account info

Returns your workspace details, billing plan, and remaining AI credits.

{
  "data": {
    "workspace_id": "ws-uuid-001",
    "workspace_name": "My Workspace",
    "plan": "standard",
    "credits": {
      "monthly_remaining": 100,
      "purchased_remaining": 500,
      "trial_remaining": 0,
      "period_end": "2026-04-01T00:00:00Z"
    }
  }
}