Feed your assistant from your own system

Your own system (a website, a learning platform, a catalogue, a help desk or a CRM) can send one assistant its knowledge and keep it up to date by itself: files, web pages, YouTube videos and Q&As. Nobody uploads anything in Nexa.

1. Create a key for the assistant

Open the assistant, go to Knowledge, open Feed it from your own system and press Create a key for this assistant. Copy the key now: it is shown once, and it works for this assistant only. To be told when Nexa has finished reading what you sent, create the key in Settings → Developer with a webhook address instead.

In the examples, $NEXA_KEY is that key and $ASSISTANT is the assistant's id (the part after /assistants/ in its address).

2. Send a Q&A and a web page

curl -X POST "https://api.nexahubs.co/api/v1/public/assistants/$ASSISTANT/knowledge/batches" \
  -H "Authorization: Bearer $NEXA_KEY" \
  -H "Idempotency-Key: catalogue-2026-11-08-1" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "From our catalogue",
    "items": [
      {"kind": "text", "text_kind": "faq", "external_id": "faq-shipping",
       "title": "How long does shipping take?",
       "body": "1 to 2 business days in Cairo and Giza, 2 to 3 elsewhere."},
      {"kind": "url", "external_id": "page-returns", "url": "https://shop.example.com/returns"},
      {"kind": "youtube", "url": "https://www.youtube.com/watch?v=VIDEO_ID", "rights_confirmed": true}
    ]
  }'

Up to 50 items in one batch. The answer is the batch, with an id and one entry per item. Sending the same Idempotency-Key again returns the same batch instead of a copy.

3. See when it is ready

curl "https://api.nexahubs.co/api/v1/public/assistants/$ASSISTANT/knowledge/batches/$BATCH" \
  -H "Authorization: Bearer $NEXA_KEY"

Each item moves through queued, processing and indexing to ready (the assistant can find it in its answers) or failed (with a reason). Retry a failed item with POST …/items/$ITEM/retry; cancel one with POST …/items/$ITEM/cancel.

4. Send a file

Add the file to a batch with its name and size:

{"kind": "file", "external_id": "price-list", "filename": "price-list.pdf", "size": 482113, "content_type": "application/pdf"}

Its entry in the answer carries an upload object: PUT the file's bytes to its address (or each part, for a large file), then:

curl -X POST "https://api.nexahubs.co/api/v1/public/assistants/$ASSISTANT/knowledge/items/$ITEM/complete" \
  -H "Authorization: Bearer $NEXA_KEY"

5. Change or remove what you sent

Find it by your own id, then change it (a Q&A or an article) or remove it. For a file or a link, remove it and send the new one:

curl "https://api.nexahubs.co/api/v1/public/assistants/$ASSISTANT/knowledge/objects?external_id=faq-shipping" \
  -H "Authorization: Bearer $NEXA_KEY"

curl -X PATCH "https://api.nexahubs.co/api/v1/public/assistants/$ASSISTANT/knowledge/objects/$OBJECT" \
  -H "Authorization: Bearer $NEXA_KEY" -H "Content-Type: application/json" \
  -d '{"body": "Same day in Cairo, 1 to 3 business days elsewhere."}'

curl -X DELETE "https://api.nexahubs.co/api/v1/public/assistants/$ASSISTANT/knowledge/objects/$OBJECT" \
  -H "Authorization: Bearer $NEXA_KEY"

Good to know

• What a key sends waits under Knowledge for someone who may publish, unless that person pressed Turn on publishing directly for the key.
• Anything that looks like a password, personal data or instructions to the assistant waits for a person, with the reason, even when publishing directly is on.
• The webhook is called once per batch, when it is finished. Its body is signed: X-Nexa-Signature: t=<unix>,v1=<hex>, an HMAC-SHA256 over "<t>.<body>" with your signing secret. Refuse one older than 5 minutes; X-Nexa-Delivery stays the same on a retry.
• To stop a system, close its key in Settings → Developer: it stops working at once.