Collections API

Collections are curated groups of acronyms. Teams use collections for onboarding, department-specific glossaries, project-scoped terminology, or any thematic grouping.

List Collections

GET /api/v1/collections

Returns all public collections in your workspace, with counts of items in each.

Query Parameters

Parameter	Type	Required	Default	Description
include_unpublished	boolean	No	false	Include private collections (admin only)

Response

{
  "success": true,
  "data": [
    {
      "id": "col_abc123",
      "name": "Engineering Onboarding",
      "description": "Essential acronyms for new engineers",
      "isPublic": true,
      "isOnboarding": true,
      "itemCount": 15,
      "creator": {
        "name": "Alice Chen",
        "avatarUrl": "https://avatar.example.com/alice.jpg"
      },
      "createdAt": "2024-01-10T10:00:00Z",
      "updatedAt": "2024-01-20T14:30:00Z"
    },
    {
      "id": "col_def456",
      "name": "Sales Glossary",
      "description": "Sales and customer success terms",
      "isPublic": true,
      "isOnboarding": false,
      "itemCount": 8,
      "creator": {
        "name": "Bob Smith",
        "avatarUrl": "https://avatar.example.com/bob.jpg"
      },
      "createdAt": "2024-01-15T09:45:00Z",
      "updatedAt": "2024-01-15T09:45:00Z"
    }
  ]
}

Response Fields

Field	Type	Description
id	string	Unique collection ID (prefixed `col_`)
name	string	Display name
description	string \| null	Optional description
isPublic	boolean	Visible to all workspace members
isOnboarding	boolean	Highlighted for new user onboarding
itemCount	number	Number of acronyms in collection
creator.name	string	Name of creator
creator.avatarUrl	string \| null	Avatar URL of creator
createdAt	string	ISO 8601 creation timestamp
updatedAt	string	ISO 8601 update timestamp

Examples

List public collections:

curl https://engineering.define.wtf/api/v1/collections \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN"

List including private collections (admin only):

curl "https://engineering.define.wtf/api/v1/collections?include_unpublished=true" \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN"

Create Collection

POST /api/v1/collections

Creates a new collection with optional initial items.

Request Body

{
  "name": "Marketing Fundamentals",
  "description": "Core marketing acronyms and concepts",
  "isPublic": true,
  "isOnboarding": false,
  "items": [
    {
      "acronymId": "acr_001",
      "sortOrder": 0
    },
    {
      "acronymId": "acr_002",
      "sortOrder": 1
    }
  ]
}

Body Parameters

Field	Type	Required	Max Length	Description
name	string	Yes	200	Collection name
description	string	No	1000	Optional description
isPublic	boolean	No (default: false)	—	Visible to all members
isOnboarding	boolean	No (default: false)	—	Highlight for new users
items	array	No	—	Initial acronym items
items[].acronymId	string	—	—	Acronym ID
items[].sortOrder	number	—	—	Position in collection (0-indexed)

Response

Returns 201 Created:

{
  "success": true,
  "data": {
    "id": "col_ghi789",
    "name": "Marketing Fundamentals",
    "description": "Core marketing acronyms and concepts",
    "isPublic": true,
    "isOnboarding": false,
    "itemCount": 2,
    "creator": {
      "name": "Carol Davis",
      "avatarUrl": "https://avatar.example.com/carol.jpg"
    },
    "createdAt": "2024-01-21T18:00:00Z",
    "updatedAt": "2024-01-21T18:00:00Z"
  }
}

Permissions

collection:create required

Examples

Create simple collection:

curl -X POST https://engineering.define.wtf/api/v1/collections \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing Fundamentals",
    "description": "Core marketing acronyms and concepts",
    "isPublic": true
  }'

Create with initial items:

curl -X POST https://engineering.define.wtf/api/v1/collections \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering Onboarding",
    "description": "Must-know acronyms for new engineers",
    "isPublic": true,
    "isOnboarding": true,
    "items": [
      {"acronymId": "acr_abc123", "sortOrder": 0},
      {"acronymId": "acr_def456", "sortOrder": 1},
      {"acronymId": "acr_ghi789", "sortOrder": 2}
    ]
  }'

Update Collection

PATCH /api/v1/collections/{id}

Updates collection metadata.

Parameters

Parameter	Type	Required	Description
id	string	Yes	Collection ID (e.g., `col_abc123`)

Request Body

{
  "name": "Marketing Essentials",
  "description": "Essential marketing acronyms",
  "isPublic": true,
  "isOnboarding": false
}

Body Parameters

Field	Type	Description
name	string	New name
description	string	New description
isPublic	boolean	Update visibility
isOnboarding	boolean	Update onboarding flag

Response

Returns 200 OK:

{
  "success": true,
  "data": {
    "id": "col_ghi789",
    "name": "Marketing Essentials",
    "description": "Essential marketing acronyms",
    "isPublic": true,
    "isOnboarding": false,
    "itemCount": 2,
    "updatedAt": "2024-01-21T18:15:00Z"
  }
}

Example

curl -X PATCH https://engineering.define.wtf/api/v1/collections/col_ghi789 \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing Essentials",
    "isOnboarding": false
  }'

Delete Collection

DELETE /api/v1/collections/{id}

Deletes a collection. The acronyms themselves remain; only the collection grouping is removed.

Parameters

Parameter	Type	Required	Description
id	string	Yes	Collection ID

Response

Returns 204 No Content (no response body).

Example

curl -X DELETE https://engineering.define.wtf/api/v1/collections/col_ghi789 \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN"

Add Item to Collection

POST /api/v1/collections/{id}/items

Adds an acronym to a collection.

Parameters

Parameter	Type	Required	Description
id	string	Yes	Collection ID

Request Body

{
  "acronymId": "acr_new999",
  "sortOrder": 5
}

Body Parameters

Field	Type	Required	Description
acronymId	string	Yes	Acronym ID to add
sortOrder	number	No	Position in collection

Response

Returns 201 Created:

{
  "success": true,
  "data": {
    "id": "item_xyz123",
    "collectionId": "col_ghi789",
    "acronymId": "acr_new999",
    "sortOrder": 5,
    "createdAt": "2024-01-21T18:30:00Z"
  }
}

Example

curl -X POST https://engineering.define.wtf/api/v1/collections/col_ghi789/items \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "acronymId": "acr_new999",
    "sortOrder": 5
  }'

Remove Item from Collection

DELETE /api/v1/collections/{id}/items/{itemId}

Removes an acronym from a collection.

Parameters

Parameter	Type	Required	Description
id	string	Yes	Collection ID
itemId	string	Yes	Collection item ID

Response

Returns 204 No Content (no response body).

Example

curl -X DELETE https://engineering.define.wtf/api/v1/collections/col_ghi789/items/item_xyz123 \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN"

Reorder Collection Items

PATCH /api/v1/collections/{id}/reorder

Reorders items in a collection by providing a new sort order.

Parameters

Parameter	Type	Required	Description
id	string	Yes	Collection ID

Request Body

{
  "items": [
    {"itemId": "item_aaa111", "sortOrder": 0},
    {"itemId": "item_bbb222", "sortOrder": 1},
    {"itemId": "item_ccc333", "sortOrder": 2}
  ]
}

Body Parameters

Field	Type	Required	Description
items	array	Yes	Array of items with new sort orders
items[].itemId	string	Yes	Item ID
items[].sortOrder	number	Yes	New position (0-indexed)

Response

Returns 200 OK:

{
  "success": true,
  "data": {
    "id": "col_ghi789",
    "itemsReordered": 3,
    "updatedAt": "2024-01-21T18:45:00Z"
  }
}

Example

curl -X PATCH https://engineering.define.wtf/api/v1/collections/col_ghi789/reorder \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"itemId": "item_aaa111", "sortOrder": 0},
      {"itemId": "item_bbb222", "sortOrder": 1},
      {"itemId": "item_ccc333", "sortOrder": 2}
    ]
  }'

Onboarding Collections

Collections with isOnboarding: true are highlighted during new user onboarding. These are typically:

Core company acronyms everyone should know
Department-specific glossaries
Essential processes and frameworks

Admin-only collections (with isOnboarding: true and isPublic: false) are shown only to members of that admin group.

Example: Create Onboarding Collection

curl -X POST https://engineering.define.wtf/api/v1/collections \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Everyone Should Know",
    "description": "Core company acronyms for all new team members",
    "isPublic": true,
    "isOnboarding": true,
    "items": [
      {"acronymId": "acr_001", "sortOrder": 0},
      {"acronymId": "acr_002", "sortOrder": 1}
    ]
  }'

Error Responses

Collection not found (404):

{
  "success": false,
  "error": {
    "code": "COLLECTION_NOT_FOUND",
    "message": "Collection not found"
  }
}

Acronym not found (404):

{
  "success": false,
  "error": {
    "code": "ACRONYM_NOT_FOUND",
    "message": "Acronym not found"
  }
}

Profanity detected (400):

{
  "success": false,
  "error": {
    "code": "PROFANITY_DETECTED",
    "message": "Content contains inappropriate language",
    "details": {
      "fields": ["name"]
    }
  }
}

Insufficient permissions (403):

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to manage this collection"
  }
}

Collection Fields Reference

Field	Type	Description
id	string	Unique collection ID (prefixed `col_`)
name	string	Display name (1-200 chars)
description	string \| null	Optional description (max 1000 chars)
isPublic	boolean	Visible to all workspace members
isOnboarding	boolean	Highlighted during new user onboarding
itemCount	number	Number of acronyms in collection
creator.name	string	Creator's display name
creator.avatarUrl	string \| null	Creator's avatar URL
createdAt	string	ISO 8601 creation timestamp
updatedAt	string	ISO 8601 update timestamp

Collections

On this page