NextDocsNextDocs

Artifacts

Artifact CRUD and AI generation.

List artifacts

Returns a paginated list of the authenticated user's artifacts.

GET
/v1/artifacts

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

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

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

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

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

print(response.text)
{
  "object": "list",
  "data": [
    {
      "id": "doc_abc123",
      "brand_id": null,
      "created_at": "2026-01-15T10:30:00.000Z",
      "name": "Q2 Pitch Deck",
      "object": "artifact",
      "page_count": 12,
      "status": "ready",
      "theme_id": null,
      "type": "presentation",
      "updated_at": "2026-04-01T08:00:00.000Z"
    }
  ],
  "has_more": false
}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found."
  }
}

Create an artifact

Creates a single artifact via AI generation and waits for completion. Best for short generations; prefer artifacts.create_async for multi-page documents, slower model runs, or multiple design variations. Supported types: presentation, document, social, image, pageless.

POST
/v1/artifacts

Authorization

AuthorizationRequiredBearer <token>

NextDocs API key (nxd_xxx format)

In: header

Request Body

application/jsonOptional
brand_idstring

Brand kit ID to apply.

instructionRequiredstring

AI generation instruction.

Minimum length: 1Maximum length: 10000
num_pagesinteger

Number of pages to generate.

Minimum: 1Maximum: 50
theme_idstring

Theme ID to apply. When omitted, the API auto-generates appearance variants.

namestring

Optional artifact name.

Minimum length: 1Maximum length: 500
modelstring

Model to use. 'fast' for speed, 'quality' for best results, or a specific AI gateway model ID.

num_copiesinteger

Synchronous artifact creation only supports a single design variation. Use the async endpoint for multiple copies.

Default: 1Minimum: 1Maximum: 1
template_idstring

Template to base the generation on. The template's structure and theme guide the AI.

typeRequiredstring

Artifact type to generate. Supported values: presentation, document, social, image, pageless.

Value in: "presentation" | "document" | "social" | "image" | "pageless"

Response Body

Artifact created successfully.

idRequiredstring
brand_idRequiredstring | null | null
created_atRequiredstring
nameRequiredstring
objectRequiredstring
Value in: "artifact"
page_countRequirednumber | null | null
statusRequiredstring
Value in: "generating" | "ready" | "failed"
theme_idRequiredstring | null | null

Effective theme ID for the artifact. This is the explicitly requested theme when provided, otherwise the linked brand theme when one was applied.

typeRequiredstring
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

User has exhausted available generation credits.

TypeScript Definitions

Use the response body type in TypeScript.

errorRequiredobject
curl -X POST "https://api.nextdocs.io/v1/artifacts" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "brand_id": "brand_abc123",
    "instruction": "Create a pitch deck for a SaaS startup raising Series A.",
    "num_pages": 12,
    "theme_id": "paperWhite",
    "name": "MCP Integration Test Deck",
    "model": "fast",
    "num_copies": 1,
    "template_id": "tmpl_abc123",
    "type": "presentation"
  }'
const body = JSON.stringify({
  "brand_id": "brand_abc123",
  "instruction": "Create a pitch deck for a SaaS startup raising Series A.",
  "num_pages": 12,
  "theme_id": "paperWhite",
  "name": "MCP Integration Test Deck",
  "model": "fast",
  "num_copies": 1,
  "template_id": "tmpl_abc123",
  "type": "presentation"
})

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

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

func main() {
  url := "https://api.nextdocs.io/v1/artifacts"
  body := strings.NewReader(`{
    "brand_id": "brand_abc123",
    "instruction": "Create a pitch deck for a SaaS startup raising Series A.",
    "num_pages": 12,
    "theme_id": "paperWhite",
    "name": "MCP Integration Test Deck",
    "model": "fast",
    "num_copies": 1,
    "template_id": "tmpl_abc123",
    "type": "presentation"
  }`)
  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/artifacts"
body = {
  "brand_id": "brand_abc123",
  "instruction": "Create a pitch deck for a SaaS startup raising Series A.",
  "num_pages": 12,
  "theme_id": "paperWhite",
  "name": "MCP Integration Test Deck",
  "model": "fast",
  "num_copies": 1,
  "template_id": "tmpl_abc123",
  "type": "presentation"
}
response = requests.request("POST", url, json = body, headers = {
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
})

print(response.text)
{
  "id": "doc_abc123",
  "brand_id": null,
  "created_at": "2026-01-15T10:30:00.000Z",
  "name": "Q2 Pitch Deck",
  "object": "artifact",
  "page_count": 12,
  "status": "ready",
  "theme_id": null,
  "type": "presentation",
  "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."
  }
}

Create an artifact asynchronously

Queues artifact generation as a background job. Supported types: presentation, document, social, image, pageless. Supports model selection, template-based generation, and multiple design variations via num_copies. Returns a job object immediately.

POST
/v1/artifacts/async

Authorization

AuthorizationRequiredBearer <token>

NextDocs API key (nxd_xxx format)

In: header

Request Body

application/jsonOptional
brand_idstring

Brand kit ID to apply.

instructionRequiredstring

AI generation instruction.

Minimum length: 1Maximum length: 10000
num_pagesinteger

Number of pages to generate.

Minimum: 1Maximum: 50
theme_idstring

Theme ID to apply. When omitted, the API auto-generates appearance variants.

namestring

Optional artifact name.

Minimum length: 1Maximum length: 500
modelstring

Model to use. 'fast' for speed, 'quality' for best results, or a specific AI gateway model ID.

num_copiesinteger

Number of design variations to generate (1-4). Each variation uses the same prompt but produces different layouts.

Default: 1Minimum: 1Maximum: 4
template_idstring

Template to base the generation on. The template's structure and theme guide the AI.

typeRequiredstring

Artifact type to generate. Supported values: presentation, document, social, image, pageless.

Value in: "presentation" | "document" | "social" | "image" | "pageless"

Response Body

Artifact generation accepted for asynchronous processing.

TypeScript Definitions

Use the response body type in TypeScript.

idRequiredstring
created_atRequiredstring
errorRequiredobject | null | null
objectRequiredstring
Value in: "job"
resultRequiredobject | null | null
statusRequiredstring
Value in: "processing" | "completed" | "failed"
typeRequiredstring
Value in: "artifact.create" | "export.run"
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

User has exhausted available generation credits.

TypeScript Definitions

Use the response body type in TypeScript.

errorRequiredobject
curl -X POST "https://api.nextdocs.io/v1/artifacts/async" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "brand_id": "brand_abc123",
    "instruction": "Create a pitch deck for a SaaS startup raising Series A.",
    "num_pages": 12,
    "theme_id": "paperWhite",
    "name": "MCP Integration Test Deck",
    "model": "fast",
    "num_copies": 1,
    "template_id": "tmpl_abc123",
    "type": "presentation"
  }'
const body = JSON.stringify({
  "brand_id": "brand_abc123",
  "instruction": "Create a pitch deck for a SaaS startup raising Series A.",
  "num_pages": 12,
  "theme_id": "paperWhite",
  "name": "MCP Integration Test Deck",
  "model": "fast",
  "num_copies": 1,
  "template_id": "tmpl_abc123",
  "type": "presentation"
})

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

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

func main() {
  url := "https://api.nextdocs.io/v1/artifacts/async"
  body := strings.NewReader(`{
    "brand_id": "brand_abc123",
    "instruction": "Create a pitch deck for a SaaS startup raising Series A.",
    "num_pages": 12,
    "theme_id": "paperWhite",
    "name": "MCP Integration Test Deck",
    "model": "fast",
    "num_copies": 1,
    "template_id": "tmpl_abc123",
    "type": "presentation"
  }`)
  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/artifacts/async"
body = {
  "brand_id": "brand_abc123",
  "instruction": "Create a pitch deck for a SaaS startup raising Series A.",
  "num_pages": 12,
  "theme_id": "paperWhite",
  "name": "MCP Integration Test Deck",
  "model": "fast",
  "num_copies": 1,
  "template_id": "tmpl_abc123",
  "type": "presentation"
}
response = requests.request("POST", url, json = body, headers = {
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
})

print(response.text)
{
  "id": "job_abc123def456",
  "created_at": "2026-01-15T10:30:00.000Z",
  "error": null,
  "object": "job",
  "result": null,
  "status": "processing",
  "type": "artifact.create",
  "updated_at": "2026-01-15T10: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 artifact

Returns a single artifact by ID, including page count and metadata.

GET
/v1/artifacts/{id}

Authorization

AuthorizationRequiredBearer <token>

NextDocs API key (nxd_xxx format)

In: header

Path Parameters

idRequiredstring

Artifact ID

Response Body

The requested artifact.

idRequiredstring
brand_idRequiredstring | null | null
created_atRequiredstring
nameRequiredstring
objectRequiredstring
Value in: "artifact"
page_countRequirednumber | null | null
statusRequiredstring
Value in: "generating" | "ready" | "failed"
theme_idRequiredstring | null | null

Effective theme ID for the artifact. This is the explicitly requested theme when provided, otherwise the linked brand theme when one was applied.

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

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

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

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

print(response.text)
{
  "id": "doc_abc123",
  "brand_id": null,
  "created_at": "2026-01-15T10:30:00.000Z",
  "name": "Q2 Pitch Deck",
  "object": "artifact",
  "page_count": 12,
  "status": "ready",
  "theme_id": null,
  "type": "presentation",
  "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 an artifact

Partially updates an artifact. Currently supports renaming.

PATCH
/v1/artifacts/{id}

Authorization

AuthorizationRequiredBearer <token>

NextDocs API key (nxd_xxx format)

In: header

Request Body

application/jsonOptional
namestring

Artifact name.

Minimum length: 1Maximum length: 500

Path Parameters

idRequiredstring

Artifact ID

Response Body

The updated artifact.

idRequiredstring
brand_idRequiredstring | null | null
created_atRequiredstring
nameRequiredstring
objectRequiredstring
Value in: "artifact"
page_countRequirednumber | null | null
statusRequiredstring
Value in: "generating" | "ready" | "failed"
theme_idRequiredstring | null | null

Effective theme ID for the artifact. This is the explicitly requested theme when provided, otherwise the linked brand theme when one was applied.

typeRequiredstring
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/artifacts/doc_abc123" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q2 Pitch Deck v2"
  }'
const body = JSON.stringify({
  "name": "Q2 Pitch Deck v2"
})

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

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

func main() {
  url := "https://api.nextdocs.io/v1/artifacts/doc_abc123"
  body := strings.NewReader(`{
    "name": "Q2 Pitch Deck v2"
  }`)
  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/artifacts/doc_abc123"
body = {
  "name": "Q2 Pitch Deck v2"
}
response = requests.request("PATCH", url, json = body, headers = {
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
})

print(response.text)
{
  "id": "doc_abc123",
  "brand_id": null,
  "created_at": "2026-01-15T10:30:00.000Z",
  "name": "Q2 Pitch Deck",
  "object": "artifact",
  "page_count": 12,
  "status": "ready",
  "theme_id": null,
  "type": "presentation",
  "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 an artifact

Permanently deletes an artifact.

DELETE
/v1/artifacts/{id}

Authorization

AuthorizationRequiredBearer <token>

NextDocs API key (nxd_xxx format)

In: header

Path Parameters

idRequiredstring

Artifact ID

Response Body

Artifact 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
curl -X DELETE "https://api.nextdocs.io/v1/artifacts/doc_abc123" \
  -H "Authorization: Bearer <token>"
fetch("https://api.nextdocs.io/v1/artifacts/doc_abc123", {
  headers: {
    "Authorization": "Bearer <token>"
  }
})
package main

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

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