(PUT) Update/Upsert collections

Update existing collections or create new ones with upsert operations.

Endpoint

PUT /api/collections

Upsert (update or insert) one or more collections. If id is provided, the collection is updated. If the ID does not exist, the request fails. To create new collections, omit the id field.

This endpoint is useful for synchronization scenarios where you want to ensure collections exist with specific properties.

Endpoint text

PUT /api/collections

Authentication

Requires authentication with an API key that has the collectionsWrite scope.

Request Body

The request body must be an array of collection objects. Include the id field to update an existing collection, or omit it to create a new one.

You can upsert up to 10,000 collections in a single request. However, the actual maximum may be lower based on your subscription plan limits and available resources.

Parameter	Type	Required	Description
`id` (body)	string (UUID)	Yes	Required when updating. Omit to create a new collection. If provided, it must exist in your workspace or the request fails.
`name` (body)	string	No	The name of the collection. Required when creating a new collection (no id). Optional when updating.
`description` (body)	string	No	Optional description. Only changes when provided.

Update Behavior

When updating, only the fields you include are changed. Omitted fields keep their current values. To clear a value, send it explicitly as null.

Plan Limits

The actual maximum number of collections you can upsert per request may be lower than 10,000 based on your subscription plan limits and available resources. The system will enforce both the hard limit (10,000) and your plan-specific limits.

Examples

Request cURL

curl -X PUT "https://hoko.to/api/collections" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Updated Name",
      "description": "Updated description"
    }
  ]'

Request JavaScript

const response = await fetch("https://hoko.to/api/collections", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer <API_KEY>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify([
    {
      id: "550e8400-e29b-41d4-a716-446655440000",
      name: "Updated Name",
      description: "Updated description"
    }
  ])
});
const collections = await response.json();

Response json

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Updated Name",
    "description": "Updated description",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
]