---
title: "Create a collection"
method: POST
path: "/collections"
tags: ["Data"]
---

# Create a collection

`POST /collections`

## Request

- Base URL: `https://api.hypamoon.com/api/v1`
- URL: `https://api.hypamoon.com/api/v1/collections`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://app.hypamoon.com/oauth/authorize`, token URL `https://api.hypamoon.com/oauth/token`, scopes: `data:write`)

A collection holds JSON documents: the entries of a contact form, sign-ups, reservations, or facts for the assistant. Free, including in test mode. access decides who may use it besides your API key: private (all false, the default); public_write for a form on your website (with the public token, a bot check and limits); public_read to show the newest documents on a page; assistant_read to give the assistant the newest documents added through the API. triggers: email_on_insert emails every new document to the project's billing email address (live only, at most 50 emails per collection per day; beyond that, the document is still stored and the webhook is still sent), webhook_on_insert sends document.created. schema is an optional JSON Schema that every document must match. At most 20 collections per project on Free, 50 on Online, 100 on Reachable, 200 on Business.

## Request body

- CollectionInput: A new collection.
  - `name` string, required: The name of the collection, unique in the project: 2 to 40 characters, a lowercase letter first, then lowercase letters, digits and underscores (contact, signups, menu). A form posts to it by this name.
  - `description` string: What the collection is for, for your own overview.
  - `access` object: Who may use the collection besides your API key. Leave it out for private: all false.
    - `public_write` boolean: Anyone with the project's public token may add documents from an allowed origin, after a bot check and within limits: a form on a website. Default false.
    - `public_read` boolean: Anyone with the project's public token may read the newest documents (data and created_at only) from an allowed origin. Default false.
    - `assistant_read` boolean: The assistant gets the newest documents (added through the API, never those from a form) in its chat instructions, 8 kB at most. Default false.
  - `triggers` object: What happens when a document is added, through the API or a form.
    - `email_on_insert` boolean: Email every new document to the project's billing email address (live projects only, not in test mode). Default false.
    - `webhook_on_insert` boolean: Send the webhook document.created for every new document, to endpoints subscribed to it. Default false.
  - `email_routing` object: Where the email of email_on_insert goes, instead of the billing email address: at most 5 different addresses in to and rules together. An address must be confirmed before it gets anything: the billing email, the email of a project member and an address on a domain connected to the project are confirmed right away; any other address gets one email with a link to confirm (live projects only). When none of the chosen addresses is confirmed, the email goes to the billing email address. Reply-To stays the email field of the entry.
    - `to` string[]: Where the email goes when no rule matches. Empty or left out: the billing email address.
    - `rules` object[]: Up to 10 rules on a field of the new document; the first that matches decides where the email goes.
      - `field` string, required: A top-level field of the document, like vacancy or subject.
      - `equals` union, required: The value that field must have. Text matches without regard to case or surrounding spaces; for a list (checkboxes) one of its values must match.
        - string
        - number
        - boolean
      - `to` string[], required: Where the email goes when this rule matches.
  - `schema` object: Optional JSON Schema (a subset of draft 2020-12, at most 16 kB) that every document must match, with type "object" at the root. Supported: type, properties, required, additionalProperties, items, minItems, maxItems, enum, const, minLength, maxLength, pattern, format (email, uri, date, date-time, time), minimum, maximum, exclusiveMinimum, exclusiveMaximum, title and description.

## Response `201`

The new collection.

- Collection: A collection of JSON documents: the data layer of a project.
  - `id` string, uuid, required: The id of the collection. Its name works in the path as well.
  - `name` string, required: The name, unique in the project. A form posts to it by this name.
  - `description` string, nullable, required: What the collection is for, or null.
  - `access` object, required: Who may use the collection besides your API key. All false is private.
    - `public_write` boolean, required: A form on an allowed origin may add documents, with the public token, a bot check and limits.
    - `public_read` boolean, required: A page on an allowed origin may read the newest documents (data and created_at) with the public token.
    - `assistant_read` boolean, required: The assistant gets the newest documents added through the API in its chat instructions.
  - `triggers` object, required
    - `email_on_insert` boolean, required: Every new document is emailed to the project's billing email address (live only).
    - `webhook_on_insert` boolean, required: Every new document sends the webhook document.created.
  - `email_routing` object, nullable, required: Where the email of email_on_insert goes. null: the billing email address.
    - `to` string[], required: Where the email goes when no rule matches. Empty: the billing email address.
    - `rules` object[], required: The first rule that matches decides where the email goes.
      - `field` string, required: A top-level field of the new document.
      - `equals` union, required: The value that field must have.
        - string
        - number
        - boolean
      - `to` string[], required: Where the email goes when this rule matches.
    - `recipients` object[], required: Every address in to and rules, with whether it may receive email.
      - `email` string, required: The address, in lowercase.
      - `status` 'confirmed' | 'pending', required: pending: it gets nothing until someone clicks the link in the confirmation email.
      - `confirmed_by` 'billing_email' | 'member' | 'domain' | 'link' | 'null', nullable, required: Why it is confirmed: the billing email, a project member, a domain connected to the project, or the link. null while pending.
      - `confirmation_sent_at` string, nullable, required: When the last confirmation email was sent (ISO 8601), or null.
  - `schema` object, nullable, required: The JSON Schema every document must match, or null.
  - `personal_data` boolean: true for a collection with personal data imported from WordPress (form entries, orders, customers, users, reviews). It always stays private.
  - `document_count` integer, required: How many documents the collection has now.
  - `created_at` string, date-time, required: When the collection was created.
  - `updated_at` string, date-time, required: When the collection last changed.
  - `test` boolean, required: true for a collection of a test project.

## Other responses

- `400`: Bad Request: invalid_json.
- `401`: Unauthorized: unauthorized, missing_api_key, invalid_api_key, api_key_revoked, project_deleted.
- `403`: Forbidden: project_not_enabled, key_mode_mismatch, missing_scope, verification_required.
- `409`: Conflict: collection_name_taken.
- `422`: Unprocessable Content: validation_failed, collection_limit_reached.
- `429`: Too Many Requests: rate_limited.
- `500`: Internal Server Error: internal_error.
- `503`: Service Unavailable: service_unavailable.

---

[API](https://skmtc.dev/hypamoon/apis/hypamoon-api.md) · [All operations](https://skmtc.dev/hypamoon/apis/hypamoon-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hypamoon/apis/hypamoon-api/revisions/9f0b90004c06?raw)