NextDocsNextDocs

Brands

Brand kit management — themes, assets, and AI instructions. Brand assets can also be managed interactively in NextDocs at /brands/{brand_id}.

List brands

Returns a paginated list of the user's brand kits.

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.

org_idstring

Organization ID returned by organizations.list. Omit for personal scope.

Minimum length: 1

Response Body

A paginated list of resources.

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...&org_id=org_2abc123" \
  -H "Authorization: Bearer <token>"
fetch("https://api.nextdocs.io/v1/brands?limit=20&after=clxyz123...&org_id=org_2abc123", {
  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...&org_id=org_2abc123"

  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...&org_id=org_2abc123"

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": {
        "id": "abc123",
        "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",
        "font_primary": "Playfair Display",
        "font_secondary": "Inter",
        "is_custom": true,
        "name": "Midnight Blue",
        "object": "theme",
        "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 the specified name and theme_id and optional AI instruction. theme_id must reference a theme owned by the user or a system theme key. Add assets to the brand by passing brand_id when creating or updating assets.

POST
/v1/brands

Authorization

AuthorizationRequiredBearer <token>

NextDocs API key (nxd_xxx format)

In: header

Request Body

application/jsonOptional
org_idstring

Organization ID returned by organizations.list. Omit for personal scope.

Minimum length: 1
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

Resource created successfully.

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

Rate limit or usage quota exceeded.

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 '{
    "org_id": "org_2abc123",
    "name": "Acme Corp",
    "theme_id": "theme_xyz789",
    "ai_instruction": "Use formal tone and blue color scheme."
  }'
const body = JSON.stringify({
  "org_id": "org_2abc123",
  "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(`{
    "org_id": "org_2abc123",
    "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 = {
  "org_id": "org_2abc123",
  "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": {
    "id": "abc123",
    "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",
    "font_primary": "Playfair Display",
    "font_secondary": "Inter",
    "is_custom": true,
    "name": "Midnight Blue",
    "object": "theme",
    "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."
  }
}

Get a brand

Returns a single brand kit by ID, including its theme and linked assets.

GET
/v1/brands/{id}

Authorization

AuthorizationRequiredBearer <token>

NextDocs API key (nxd_xxx format)

In: header

Path Parameters

idRequiredstring

Brand ID

Query Parameters

org_idstring

Organization ID returned by organizations.list. Omit for personal scope.

Minimum length: 1

Response Body

The requested resource.

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

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?org_id=org_2abc123" \
  -H "Authorization: Bearer <token>"
fetch("https://api.nextdocs.io/v1/brands/brand_abc123?org_id=org_2abc123", {
  headers: {
    "Authorization": "Bearer <token>"
  }
})
package main

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

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

  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?org_id=org_2abc123"

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": {
    "id": "abc123",
    "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",
    "font_primary": "Playfair Display",
    "font_secondary": "Inter",
    "is_custom": true,
    "name": "Midnight Blue",
    "object": "theme",
    "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."
  }
}

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

Updated brand kit name.

Minimum length: 1Maximum length: 100
theme_idstring

Updated theme ID to apply to this brand kit.

Minimum length: 1
ai_instructionstring | null | null

Updated AI instruction. Set to null to clear the existing instruction.

Maximum length: 2000
org_idstring

Organization ID returned by organizations.list. Omit for personal scope.

Minimum length: 1

Path Parameters

idRequiredstring

Brand ID

Response Body

Resource updated successfully.

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

Rate limit or usage quota exceeded.

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,
    "org_id": "org_2abc123"
  }'
const body = JSON.stringify({
  "name": "Acme Corp v2",
  "theme_id": "theme_new123",
  "ai_instruction": null,
  "org_id": "org_2abc123"
})

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,
    "org_id": "org_2abc123"
  }`)
  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,
  "org_id": "org_2abc123"
}
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": {
    "id": "abc123",
    "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",
    "font_primary": "Playfair Display",
    "font_secondary": "Inter",
    "is_custom": true,
    "name": "Midnight Blue",
    "object": "theme",
    "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

Request Body

application/jsonOptional
org_idstring

Organization ID returned by organizations.list. Omit for personal scope.

Minimum length: 1

Path Parameters

idRequiredstring

Brand ID

Response Body

Resource deleted.

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

Request conflicts with the current state of the resource.

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>" \
  -H "Content-Type: application/json" \
  -d '{
    "org_id": "org_2abc123"
  }'
const body = JSON.stringify({
  "org_id": "org_2abc123"
})

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(`{
    "org_id": "org_2abc123"
  }`)
  req, _ := http.NewRequest("DELETE", 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 = {
  "org_id": "org_2abc123"
}
response = requests.request("DELETE", url, json = body, headers = {
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
})

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."
  }
}