Glossary API

The Business Glossary API provides CRUD operations for business terms, product/field linking, and CSV import/export.

Base path: /spaces/{slug}/glossary

All endpoints require authentication and space membership.

---

Term CRUD

Create Term

POST /spaces/{slug}/glossary

Request Body:

Field	Type	Required	Description
name	string	✅	Term name (1–200 chars)
slug	string	✅	URL-safe identifier (pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$)
definition	string	—	Rich-text definition
category	string	—	Category grouping
status	string	—	draft (default), approved, deprecated
synonyms	string[]	—	Alternative names

Response: 201 Created — GlossaryTermResponse

{
  "id": "uuid",
  "name": "Annual Recurring Revenue",
  "slug": "annual-recurring-revenue",
  "definition": "Total annualized subscription revenue.",
  "category": "Finance",
  "status": "approved",
  "synonyms": ["ARR"],
  "created_by_id": "uuid",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z",
  "products": [],
  "fields": []
}

Errors: 409 Conflict — Slug already exists in this space.

---

List Terms

GET /spaces/{slug}/glossary

Query Parameters:

Parameter	Type	Default	Description
category	string	—	Filter by category
status	string	—	Filter by status
letter	string	—	Filter by first letter (single char)
limit	int	100	Max items (1–500)
offset	int	0	Pagination offset

Response: 200 OK

{
  "items": [
    {
      "id": "uuid",
      "name": "Annual Recurring Revenue",
      "slug": "annual-recurring-revenue",
      "category": "Finance",
      "status": "approved",
      "synonyms": ["ARR"],
      "product_count": 3,
      "field_count": 5
    }
  ],
  "total": 42
}

---

Get Term

GET /spaces/{slug}/glossary/{term_slug}

Response: 200 OK — GlossaryTermResponse (includes linked products and fields).

Errors: 404 Not Found — Term not found.

---

Update Term

PATCH /spaces/{slug}/glossary/{term_slug}

Request Body (all fields optional):

Field	Type	Description
name	string	Updated name
definition	string	Updated definition
category	string	Updated category
status	string	Updated status
synonyms	string[]	Updated synonyms

Response: 200 OK — GlossaryTermResponse

Errors: 404 Not Found — Term not found.

---

Delete Term

DELETE /spaces/{slug}/glossary/{term_slug}

Response: 204 No Content

Errors: 404 Not Found — Term not found.

---

Categories

List Categories

GET /spaces/{slug}/glossary/categories

Returns distinct category names used in the space.

Response: 200 OK

["Finance", "Marketing", "Operations"]

---

Linking

Link Product

POST /spaces/{slug}/glossary/{term_slug}/products

Request Body:

Field	Type	Required	Description
product_id	UUID	✅	Product to link

Response: 201 Created

{
  "id": "uuid",
  "term_id": "uuid",
  "linked_at": "2025-01-15T10:30:00Z"
}

Errors: 409 Conflict — Link already exists.

---

Unlink Product

DELETE /spaces/{slug}/glossary/{term_slug}/products/{product_id}

Response: 204 No Content

---

Link Field

POST /spaces/{slug}/glossary/{term_slug}/fields

Request Body:

Field	Type	Required	Description
field_id	UUID	✅	Field to link

Response: 201 Created — LinkResponse

Errors: 409 Conflict — Link already exists.

---

Unlink Field

DELETE /spaces/{slug}/glossary/{term_slug}/fields/{field_id}

Response: 204 No Content

---

Get Terms for Product

GET /spaces/{slug}/glossary/products/{product_id}/terms

Returns all glossary terms linked to a specific product.

Response: 200 OK — GlossaryTermListResponse[]

---

CSV Import/Export

Export Terms

GET /spaces/{slug}/glossary/export

Downloads all terms as a CSV file.

Response: 200 OK — CSV file (text/csv)

Columns: name, slug, definition, category, status, synonyms

---

Import Terms

POST /spaces/{slug}/glossary/import

Upserts terms from a CSV file. Matching is done by slug — existing terms are updated, new slugs create new terms.

Request: Multipart form upload (field: file) or raw CSV body with Content-Type: text/csv.

Response: 200 OK

{
  "created": 12,
  "updated": 3,
  "errors": 0
}

---

Response Models

GlossaryTermResponse

Field	Type	Description
id	UUID	Term identifier
name	string	Term name
slug	string	URL-safe identifier
definition	string | null	Rich-text definition
category	string | null	Category grouping
status	string	draft, approved, deprecated
synonyms	string[] | null	Alternative names
created_by_id	UUID | null	Creator's user ID
created_at	datetime | null	Creation timestamp
updated_at	datetime | null	Last update timestamp
products	LinkedProductBrief[]	Linked products
fields	LinkedFieldBrief[]	Linked fields

LinkedProductBrief

Field	Type	Description
id	UUID	Product ID
name	string	Product name
slug	string	Product slug

LinkedFieldBrief

Field	Type	Description
id	UUID	Field ID
name	string	Field name
data_type	string | null	Column data type
product_id	UUID | null	Parent product ID