NextDocsNextDocs

Assets

User-uploaded assets that can optionally be linked to brands. For tool-driven workflows, prefer fetchable HTTPS URLs or upload the file in NextDocs first.

List assets

Returns a paginated list of the user's assets.

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.

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

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

Create an asset

Creates an asset record from a fetchable HTTPS source URL, optionally linked to a brand. Data URLs and base64 payloads are not accepted.

POST
/v1/assets

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
source_urlRequiredstring

Fetchable HTTPS source asset URL. Data URLs and base64 payloads are not accepted. 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

Resource created successfully.

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

Rate limit or usage quota exceeded.

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 '{
    "org_id": "org_2abc123",
    "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({
  "org_id": "org_2abc123",
  "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(`{
    "org_id": "org_2abc123",
    "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 = {
  "org_id": "org_2abc123",
  "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."
  }
}
{
  "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 resource.

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

Updated asset display name.

Minimum length: 1Maximum length: 200
typestring

Updated asset type.

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

Updated guidance for how AI generation should use this asset.

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>

Replacement search tags for this asset.

Path Parameters

idRequiredstring

Asset ID

Response Body

Resource updated successfully.

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

Rate limit or usage quota exceeded.

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

Delete an asset

Deletes an asset.

DELETE
/v1/assets/{id}

Authorization

AuthorizationRequiredBearer <token>

NextDocs API key (nxd_xxx format)

In: header

Path Parameters

idRequiredstring

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