NUWAY API

Knowledge

What your AI workers know comes from your training data: FAQs, documents, websites and more. Everything you add is trained automatically in the background, usually within a few minutes. Until then isTrained is false.

List knowledge

GET /api/v1/external/knowledge Page pagination

Newest first.

Query parameters

Name	Description
`type` string	`FAQ`, `FILE` (documents), `WEB`, `EXCEL`, `AUDIO`, `PICTURE`, or a file extension such as `pdf`
`page` integer	Starts at 0
`size` integer	1–200, default 20

Example request

curl "https://ai.nuway.co/api/v1/external/knowledge?type=FAQ&size=20" \
  -H "X-API-KEY: $NUWAY_API_KEY"

// Node.js 18+. Uses top-level await: save as .mjs (or set "type": "module").
const res = await fetch("https://ai.nuway.co/api/v1/external/knowledge?type=FAQ&size=20", {
  method: "GET",
  headers: {
    "X-API-KEY": process.env.NUWAY_API_KEY
  }
});
const data = await res.json();

import os
import requests
r = requests.get(
    "https://ai.nuway.co/api/v1/external/knowledge?type=FAQ&size=20",
    headers={"X-API-KEY": os.environ["NUWAY_API_KEY"]},
    timeout=30,
)
r.raise_for_status()
data = r.json()

Response

{
  "content": [
    {
      "id": "c094a01a-a4f7-4319-8fdf-c3291d572a7b",
      "question": "What is your policy for replacing a product damaged during shipping?",
      "answer": "Contact our team within 14 days and we'll send a replacement.",
      "isTrained": true,
      "trainedAiCharCount": 207,
      "latestAiTrainedOn": "2026-09-28T12:03:56.891107",
      "createdAt": "2026-09-28T12:03:56.893994",
      "updatedAt": "2026-09-28T12:03:56.894000"
    }
  ],
  "totalElements": 17,
  "totalPages": 1,
  "size": 20,
  "number": 0
}

Response fields

Name	Description
`id`	Use it to update or delete.
`isTrained, latestAiTrainedOn`	Whether the AI has learned it yet, and when.
`trainedAiCharCount`	Size of the content.
`resourceUrl`	Documents only: a temporary download link, valid for 12 hours. Request the list again for a fresh one.

FAQ items have question and answer. Document items look like this:

{
  "id": "d5e4f0aa-f1b0-440d-bb62-4fe7a8fa6841",
  "fileName": "price-list-2026.pdf",
  "resourceUrl": "https://storage.googleapis.com/...",
  "resourceExtension": "pdf",
  "isTrained": true,
  "trainedAiCharCount": 171588,
  "latestAiTrainedOn": "2026-10-06T16:46:33.310425",
  "createdAt": "2026-10-06T16:46:25.241804",
  "updatedAt": "2026-10-06T16:46:33.308543"
}

Upload a document

POST /api/v1/external/knowledge/documents

Upload as multipart/form-data in a field named file, up to 100 MB. Supported: PDF, Word (.docx, .doc), text (.txt), CSV, Excel (.xlsx, .xls), images (.jpg, .png) and audio (.mp3, .wav).

Form data

Name	Description
`file` file required	The document, up to 100 MB.

Example request

curl -X POST "https://ai.nuway.co/api/v1/external/knowledge/documents" \
  -H "X-API-KEY: $NUWAY_API_KEY" \
  -F "[email protected]"

// Node.js 20+. Uses top-level await: save as .mjs (or set "type": "module").
import { openAsBlob } from "node:fs";
const form = new FormData();
form.append("file", await openAsBlob("price-list-2026.pdf"), "price-list-2026.pdf");
const res = await fetch("https://ai.nuway.co/api/v1/external/knowledge/documents", {
  method: "POST",
  headers: {
    "X-API-KEY": process.env.NUWAY_API_KEY
  },
  body: form
});
const data = await res.json();

import os
import requests
with open("price-list-2026.pdf", "rb") as f:
    r = requests.post(
        "https://ai.nuway.co/api/v1/external/knowledge/documents",
        headers={"X-API-KEY": os.environ["NUWAY_API_KEY"]},
        files={"file": f},
        timeout=300,  # large files take a while to upload
    )
r.raise_for_status()
data = r.json()

Response

201 Created

The response is the new document item, with isTrained: false until training finishes. Training is billed like training from the dashboard. If your wallet can't cover it, the document stays untrained and you get a dashboard notification to add funds; you can then train it from the dashboard.

Errors 402 with "kind": "knowledge_base" when the extra storage can't be paid for (nothing is stored), 409 account setup not finished, 413 file too large.

Add an FAQ

POST /api/v1/external/knowledge/faqs

Add a question and answer. The response (201) is the new FAQ item.

Request body

Name	Description
`question` string required	Up to 4,000 characters.
`answer` string required	Up to 20,000 characters.

Example request

curl -X POST "https://ai.nuway.co/api/v1/external/knowledge/faqs" \
  -H "X-API-KEY: $NUWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"Do you have parking?","answer":"Yes, free visitor parking is available behind the building."}'

// Node.js 18+. Uses top-level await: save as .mjs (or set "type": "module").
const res = await fetch("https://ai.nuway.co/api/v1/external/knowledge/faqs", {
  method: "POST",
  headers: {
    "X-API-KEY": process.env.NUWAY_API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "question": "Do you have parking?",
    "answer": "Yes, free visitor parking is available behind the building."
  })
});
const data = await res.json();

import os
import requests
r = requests.post(
    "https://ai.nuway.co/api/v1/external/knowledge/faqs",
    headers={"X-API-KEY": os.environ["NUWAY_API_KEY"]},
    json={
      "question": "Do you have parking?",
      "answer": "Yes, free visitor parking is available behind the building."
    },
    timeout=30,
)
r.raise_for_status()
data = r.json()

Update an FAQ

PUT /api/v1/external/knowledge/faqs/{id}

Replace an FAQ's question and answer. It is retrained automatically, and the old answer stops being used immediately.

Path parameters

Name	Description
`id` string required	The FAQ id, from List knowledge.

Request body

Name	Description
`question` string required	Up to 4,000 characters.
`answer` string required	Up to 20,000 characters.

Example request

curl -X PUT "https://ai.nuway.co/api/v1/external/knowledge/faqs/{id}" \
  -H "X-API-KEY: $NUWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"Do you have parking?","answer":"Yes, free visitor parking is available behind the building, 8am to 8pm."}'

// Node.js 18+. Uses top-level await: save as .mjs (or set "type": "module").
const res = await fetch("https://ai.nuway.co/api/v1/external/knowledge/faqs/{id}", {
  method: "PUT",
  headers: {
    "X-API-KEY": process.env.NUWAY_API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "question": "Do you have parking?",
    "answer": "Yes, free visitor parking is available behind the building, 8am to 8pm."
  })
});
const data = await res.json();

import os
import requests
r = requests.put(
    "https://ai.nuway.co/api/v1/external/knowledge/faqs/{id}",
    headers={"X-API-KEY": os.environ["NUWAY_API_KEY"]},
    json={
      "question": "Do you have parking?",
      "answer": "Yes, free visitor parking is available behind the building, 8am to 8pm."
    },
    timeout=30,
)
r.raise_for_status()
data = r.json()

Errors 404 when the FAQ doesn't exist or isn't yours.

Delete knowledge

DELETE /api/v1/external/knowledge/{id}

Delete an FAQ or document. The AI stops using it immediately.

Path parameters

Name	Description
`id` string required	The item id, from List knowledge.

Example request

curl -X DELETE "https://ai.nuway.co/api/v1/external/knowledge/{id}" \
  -H "X-API-KEY: $NUWAY_API_KEY"

// Node.js 18+. Uses top-level await: save as .mjs (or set "type": "module").
const res = await fetch("https://ai.nuway.co/api/v1/external/knowledge/{id}", {
  method: "DELETE",
  headers: {
    "X-API-KEY": process.env.NUWAY_API_KEY
  }
});
const data = await res.json();

import os
import requests
r = requests.delete(
    "https://ai.nuway.co/api/v1/external/knowledge/{id}",
    headers={"X-API-KEY": os.environ["NUWAY_API_KEY"]},
    timeout=30,
)
r.raise_for_status()
data = r.json()

Response

{ "id": "c094a01a-a4f7-4319-8fdf-c3291d572a7b", "deleted": true }