NextDocsNextDocs

Brands

Brand kit management — themes, assets, and AI instructions.

List brands

Returns a paginated list of brand kits in the authenticated user's personal scope.

GET
/v1/brands

Authorization

AuthorizationRequiredBearer <token>

NextDocs API key (nxd_xxx format)

In: header

Query Parameters

limitinteger

Number of items to return (1-20).

Default: 20Minimum: 1Maximum: 20
afterstring

Cursor for pagination. Pass the ID of the last item from the previous page.

Response Body

A paginated list of brands.

TypeScript Definitions

Use the response body type in TypeScript.

objectRequiredstring
Value in: "list"
dataRequiredarray<object>
has_moreRequiredboolean

Whether there are more items after this page.

Authentication required or API key is invalid.

TypeScript Definitions

Use the response body type in TypeScript.

errorRequiredobject
curl -X GET "https://api.nextdocs.io/v1/brands?limit=20&after=clxyz123..." \
  -H "Authorization: Bearer <token>"
fetch("https://api.nextdocs.io/v1/brands?limit=20&after=clxyz123...", {
  headers: {
    "Authorization": "Bearer <token>"
  }
})
package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {
  url := "https://api.nextdocs.io/v1/brands?limit=20&after=clxyz123..."

  req, _ := http.NewRequest("GET", url, nil)
  req.Header.Add("Authorization", "Bearer <token>")
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}
import requests

url = "https://api.nextdocs.io/v1/brands?limit=20&after=clxyz123..."

response = requests.request("GET", url, headers = {
  "Authorization": "Bearer <token>"
})

print(response.text)
{
  "object": "list",
  "data": [
    {
      "object": "brand",
      "id": "brand_abc123",
      "name": "Acme Corp",
      "ai_instruction": "Use formal tone and blue color scheme.",
      "theme_id": "theme_xyz789",
      "theme": {
        "object": "theme",
        "id": "abc123",
        "name": "Midnight Blue",
        "is_custom": true,
        "font_primary": "Playfair Display",
        "font_secondary": "Inter",
        "colors": {
          "background": "#FFFFFF",
          "foreground": "#1F1F1F",
          "muted": "#F5F5F5",
          "card": "#FAFAFA",
          "text_on_muted": "#6B7280",
          "text_on_card": "#374151",
          "primary": "#3B82F6",
          "secondary": "#8B5CF6",
          "tertiary": "#EC4899",
          "text_on_primary": "#FFFFFF",
          "text_on_secondary": "#FFFFFF",
          "text_on_tertiary": "#FFFFFF",
          "border": "#E5E7EB"
        },
        "created_at": "2026-01-15T10:30:00.000Z",
        "updated_at": "2026-04-01T08:00:00.000Z"
      },
      "assets": [
        {
          "object": "asset",
          "id": "asset_abc123",
          "name": "LiveHaus Logo",
          "type": "icon",
          "url": "https://cdn.nextdocs.com/users/user_123/assets/logo.png",
          "slug": "livehaus-logo",
          "format": "png",
          "usage_mode": "always",
          "category": "logo",
          "tags": [
            "logo",
            "brand",
            "mark"
          ],
          "brand_id": "brand_abc123",
          "size": 2048,
          "width": 512,
          "height": 512,
          "created_at": "2026-04-06T10:30:00.000Z",
          "updated_at": "2026-04-06T10:30:00.000Z"
        }
      ],
      "created_at": "2026-01-15T10:30:00.000Z",
      "updated_at": "2026-04-01T08:00:00.000Z"
    }
  ],
  "has_more": false
}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found."
  }
}

Create a brand

Creates a brand kit with a theme and optional AI instruction. Add assets by creating or updating assets with brand_id set to this brand. If a logo or other brand file is only available locally, create the brand first, then open /brands/{brand_id} in NextDocs to upload the asset there.

POST
/v1/brands

Authorization

AuthorizationRequiredBearer <token>

NextDocs API key (nxd_xxx format)

In: header

Request Body

application/jsonOptional
nameRequiredstring

Brand kit name.

Minimum length: 1Maximum length: 100
theme_idRequiredstring

ID of an existing theme or a system theme key.

Minimum length: 1
ai_instructionstring

Custom AI instruction applied when this brand kit is active.

Maximum length: 2000

Response Body

The created brand.

objectRequiredstring
Value in: "brand"
idRequiredstring
nameRequiredstring
ai_instructionRequiredstring | null | null
theme_idRequiredstring | null | null
themeRequiredobject | null | null
assetsRequiredarray<object>

@minItems 0

@minItems 0

@minItems 0

created_atRequiredstring
updated_atRequiredstring

Request validation failed.

TypeScript Definitions

Use the response body type in TypeScript.

errorRequiredobject

Authentication required or API key is invalid.

TypeScript Definitions

Use the response body type in TypeScript.

errorRequiredobject

The requested resource was not found.

TypeScript Definitions

Use the response body type in TypeScript.

errorRequiredobject
curl -X POST "https://api.nextdocs.io/v1/brands" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "theme_id": "theme_xyz789",
    "ai_instruction": "Use formal tone and blue color scheme."
  }'
const body = JSON.stringify({
  "name": "Acme Corp",
  "theme_id": "theme_xyz789",
  "ai_instruction": "Use formal tone and blue color scheme."
})

fetch("https://api.nextdocs.io/v1/brands", {
  headers: {
    "Authorization": "Bearer <token>"
  },
  body
})
package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
  "strings"
)

func main() {
  url := "https://api.nextdocs.io/v1/brands"
  body := strings.NewReader(`{
    "name": "Acme Corp",
    "theme_id": "theme_xyz789",
    "ai_instruction": "Use formal tone and blue color scheme."
  }`)
  req, _ := http.NewRequest("POST", url, body)
  req.Header.Add("Authorization", "Bearer <token>")
  req.Header.Add("Content-Type", "application/json")
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}
import requests

url = "https://api.nextdocs.io/v1/brands"
body = {
  "name": "Acme Corp",
  "theme_id": "theme_xyz789",
  "ai_instruction": "Use formal tone and blue color scheme."
}
response = requests.request("POST", url, json = body, headers = {
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
})

print(response.text)
{
  "object": "brand",
  "id": "brand_abc123",
  "name": "Acme Corp",
  "ai_instruction": "Use formal tone and blue color scheme.",
  "theme_id": "theme_xyz789",
  "theme": {
    "object": "theme",
    "id": "abc123",
    "name": "Midnight Blue",
    "is_custom": true,
    "font_primary": "Playfair Display",
    "font_secondary": "Inter",
    "colors": {
      "background": "#FFFFFF",
      "foreground": "#1F1F1F",
      "muted": "#F5F5F5",
      "card": "#FAFAFA",
      "text_on_muted": "#6B7280",
      "text_on_card": "#374151",
      "primary": "#3B82F6",
      "secondary": "#8B5CF6",
      "tertiary": "#EC4899",
      "text_on_primary": "#FFFFFF",
      "text_on_secondary": "#FFFFFF",
      "text_on_tertiary": "#FFFFFF",
      "border": "#E5E7EB"
    },
    "created_at": "2026-01-15T10:30:00.000Z",
    "updated_at": "2026-04-01T08:00:00.000Z"
  },
  "assets": [
    {
      "object": "asset",
      "id": "asset_abc123",
      "name": "LiveHaus Logo",
      "type": "icon",
      "url": "https://cdn.nextdocs.com/users/user_123/assets/logo.png",
      "slug": "livehaus-logo",
      "format": "png",
      "usage_mode": "always",
      "category": "logo",
      "tags": [
        "logo",
        "brand",
        "mark"
      ],
      "brand_id": "brand_abc123",
      "size": 2048,
      "width": 512,
      "height": 512,
      "created_at": "2026-04-06T10:30:00.000Z",
      "updated_at": "2026-04-06T10:30:00.000Z"
    }
  ],
  "created_at": "2026-01-15T10:30:00.000Z",
  "updated_at": "2026-04-01T08:00:00.000Z"
}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found."
  }
}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found."
  }
}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found."
  }
}

Get a brand

Returns a single brand kit by ID, including its theme and linked assets. Use /brands/{id} in NextDocs when the user needs to manage brand assets interactively.

GET
/v1/brands/{id}

Authorization

AuthorizationRequiredBearer <token>

NextDocs API key (nxd_xxx format)

In: header

Path Parameters

idRequiredstring

Brand ID

Response Body

The requested brand.

objectRequiredstring
Value in: "brand"
idRequiredstring
nameRequiredstring
ai_instructionRequiredstring | null | null
theme_idRequiredstring | null | null
themeRequiredobject | null | null
assetsRequiredarray<object>

@minItems 0

@minItems 0

@minItems 0

created_atRequiredstring
updated_atRequiredstring

Authentication required or API key is invalid.

TypeScript Definitions

Use the response body type in TypeScript.

errorRequiredobject

Access denied.

TypeScript Definitions

Use the response body type in TypeScript.

errorRequiredobject

The requested resource was not found.

TypeScript Definitions

Use the response body type in TypeScript.

errorRequiredobject
curl -X GET "https://api.nextdocs.io/v1/brands/brand_abc123" \
  -H "Authorization: Bearer <token>"
fetch("https://api.nextdocs.io/v1/brands/brand_abc123", {
  headers: {
    "Authorization": "Bearer <token>"
  }
})
package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {
  url := "https://api.nextdocs.io/v1/brands/brand_abc123"

  req, _ := http.NewRequest("GET", url, nil)
  req.Header.Add("Authorization", "Bearer <token>")
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}
import requests

url = "https://api.nextdocs.io/v1/brands/brand_abc123"

response = requests.request("GET", url, headers = {
  "Authorization": "Bearer <token>"
})

print(response.text)
{
  "object": "brand",
  "id": "brand_abc123",
  "name": "Acme Corp",
  "ai_instruction": "Use formal tone and blue color scheme.",
  "theme_id": "theme_xyz789",
  "theme": {
    "object": "theme",
    "id": "abc123",
    "name": "Midnight Blue",
    "is_custom": true,
    "font_primary": "Playfair Display",
    "font_secondary": "Inter",
    "colors": {
      "background": "#FFFFFF",
      "foreground": "#1F1F1F",
      "muted": "#F5F5F5",
      "card": "#FAFAFA",
      "text_on_muted": "#6B7280",
      "text_on_card": "#374151",
      "primary": "#3B82F6",
      "secondary": "#8B5CF6",
      "tertiary": "#EC4899",
      "text_on_primary": "#FFFFFF",
      "text_on_secondary": "#FFFFFF",
      "text_on_tertiary": "#FFFFFF",
      "border": "#E5E7EB"
    },
    "created_at": "2026-01-15T10:30:00.000Z",
    "updated_at": "2026-04-01T08:00:00.000Z"
  },
  "assets": [
    {
      "object": "asset",
      "id": "asset_abc123",
      "name": "LiveHaus Logo",
      "type": "icon",
      "url": "https://cdn.nextdocs.com/users/user_123/assets/logo.png",
      "slug": "livehaus-logo",
      "format": "png",
      "usage_mode": "always",
      "category": "logo",
      "tags": [
        "logo",
        "brand",
        "mark"
      ],
      "brand_id": "brand_abc123",
      "size": 2048,
      "width": 512,
      "height": 512,
      "created_at": "2026-04-06T10:30:00.000Z",
      "updated_at": "2026-04-06T10:30:00.000Z"
    }
  ],
  "created_at": "2026-01-15T10:30:00.000Z",
  "updated_at": "2026-04-01T08:00:00.000Z"
}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found."
  }
}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found."
  }
}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found."
  }
}

Update a brand

Partially updates a brand kit. Only provided fields are changed.

PATCH
/v1/brands/{id}

Authorization

AuthorizationRequiredBearer <token>

NextDocs API key (nxd_xxx format)

In: header

Request Body

application/jsonOptional
namestring
Minimum length: 1Maximum length: 100
theme_idstring
Minimum length: 1
ai_instructionstring | null | null

Set to null to clear.

Maximum length: 2000

Path Parameters

idRequiredstring

Brand ID

Response Body

The updated brand.

objectRequiredstring
Value in: "brand"
idRequiredstring
nameRequiredstring
ai_instructionRequiredstring | null | null
theme_idRequiredstring | null | null
themeRequiredobject | null | null
assetsRequiredarray<object>

@minItems 0

@minItems 0

@minItems 0

created_atRequiredstring
updated_atRequiredstring

Request validation failed.

TypeScript Definitions

Use the response body type in TypeScript.

errorRequiredobject

Authentication required or API key is invalid.

TypeScript Definitions

Use the response body type in TypeScript.

errorRequiredobject

Access denied.

TypeScript Definitions

Use the response body type in TypeScript.

errorRequiredobject

The requested resource was not found.

TypeScript Definitions

Use the response body type in TypeScript.

errorRequiredobject
curl -X PATCH "https://api.nextdocs.io/v1/brands/brand_abc123" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp v2",
    "theme_id": "theme_new123",
    "ai_instruction": null
  }'
const body = JSON.stringify({
  "name": "Acme Corp v2",
  "theme_id": "theme_new123",
  "ai_instruction": null
})

fetch("https://api.nextdocs.io/v1/brands/brand_abc123", {
  headers: {
    "Authorization": "Bearer <token>"
  },
  body
})
package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
  "strings"
)

func main() {
  url := "https://api.nextdocs.io/v1/brands/brand_abc123"
  body := strings.NewReader(`{
    "name": "Acme Corp v2",
    "theme_id": "theme_new123",
    "ai_instruction": null
  }`)
  req, _ := http.NewRequest("PATCH", url, body)
  req.Header.Add("Authorization", "Bearer <token>")
  req.Header.Add("Content-Type", "application/json")
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}
import requests

url = "https://api.nextdocs.io/v1/brands/brand_abc123"
body = {
  "name": "Acme Corp v2",
  "theme_id": "theme_new123",
  "ai_instruction": null
}
response = requests.request("PATCH", url, json = body, headers = {
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
})

print(response.text)
{
  "object": "brand",
  "id": "brand_abc123",
  "name": "Acme Corp",
  "ai_instruction": "Use formal tone and blue color scheme.",
  "theme_id": "theme_xyz789",
  "theme": {
    "object": "theme",
    "id": "abc123",
    "name": "Midnight Blue",
    "is_custom": true,
    "font_primary": "Playfair Display",
    "font_secondary": "Inter",
    "colors": {
      "background": "#FFFFFF",
      "foreground": "#1F1F1F",
      "muted": "#F5F5F5",
      "card": "#FAFAFA",
      "text_on_muted": "#6B7280",
      "text_on_card": "#374151",
      "primary": "#3B82F6",
      "secondary": "#8B5CF6",
      "tertiary": "#EC4899",
      "text_on_primary": "#FFFFFF",
      "text_on_secondary": "#FFFFFF",
      "text_on_tertiary": "#FFFFFF",
      "border": "#E5E7EB"
    },
    "created_at": "2026-01-15T10:30:00.000Z",
    "updated_at": "2026-04-01T08:00:00.000Z"
  },
  "assets": [
    {
      "object": "asset",
      "id": "asset_abc123",
      "name": "LiveHaus Logo",
      "type": "icon",
      "url": "https://cdn.nextdocs.com/users/user_123/assets/logo.png",
      "slug": "livehaus-logo",
      "format": "png",
      "usage_mode": "always",
      "category": "logo",
      "tags": [
        "logo",
        "brand",
        "mark"
      ],
      "brand_id": "brand_abc123",
      "size": 2048,
      "width": 512,
      "height": 512,
      "created_at": "2026-04-06T10:30:00.000Z",
      "updated_at": "2026-04-06T10:30:00.000Z"
    }
  ],
  "created_at": "2026-01-15T10:30:00.000Z",
  "updated_at": "2026-04-01T08:00:00.000Z"
}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found."
  }
}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found."
  }
}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found."
  }
}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found."
  }
}

Delete a brand

Deletes a brand kit and unlinks all associated assets. The linked theme is not deleted.

DELETE
/v1/brands/{id}

Authorization

AuthorizationRequiredBearer <token>

NextDocs API key (nxd_xxx format)

In: header

Path Parameters

idRequiredstring

Brand ID

Response Body

Brand deleted successfully.

Authentication required or API key is invalid.

TypeScript Definitions

Use the response body type in TypeScript.

errorRequiredobject

Access denied.

TypeScript Definitions

Use the response body type in TypeScript.

errorRequiredobject

The requested resource was not found.

TypeScript Definitions

Use the response body type in TypeScript.

errorRequiredobject
curl -X DELETE "https://api.nextdocs.io/v1/brands/brand_abc123" \
  -H "Authorization: Bearer <token>"
fetch("https://api.nextdocs.io/v1/brands/brand_abc123", {
  headers: {
    "Authorization": "Bearer <token>"
  }
})
package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {
  url := "https://api.nextdocs.io/v1/brands/brand_abc123"

  req, _ := http.NewRequest("DELETE", url, nil)
  req.Header.Add("Authorization", "Bearer <token>")
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}
import requests

url = "https://api.nextdocs.io/v1/brands/brand_abc123"

response = requests.request("DELETE", url, headers = {
  "Authorization": "Bearer <token>"
})

print(response.text)
Empty
{
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found."
  }
}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found."
  }
}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found."
  }
}