NextDocsNextDocs

Assets

User-uploaded assets that can optionally be linked to brands.

List assets

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

GET
/v1/assets

Authorization

AuthorizationRequiredBearer <token>

NextDocs API key (nxd_xxx format)

In: header

Query Parameters

limitinteger

Number of assets to return (1-20).

Default: 20Minimum: 1Maximum: 20
afterstring

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

typestring

Filter by asset type.

Value in: "icon" | "illustration" | "photo" | "video"
brand_idstring

Filter to assets linked to a specific brand.

unassignedboolean | null | null

When true, return only unassigned assets.

Response Body

A paginated list of assets.

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.

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 GET "https://api.nextdocs.io/v1/assets?limit=20&after=asset_abc123&type=icon&brand_id=brand_abc123&unassigned=true" \
  -H "Authorization: Bearer <token>"
fetch("https://api.nextdocs.io/v1/assets?limit=20&after=asset_abc123&type=icon&brand_id=brand_abc123&unassigned=true", {
  headers: {
    "Authorization": "Bearer <token>"
  }
})
package main

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

func main() {
  url := "https://api.nextdocs.io/v1/assets?limit=20&after=asset_abc123&type=icon&brand_id=brand_abc123&unassigned=true"

  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/assets?limit=20&after=asset_abc123&type=icon&brand_id=brand_abc123&unassigned=true"

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

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

Create an asset

Creates a user asset from a fetchable source URL and optionally links it to a brand. Prefer HTTPS URLs for tool-driven workflows. If the file only exists in the NextDocs app or a chat attachment, open the brand in NextDocs and upload it there before continuing with the returned asset.

POST
/v1/assets

Authorization

AuthorizationRequiredBearer <token>

NextDocs API key (nxd_xxx format)

In: header

Request Body

application/jsonOptional
source_urlRequiredstring

Fetchable source asset URL. Prefer HTTPS URLs for tool-driven workflows. If the file only exists locally in NextDocs or a chat client, upload it in NextDocs first and then use the resulting asset.

Minimum length: 1
namestring

Display name for the asset. Defaults to a filename-based name when omitted.

Minimum length: 1Maximum length: 200
typestring

Asset type. Defaults to an inferred type when omitted.

Value in: "icon" | "illustration" | "photo" | "video"
usage_modestring

How AI generation should use this asset. Defaults to always for brand-linked assets and maybe otherwise.

Value in: "always" | "maybe" | "never"
brand_idstring | null | null

Optional brand to attach this asset to. Set to null or omit for an unassigned asset.

categorystring | null | null

Optional category label.

Maximum length: 100
tagsarray<string>

Optional search tags.

Response Body

The created asset.

objectRequiredstring
Value in: "asset"
idRequiredstring
nameRequiredstring
typeRequiredstring
Value in: "icon" | "illustration" | "photo" | "video"
urlRequiredstring
slugRequiredstring
formatRequiredstring
usage_modeRequiredstring
Value in: "always" | "maybe" | "never"
categoryRequiredstring | null | null
tagsRequiredarray<string>

@minItems 0

@minItems 0

@minItems 0

brand_idRequiredstring | null | null
sizeRequirednumber | null | null
widthRequirednumber | null | null
heightRequirednumber | null | null
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/assets" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "https://example.com/logo.png",
    "name": "LiveHaus Logo",
    "type": "icon",
    "usage_mode": "always",
    "brand_id": "brand_abc123",
    "category": "logo",
    "tags": [
      "logo",
      "brand",
      "mark"
    ]
  }'
const body = JSON.stringify({
  "source_url": "https://example.com/logo.png",
  "name": "LiveHaus Logo",
  "type": "icon",
  "usage_mode": "always",
  "brand_id": "brand_abc123",
  "category": "logo",
  "tags": [
    "logo",
    "brand",
    "mark"
  ]
})

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

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

func main() {
  url := "https://api.nextdocs.io/v1/assets"
  body := strings.NewReader(`{
    "source_url": "https://example.com/logo.png",
    "name": "LiveHaus Logo",
    "type": "icon",
    "usage_mode": "always",
    "brand_id": "brand_abc123",
    "category": "logo",
    "tags": [
      "logo",
      "brand",
      "mark"
    ]
  }`)
  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/assets"
body = {
  "source_url": "https://example.com/logo.png",
  "name": "LiveHaus Logo",
  "type": "icon",
  "usage_mode": "always",
  "brand_id": "brand_abc123",
  "category": "logo",
  "tags": [
    "logo",
    "brand",
    "mark"
  ]
}
response = requests.request("POST", url, json = body, headers = {
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
})

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

Returns a single asset by ID.

GET
/v1/assets/{id}

Authorization

AuthorizationRequiredBearer <token>

NextDocs API key (nxd_xxx format)

In: header

Path Parameters

idRequiredstring

Asset ID

Response Body

The requested asset.

objectRequiredstring
Value in: "asset"
idRequiredstring
nameRequiredstring
typeRequiredstring
Value in: "icon" | "illustration" | "photo" | "video"
urlRequiredstring
slugRequiredstring
formatRequiredstring
usage_modeRequiredstring
Value in: "always" | "maybe" | "never"
categoryRequiredstring | null | null
tagsRequiredarray<string>

@minItems 0

@minItems 0

@minItems 0

brand_idRequiredstring | null | null
sizeRequirednumber | null | null
widthRequirednumber | null | null
heightRequirednumber | null | null
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/assets/asset_abc123" \
  -H "Authorization: Bearer <token>"
fetch("https://api.nextdocs.io/v1/assets/asset_abc123", {
  headers: {
    "Authorization": "Bearer <token>"
  }
})
package main

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

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

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

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

Update an asset

Partially updates an asset. Only provided fields are changed.

PATCH
/v1/assets/{id}

Authorization

AuthorizationRequiredBearer <token>

NextDocs API key (nxd_xxx format)

In: header

Request Body

application/jsonOptional
namestring
Minimum length: 1Maximum length: 200
typestring
Value in: "icon" | "illustration" | "photo" | "video"
usage_modestring
Value in: "always" | "maybe" | "never"
brand_idstring | null | null

Set to null to unlink this asset from its current brand.

categorystring | null | null

Set to null to clear the category.

Maximum length: 100
tagsarray<string>

Path Parameters

idRequiredstring

Asset ID

Response Body

The updated asset.

objectRequiredstring
Value in: "asset"
idRequiredstring
nameRequiredstring
typeRequiredstring
Value in: "icon" | "illustration" | "photo" | "video"
urlRequiredstring
slugRequiredstring
formatRequiredstring
usage_modeRequiredstring
Value in: "always" | "maybe" | "never"
categoryRequiredstring | null | null
tagsRequiredarray<string>

@minItems 0

@minItems 0

@minItems 0

brand_idRequiredstring | null | null
sizeRequirednumber | null | null
widthRequirednumber | null | null
heightRequirednumber | null | null
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 PATCH "https://api.nextdocs.io/v1/assets/asset_abc123" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "LiveHaus Wordmark",
    "type": "icon",
    "usage_mode": "maybe",
    "brand_id": null,
    "category": null,
    "tags": [
      "logo",
      "secondary-mark"
    ]
  }'
const body = JSON.stringify({
  "name": "LiveHaus Wordmark",
  "type": "icon",
  "usage_mode": "maybe",
  "brand_id": null,
  "category": null,
  "tags": [
    "logo",
    "secondary-mark"
  ]
})

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

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

func main() {
  url := "https://api.nextdocs.io/v1/assets/asset_abc123"
  body := strings.NewReader(`{
    "name": "LiveHaus Wordmark",
    "type": "icon",
    "usage_mode": "maybe",
    "brand_id": null,
    "category": null,
    "tags": [
      "logo",
      "secondary-mark"
    ]
  }`)
  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/assets/asset_abc123"
body = {
  "name": "LiveHaus Wordmark",
  "type": "icon",
  "usage_mode": "maybe",
  "brand_id": null,
  "category": null,
  "tags": [
    "logo",
    "secondary-mark"
  ]
}
response = requests.request("PATCH", url, json = body, headers = {
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
})

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

Deletes a user asset.

DELETE
/v1/assets/{id}

Authorization

AuthorizationRequiredBearer <token>

NextDocs API key (nxd_xxx format)

In: header

Path Parameters

idRequiredstring

Asset ID

Response Body

Asset 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 asset could not be deleted due to a conflict.

TypeScript Definitions

Use the response body type in TypeScript.

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

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

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