> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moonbase.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a Form
> Creates a new form with an auto-generated collection and default fields.
## OpenAPI
````yaml POST /forms
openapi: 3.1.0
info:
title: Moonbase REST API
version: v0
servers:
- url: https://api.moonbase.ai/v0
security:
- bearer: []
tags:
- name: Inboxes
description: Manage your inboxes, conversations, and messages
- name: Collections
description: Manage your collections and items
- name: Marketing
description: Manage your marketing campaigns and forms
- name: Activities
description: View activities and capture calls
- name: Library
description: Manage your meetings, files, and notes
paths:
/forms:
post:
tags:
- Marketing
summary: Create a form
description: Creates a new form with an auto-generated collection and default fields.
parameters: []
requestBody:
description: ''
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FormCreateParams'
examples:
Create a form:
summary: Create a form
value:
name: Contact Us
redirect_url: https://example.com/thanks
pages_enabled: true
responses:
'201':
description: Creation succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/Form'
examples:
Create a form:
summary: Create a form
value:
id: 1CLJt2v5pkpkAnvdgXfEcF
type: form
updated_at: '2025-02-17T16:00:00.000Z'
name: Contact Us
redirect_url: https://example.com/thanks
pages_enabled: true
business_email_required: false
pages_url: https://moonbase.page/1CLJt2v5pkpkAnvdgXfEcF
collection:
id: 1CLJt2v6592N5WQzNpjpj2
type: collection
ref: form_1cljt2v5pkpkanvdgxfecf
html_embed: >-
created_at: '2025-02-17T16:00:00.000Z'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
Default:
summary: Default
value:
type: errors
errors:
- type: error
status: '400'
title: Bad Request
detail: >-
The request could not be understood due to malformed
syntax or invalid parameters.
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
Default:
summary: Default
value:
type: errors
errors:
- type: error
status: '401'
title: Unauthorized
detail: >-
Invalid or missing API key or JWT. You should provide
your Moonbase API Key or JWT in the authorization
header, in the format: "Authorization: Bearer
MOONBASE_API_KEY"
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
Default:
summary: Default
value:
type: errors
errors:
- type: error
status: '403'
title: Forbidden
'422':
description: Validation failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
Blank name:
summary: Blank name
value:
type: errors
errors:
- type: error
status: '422'
title: Unprocessable Entity
detail: Name can't be blank
source:
pointer: /name
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
Default:
summary: Default
value:
type: errors
errors:
- type: error
status: '429'
title: Too Many Requests
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
Default:
summary: Default
value:
type: errors
errors:
- type: error
status: '500'
title: Internal Server Error
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
Default:
summary: Default
value:
type: errors
errors:
- type: error
status: '503'
title: Service Unavailable
detail: >-
The service is temporarily unavailable, please try
again later.
x-codeSamples:
- lang: JavaScript
source: |-
import Moonbase from '@moonbaseai/sdk';
const client = new Moonbase({
apiKey: process.env['MOONBASE_API_KEY'], // This is the default and can be omitted
});
const form = await client.forms.create({
name: 'Contact Us',
pages_enabled: true,
redirect_url: 'https://example.com/thanks',
});
console.log(form.id);
- lang: Python
source: |-
import os
from moonbase import Moonbase
client = Moonbase(
api_key=os.environ.get("MOONBASE_API_KEY"), # This is the default and can be omitted
)
form = client.forms.create(
name="Contact Us",
pages_enabled=True,
redirect_url="https://example.com/thanks",
)
print(form.id)
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/moonbaseai/moonbase-sdk-go\"\n\t\"github.com/moonbaseai/moonbase-sdk-go/option\"\n)\n\nfunc main() {\n\tclient := moonbase.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tform, err := client.Forms.New(context.TODO(), moonbase.FormNewParams{\n\t\tName: \"Contact Us\",\n\t\tPagesEnabled: moonbase.Bool(true),\n\t\tRedirectURL: moonbase.String(\"https://example.com/thanks\"),\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", form.ID)\n}\n"
- lang: Ruby
source: |-
require "moonbase"
moonbase = Moonbase::Client.new(api_key: "My API Key")
form = moonbase.forms.create(name: "Contact Us")
puts(form)
components:
schemas:
FormCreateParams:
title: FormCreateParams
description: Parameters for creating a `Form`.
type: object
properties:
name:
description: The name of the form, used as the title on its public page.
type: string
redirect_url:
description: >
Optional URL the user is redirected to after a successful
submission. Omit to leave submissions without a redirect. Stored as
a Liquid template; rendered at submission time with form field
values under `submission.` (keyed by the field's `key`) plus
UTM params (`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`,
`utm_content`) automatically appended. Use the `uri_encode` filter
for URL-safe values, e.g. `https://example.com/thanks?email={{
submission.email | uri_encode }}`. The rendered URL must parse as a
valid URL or the submission errors.
type: string
pages_enabled:
description: >-
If `true`, enables a Moonbase Pages hosted page for this form,
providing a standalone public URL for sharing. Defaults to `false`.
type: boolean
business_email_required:
description: >-
If `true`, submissions require a business email address. Defaults to
`false`.
type: boolean
required:
- name
Form:
title: Form
description: >-
A Form provides a way to create `Items` in a `Collection`, often via a
public URL for external users. Each form submission creates a new item.
type: object
properties:
type:
description: >-
String representing the object’s type. Always `form` for this
object.
type: string
const: form
id:
description: Unique identifier for the object.
type: string
name:
description: The name of the form, used as the title on its public page.
type: string
redirect_url:
description: >
Optional URL the user is redirected to after a successful
submission. When unset, no redirect occurs. Stored as a Liquid
template; rendered at submission time with form field values under
`submission.` (keyed by the field's `key`) plus UTM params
(`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`,
`utm_content`) automatically appended. Use the `uri_encode` filter
for URL-safe values, e.g. `https://example.com/thanks?email={{
submission.email | uri_encode }}`. The rendered URL must parse as a
valid URL or the submission errors.
type: string
pages_enabled:
description: >-
If `true`, a Moonbase Pages hosted page is enabled for this form,
providing a standalone public URL for sharing.
type: boolean
business_email_required:
description: >-
`true` if submissions require a business email address, blocking
free and disposable providers.
type: boolean
pages_url:
description: The public URL for the form, if `pages_enabled` is `true`.
type: string
format: uri
collection:
$ref: '#/components/schemas/CollectionPointer'
description: The `Collection` that submissions to this form are saved to.
html_embed:
description: The HTML snippet for embedding the form on your website.
type: string
created_at:
description: >-
Time at which the object was created, as an ISO 8601 timestamp in
UTC.
type: string
format: date-time
updated_at:
description: >-
Time at which the object was last updated, as an ISO 8601 timestamp
in UTC.
type: string
format: date-time
required:
- collection
- name
- type
- id
- pages_enabled
- business_email_required
- html_embed
- created_at
- updated_at
Errors:
title: Errors
description: >-
The Errors object is a container that holds multiple Error objects when
an API request encounters several validation or processing issues. This
allows the API to return comprehensive feedback about all problems
encountered in a single response.
type: object
properties:
type:
type: string
const: errors
errors:
description: A list of `Error` objects.
type: array
items:
$ref: '#/components/schemas/Error'
required:
- type
CollectionPointer:
title: CollectionPointer
description: >-
A lightweight reference to a `Collection`, containing the minimal
information needed to identify it.
type: object
properties:
type:
description: >-
String representing the object’s type. Always `collection` for this
object.
type: string
const: collection
id:
description: Unique identifier of the collection.
type: string
ref:
description: The stable, machine-readable reference identifier of the collection.
type: string
required:
- type
- id
- ref
Error:
title: Error
description: >-
The Error object represents a single error that occurred during API
request processing. It provides detailed information about what went
wrong, including a unique identifier, status code, and human-readable
descriptions to help developers understand and resolve the issue.
type: object
properties:
type:
type: string
const: error
id:
description: A unique identifier for this specific error instance.
type: string
status:
description: The HTTP status code for this problem, as a string.
type: string
code:
description: An application-specific error code string.
type: string
title:
description: A short, human-readable summary of the problem.
type: string
detail:
description: A human-readable explanation of this specific error.
type: string
source:
$ref: '#/components/schemas/ErrorSource'
description: >-
An object containing more specific information about the part of the
request that caused the error.
meta:
type: object
additionalProperties: true
required:
- type
ErrorSource:
title: ErrorSource
description: >-
The ErrorSource object provides additional context about the specific
part of an API request that caused an error. It can point to either a
field in the request document or a query parameter that contains invalid
data.
type: object
properties:
pointer:
description: >-
A JSON Pointer [RFC6901] to the associated entity in the request
document.
type: string
parameter:
description: A string indicating which URI query parameter caused the error.
type: string
required: []
securitySchemes:
bearer:
type: http
scheme: bearer
description: Your Moonbase API key.
````