Categories

Hierarchical content categorization. Categories support nesting (parent/child), multi-language translations, and optional structured content schemas.

When a category has a custom schema defined, contents assigned to it can include customData with fields matching that schema.

8 endpoints

`GET /categories`

List categories

Returns a flat list of all categories for your site. Use GET /categories/tree for the nested hierarchy.

Parameters

Name	In	Type	Required	Description
`page`	query	number	No	Number
`limit`	query	number	No	Number <= 100
`search`	query	string	No	Full-text search query
`sortBy`	query	"created_at" \| "updated_at" \| "name" \| "slug"	No	One of: created_at, updated_at, name, slug
`sortOrder`	query	"asc" \| "desc"	No	One of: asc, desc
`dateFrom`	query	string	No	Filter from date (ISO 8601)
`dateTo`	query	string	No	Filter until date (ISO 8601)
`slug`	query	string	No	URL-friendly identifier, unique per site and locale
`slugs`	query	string[]	No	Array of strings
`ids`	query	string[]	No	Array of strings
`excludeIds`	query	string[]	No	Array of strings
`parentId`	query	string \| null	No	Parent resource ID
`isRoot`	query	boolean	No	Boolean
`includeChildren`	query	boolean	No	Boolean

Responses

Status	Description
`200`	Successful response
`401`	Unauthorized — invalid or missing API token
`403`	Forbidden — insufficient permissions

Examples

Bash

curl https://api.lynkow.com/v1/categories \
  -H "Authorization: Bearer $API_TOKEN"

Response Example

JSON

{
  "data": [
    {
      "id": 1,
      "name": "Tutorials",
      "slug": "tutorials",
      "description": "Step-by-step guides and how-tos",
      "parentId": null,
      "locale": "en",
      "contentCount": 12,
      "createdAt": "2025-01-10T09:00:00.000Z"
    },
    {
      "id": 2,
      "name": "API Guides",
      "slug": "api-guides",
      "description": "REST API integration tutorials",
      "parentId": 1,
      "locale": "en",
      "contentCount": 5,
      "createdAt": "2025-01-12T14:00:00.000Z"
    }
  ],
  "meta": {
    "total": 8,
    "perPage": 15,
    "currentPage": 1,
    "lastPage": 1
  }
}

`POST /categories`

Create a category

Creates a new category. Set parentId to create it as a child of an existing category. The slug is auto-generated from the name if not provided.

Request Body

Content-Type: application/json

Field	Type	Required	Description
`name`	string	Yes	Required. Display name. 1-255 characters
`slug`	string	Yes	Required. URL-friendly identifier, unique per site and locale. 1-255 characters
`description`	string \| null	No	Description text
`image`	string \| null	No	Image URL
`parentId`	string \| null	No	Parent resource ID
`locale`	string	No	BCP 47 locale code (e.g. "en", "fr")
`sitemapPriority`	number \| null	No	Sitemap priority (0.0-1.0)
`sitemapChangefreq`	"always" \| "hourly" \| "daily" \| "weekly" \| "monthly" \| "yearly" \| "never" \| null	No	Sitemap change frequency (daily, weekly, monthly)
`contentMode`	"standard" \| "structured"	No	One of: standard, structured
`schema`	object	No	Field schema definition
`schemaSource`	"own" \| "inherit"	No	One of: own, inherit

Responses

Status	Description
`201`	Successful response
`401`	Unauthorized — invalid or missing API token
`403`	Forbidden — insufficient permissions
`422`	Validation error

Notes: - Maximum nesting depth is not enforced, but 3 levels is recommended for UX.

Examples

Bash

curl -X POST https://api.lynkow.com/v1/categories \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Guides",
    "description": "REST API integration tutorials",
    "parentId": 1
  }'

Response Example

JSON

{
  "data": {
    "id": 5,
    "name": "API Guides",
    "slug": "api-guides",
    "description": "REST API integration tutorials",
    "parentId": 1,
    "locale": "en",
    "contentCount": 0,
    "createdAt": "2025-04-06T12:00:00.000Z",
    "updatedAt": "2025-04-06T12:00:00.000Z"
  }
}

`GET /categories/tree`

Get category tree

Returns categories as a nested tree structure, with each parent containing its children. Useful for building navigation menus and sidebar filters.

Responses

Status	Description
`200`	Successful response
`401`	Unauthorized — invalid or missing API token
`403`	Forbidden — insufficient permissions

Examples

Bash

curl https://api.lynkow.com/v1/categories/tree \
  -H "Authorization: Bearer $API_TOKEN"

Response Example

JSON

{
  "data": [
    {
      "id": 1,
      "name": "Tutorials",
      "slug": "tutorials",
      "contentCount": 12,
      "children": [
        {
          "id": 2,
          "name": "API Guides",
          "slug": "api-guides",
          "contentCount": 5,
          "children": []
        },
        {
          "id": 3,
          "name": "Frontend",
          "slug": "frontend",
          "contentCount": 7,
          "children": []
        }
      ]
    },
    {
      "id": 4,
      "name": "News",
      "slug": "news",
      "contentCount": 18,
      "children": []
    }
  ]
}

`GET /categories/:id`

Get a category

Returns a single category with its parent information and content count.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Unique identifier

Responses

Status	Description
`200`	Successful response
`401`	Unauthorized — invalid or missing API token
`403`	Forbidden — insufficient permissions
`404`	Not found

Examples

Bash

curl https://api.lynkow.com/v1/categories/1 \
  -H "Authorization: Bearer $API_TOKEN"

Response Example

JSON

{
  "id": 1,
  "name": "Tutorials",
  "slug": "tutorials",
  "description": "Step-by-step guides and how-tos",
  "parentId": null,
  "locale": "en",
  "contentCount": 12,
  "parent": null,
  "contents": {
    "data": [
      {
        "id": 42,
        "title": "Getting Started with Lynkow",
        "slug": "getting-started-with-lynkow",
        "status": "published"
      }
    ],
    "meta": {
      "total": 12,
      "perPage": 15,
      "currentPage": 1,
      "lastPage": 1
    }
  },
  "createdAt": "2025-01-10T09:00:00.000Z",
  "updatedAt": "2025-02-20T16:45:00.000Z"
}

`PUT /categories/:id`

Update a category

Updates a category's name, slug, description, parent, or schema. Moving a category to a different parent re-organizes the tree.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Unique identifier

Request Body

Content-Type: application/json

Field	Type	Required	Description
`name`	string	No	Display name. 1-255 characters
`slug`	string	No	URL-friendly identifier, unique per site and locale. 1-255 characters
`description`	string \| null	No	Description text
`image`	string \| null	No	Image URL
`parentId`	string \| null	No	Parent resource ID
`sitemapPriority`	number \| null	No	Sitemap priority (0.0-1.0)
`sitemapChangefreq`	"always" \| "hourly" \| "daily" \| "weekly" \| "monthly" \| "yearly" \| "never" \| null	No	Sitemap change frequency (daily, weekly, monthly)
`contentMode`	"standard" \| "structured"	No	One of: standard, structured
`schema`	object	No	Field schema definition
`schemaSource`	"own" \| "inherit"	No	One of: own, inherit

Responses

Status	Description
`200`	Successful response
`401`	Unauthorized — invalid or missing API token
`403`	Forbidden — insufficient permissions
`404`	Not found
`422`	Validation error

Notes: - Changing the slug does not update content URLs — only the category's own slug changes.

Examples

Bash

curl -X PUT https://api.lynkow.com/v1/categories/5 \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "REST API Guides",
    "description": "Updated description for API guides"
  }'

Response Example

JSON

{
  "data": {
    "id": 5,
    "name": "REST API Guides",
    "slug": "api-guides",
    "description": "Updated description for API guides",
    "parentId": 1,
    "locale": "en",
    "contentCount": 5,
    "createdAt": "2025-04-06T12:00:00.000Z",
    "updatedAt": "2025-04-06T16:00:00.000Z"
  }
}

`DELETE /categories/:id`

Delete a category

Deletes a category. Contents assigned to this category are NOT deleted — they simply lose this category association.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Unique identifier

Responses

Status	Description
`200`	Successful response
`401`	Unauthorized — invalid or missing API token
`403`	Forbidden — insufficient permissions
`404`	Not found

Notes: - Child categories are re-parented to the deleted category's parent (or become root-level).

Examples

Bash

curl -X DELETE https://api.lynkow.com/v1/categories/5 \
  -H "Authorization: Bearer $API_TOKEN"

Response Example

JSON

{
  "message": "Category deleted"
}

`GET /categories/:id/translations`

Get category translation status

Returns the translation status for this category across all enabled locales.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Unique identifier

Responses

Status	Description
`200`	Successful response
`401`	Unauthorized — invalid or missing API token
`403`	Forbidden — insufficient permissions
`404`	Not found

Examples

Bash

curl https://api.lynkow.com/v1/categories/1/translations \
  -H "Authorization: Bearer $API_TOKEN"

Response Example

JSON

{
  "data": {
    "en": {
      "status": "complete"
    },
    "fr": {
      "status": "missing"
    },
    "es": {
      "status": "partial"
    }
  }
}

`POST /categories/:id/copy-to-locale`

Copy category to another locale

Creates a translated copy of this category in the target locale.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Unique identifier

Request Body

Content-Type: application/json

Field	Type	Required	Description
`targetLocale`	string	Yes	Required

Responses

Status	Description
`200`	Successful response
`401`	Unauthorized — invalid or missing API token
`403`	Forbidden — insufficient permissions
`404`	Not found
`422`	Validation error

Examples

Bash

curl -X POST https://api.lynkow.com/v1/categories/1/copy-to-locale \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"locale": "fr"}'

Response Example

JSON

{
  "data": {
    "id": 50,
    "name": "Tutorials",
    "slug": "tutorials",
    "description": "Step-by-step guides and how-tos",
    "parentId": null,
    "locale": "fr",
    "createdAt": "2025-04-06T15:00:00.000Z",
    "updatedAt": "2025-04-06T15:00:00.000Z"
  }
}

GET /categories

Parameters

Responses

Examples

Response Example

POST /categories

Request Body

Responses

Examples

Response Example

GET /categories/tree

Responses

Examples

Response Example

GET /categories/:id

Parameters

Responses

Examples

Response Example

PUT /categories/:id

Parameters

Request Body

Responses

Examples

Response Example

DELETE /categories/:id

Parameters

Responses

Examples

Response Example

GET /categories/:id/translations

Parameters

Responses

Examples

Response Example

POST /categories/:id/copy-to-locale

Parameters

Request Body

Responses

Examples

Response Example

For LLMs

`GET /categories`

`POST /categories`

`GET /categories/tree`

`GET /categories/:id`

`PUT /categories/:id`

`DELETE /categories/:id`

`GET /categories/:id/translations`

`POST /categories/:id/copy-to-locale`