(POST) Create collections

Create one or more collections to organize your links. Each collection requires a name.

Endpoint

POST /api/collections

Create one or more collections to organize your links. Collections are essential organizational units—every link must belong to a collection.

Each collection requires a name for identification. Optionally include a description to provide additional context about the collection's purpose or contents.

You can create multiple collections in a single request by providing an array of collection objects, making it easy to set up your organizational structure quickly.

Endpoint text

POST /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. Each object represents one collection to create.

You can create 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
`name` (body)	string	Yes	The name of the collection. Used for identification and organization. Choose descriptive names that clearly indicate the collection's purpose.
`description` (body)	string	No	Optional description providing additional context about the collection. Useful for documentation and team collaboration.

Plan Limits

The actual maximum number of collections you can create 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 POST "https://hoko.to/api/collections" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "name": "Marketing Campaigns",
      "description": "All marketing campaign links"
    }
  ]'

Request JavaScript

const response = await fetch("https://hoko.to/api/collections", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <API_KEY>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify([
    {
      name: "Marketing Campaigns",
      description: "All marketing campaign links"
    }
  ])
});
const collections = await response.json();

Response json

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Marketing Campaigns",
    "description": "All marketing campaign links",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
]

Collection Requirements

Every link must belong to a collection. Create collections before creating links, or ensure the collectionId you reference in link creation requests exists in your workspace.