---
title: "Change a collection"
method: PATCH
path: "/collections/{id}"
tags: ["Data"]
---

# Change a collection

`PATCH /collections/{id}`

## Request

- Base URL: `https://api.hypamoon.com/api/v1`
- URL: `https://api.hypamoon.com/api/v1/collections/{id}`
- 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`)

Changes the name, description, access, triggers or schema. Fields you leave out stay as they are, including inside access and triggers. A new schema applies to new and changed documents; existing documents are not checked again. A new name breaks a form that posts to the old one.

## Path parameters

- `id` string, required

## Request body

- CollectionUpdate: Change a collection. Fields you leave out stay as they are.
  - `name` string: 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, nullable: 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, nullable: 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, nullable: 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 `200`

The collection as it is now.

- 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.
- `404`: Not Found: not_found.
- `409`: Conflict: collection_name_taken.
- `422`: Unprocessable Content: validation_failed.
- `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)