NextDocsNextDocs

Themes

Theme management — colors, fonts, and palette customization.

List themes

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

GET
/v1/themes

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 themes.

TypeScript Definitions

Use the response body type in TypeScript.

objectRequiredstring
Value in: "list"
dataRequiredarray<object | null | null>
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/themes?limit=20&after=clxyz123..." \
  -H "Authorization: Bearer <token>"
fetch("https://api.nextdocs.io/v1/themes?limit=20&after=clxyz123...", {
  headers: {
    "Authorization": "Bearer <token>"
  }
})
package main

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

func main() {
  url := "https://api.nextdocs.io/v1/themes?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/themes?limit=20&after=clxyz123..."

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

print(response.text)
{
  "object": "list",
  "data": [
    {
      "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"
    }
  ],
  "has_more": false
}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found."
  }
}

Create a theme

Creates a custom theme with the specified colors and fonts.

POST
/v1/themes

Authorization

AuthorizationRequiredBearer <token>

NextDocs API key (nxd_xxx format)

In: header

Request Body

application/jsonOptional
nameRequiredstring

Display name for the theme.

Minimum length: 1Maximum length: 100
font_primarystring

Heading font family (Google Fonts name).

Maximum length: 100
font_secondarystring

Body font family (Google Fonts name).

Maximum length: 100
colorsobject

Theme color palette. All fields optional.

Response Body

The created theme.

responseRequiredobject | null | null

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
curl -X POST "https://api.nextdocs.io/v1/themes" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Brand Theme",
    "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"
    }
  }'
const body = JSON.stringify({
  "name": "My Brand Theme",
  "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"
  }
})

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

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

func main() {
  url := "https://api.nextdocs.io/v1/themes"
  body := strings.NewReader(`{
    "name": "My Brand Theme",
    "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"
    }
  }`)
  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/themes"
body = {
  "name": "My Brand Theme",
  "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"
  }
}
response = requests.request("POST", url, json = body, headers = {
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
})

print(response.text)
{
  "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"
}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found."
  }
}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found."
  }
}

Get a theme

Returns a single theme by ID.

GET
/v1/themes/{id}

Authorization

AuthorizationRequiredBearer <token>

NextDocs API key (nxd_xxx format)

In: header

Path Parameters

idRequiredstring

Theme ID

Response Body

The requested theme.

responseRequiredobject | null | null

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/themes/theme_abc123" \
  -H "Authorization: Bearer <token>"
fetch("https://api.nextdocs.io/v1/themes/theme_abc123", {
  headers: {
    "Authorization": "Bearer <token>"
  }
})
package main

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

func main() {
  url := "https://api.nextdocs.io/v1/themes/theme_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/themes/theme_abc123"

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

print(response.text)
{
  "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"
}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found."
  }
}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found."
  }
}

Update a theme

Partially updates a theme. Only provided fields are changed.

PATCH
/v1/themes/{id}

Authorization

AuthorizationRequiredBearer <token>

NextDocs API key (nxd_xxx format)

In: header

Request Body

application/jsonOptional
namestring

Updated display name for the theme.

Minimum length: 1Maximum length: 100
font_primarystring

Updated heading font family.

Maximum length: 100
font_secondarystring

Updated body font family.

Maximum length: 100
colorsobject

Partial palette update. Provide only the colors you want to change.

Path Parameters

idRequiredstring

Theme ID

Response Body

The updated theme.

responseRequiredobject | null | null

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 PATCH "https://api.nextdocs.io/v1/themes/theme_abc123" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Theme",
    "font_primary": "string",
    "font_secondary": "string",
    "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"
    }
  }'
const body = JSON.stringify({
  "name": "Updated Theme",
  "font_primary": "string",
  "font_secondary": "string",
  "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"
  }
})

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

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

func main() {
  url := "https://api.nextdocs.io/v1/themes/theme_abc123"
  body := strings.NewReader(`{
    "name": "Updated Theme",
    "font_primary": "string",
    "font_secondary": "string",
    "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"
    }
  }`)
  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/themes/theme_abc123"
body = {
  "name": "Updated Theme",
  "font_primary": "string",
  "font_secondary": "string",
  "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"
  }
}
response = requests.request("PATCH", url, json = body, headers = {
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
})

print(response.text)
{
  "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"
}
{
  "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 theme

Deletes a theme. Fails with 409 if any brands still reference it.

DELETE
/v1/themes/{id}

Authorization

AuthorizationRequiredBearer <token>

NextDocs API key (nxd_xxx format)

In: header

Path Parameters

idRequiredstring

Theme ID

Response Body

Theme 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

The theme is still referenced by one or more brands.

TypeScript Definitions

Use the response body type in TypeScript.

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

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

func main() {
  url := "https://api.nextdocs.io/v1/themes/theme_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/themes/theme_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."
  }
}