API Documentation
Build on noeud.ai. Upload documents, extract knowledge graphs, and query technical documentation through a simple REST API.
📖 Overview
The noeud.ai API is organized around REST. All requests use JSON except file uploads (multipart/form-data). Base URL:
Base URL
https://noeud.ai/api/v1/
Key Concepts
- Assets — Equipment you document (machines, aircraft, vehicles)
- Documents — Technical PDFs uploaded or found by Corpus Builder
- Knowledge Units (KUs) — Structured facts extracted from documents with source and confidence
- Knowledge Graph (KG) — Interconnected graph of all KUs, entities, and relationships
- Corpus Builder — Finds relevant PDFs on the web automatically (44 queries per angle)
- RAG Chat — Answers questions using your KG with source citations
🚀 Quickstart — 5 Minutes
Step 1: Get your API key
Go to Account → API Access and copy your key.
Step 2: Upload a document
cURLPythonJavaScriptGoPHPRuby
curl -X POST https://noeud.ai/api/v1/documents/upload \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@manual.pdf" \
-F "domain=cnc_machining"
import requests
resp = requests.post(
"https://noeud.ai/api/v1/documents/upload",
headers={"Authorization": "Bearer YOUR_API_KEY"},
files={"file": open("manual.pdf", "rb")},
data={"domain": "cnc_machining"}
)
print(resp.json())
const form = new FormData();
form.append("file", fs.createReadStream("manual.pdf"));
form.append("domain", "cnc_machining");
const resp = await fetch("https://noeud.ai/api/v1/documents/upload", {
method: "POST", headers: { "Authorization": `Bearer ${KEY}` }, body: form
});
file, _ := os.Open("manual.pdf")
body := &bytes.Buffer{}
writer := multipart.NewWriter(body)
part, _ := writer.CreateFormFile("file", "manual.pdf")
io.Copy(part, file)
writer.WriteField("domain", "cnc_machining")
writer.Close()
req, _ := http.NewRequest("POST", "https://noeud.ai/api/v1/documents/upload", body)
$ch = curl_init("https://noeud.ai/api/v1/documents/upload");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ["Authorization: Bearer $key"],
CURLOPT_POSTFIELDS => ["file" => new CURLFile("manual.pdf"), "domain" => "cnc_machining"],
]);
uri = URI.parse("https://noeud.ai/api/v1/documents/upload")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{key}"
form = [["file", File.open("manual.pdf")], ["domain", "cnc_machining"]]
req.set_form(form, "multipart/form-data")
Step 3: Ask a question
cURLPython
curl -X POST https://noeud.ai/api/v1/chat \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"question": "What causes Fanuc alarm SV0401?"}'
resp = requests.post("https://noeud.ai/api/v1/chat",
headers={"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"},
json={"question": "What causes Fanuc alarm SV0401?"})
data = resp.json()
print(data["answer"])
for c in data["citations"]: print(f" {c['source']} p.{c['page']}")
That's it — document uploaded, question answered with citations, in two API calls.
🔐 Authentication
Include your API key in the Authorization header:
Header
Authorization: Bearer noeud_sk_YOUR_API_KEY
Key Format
Production: noeud_sk_{id}_live_{random} · Sandbox: noeud_sk_{id}_test_{random}
Key Scopes
| Scope | Access | Use Case |
|---|---|---|
| read | Query KG, list assets/docs, chat | Client apps |
| write | Upload docs, create assets, start jobs | Backend |
| admin | Full access including delete | Internal only |
⚠️ Keep your API key secret. Never expose in client-side code or public repos. Rotate immediately if compromised. Up to 3 active keys for zero-downtime rotation.
⏱️ Rate Limits
| Plan | Requests/Hour | RAG/Day | Upload Size | Concurrent Jobs |
|---|---|---|---|---|
| Discovery | 60 | 20 | 10 MB | 1 |
| Pro | 500 | 500 | 50 MB | 5 |
| Enterprise | 5,000 | Unlimited | 200 MB | 20 |
Response Headers
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 487
X-RateLimit-Reset: 1710523200
❌ Error Handling
| Code | Meaning |
|---|---|
| 200 | Success |
| 201 | Created |
| 400 | Bad request |
| 401 | Unauthorized |
| 403 | Forbidden (scope) |
| 404 | Not found |
| 429 | Rate limited |
| 500 | Server error |
Error Body
{"error": {"type": "invalid_request", "message": "File must be PDF", "code": "invalid_file_type", "request_id": "req_a1b2c3"}}
📄 Pagination
Request
GET /api/v1/documents?limit=20&offset=40&sort=created_at&order=desc
Response
{"data": [...], "pagination": {"total": 158, "limit": 20, "offset": 40, "has_more": true}}
🏷️ Versioning
Version in URL path (/api/v1/). Breaking changes increment version. Previous versions maintained 12 months. Pin with header: X-API-Version: 2026-03-15
🔄 Idempotency
For POST requests, include Idempotency-Key header to safely retry without duplicates. Keys valid 24 hours.
Header
Idempotency-Key: idem_a1b2c3d4-e5f6
📄 Documents
POST/api/v1/documents/upload
Upload a technical document for knowledge extraction. Supports PDF, DOCX, XLSX, images, CSV, TXT.
| Parameter | Type | Description | |
|---|---|---|---|
| file | binary | Required | Document file (multipart/form-data) |
| domain | string | Optional | cnc_machining, aviation, automotive, medical_devices, electronics, robotics, energy, marine, agriculture, construction, telecom, railway, military, injection_molding, photography, heavy_trucks |
| asset_id | string | Optional | Associate with specific asset |
| scope | string | Optional | transversal, model, or specific |
| tags | array | Optional | Custom tags: ["maintenance","urgent"] |
200 OK
{"document_id": "doc_8f3a2b1c", "filename": "fanuc_manual.pdf", "size_bytes": 4521984, "pages": 847, "status": "uploaded", "domain": "cnc_machining", "created_at": "2026-03-15T14:30:00Z"}
GET/api/v1/documents
List all documents. Supports pagination, filtering by status/domain/asset, and search by filename.
| Query Param | Type | Description | |
|---|---|---|---|
| status | string | Optional | uploaded, processing, processed, failed |
| domain | string | Optional | Filter by domain |
| search | string | Optional | Search by filename |
| created_after | ISO date | Optional | Filter by date |
GET/api/v1/documents/{document_id}
Get document details including extraction status, KU count, grounding/coverage scores.
200 OK
{"document_id": "doc_8f3a2b1c", "filename": "fanuc_manual.pdf", "pages": 847, "status": "processed", "ku_count": 1247,
"extraction": {"preset": "optimal", "duration_seconds": 342, "grounding_score": 0.91, "coverage_score": 0.87}}
GET/api/v1/documents/{document_id}/download
Download the original file. Returns binary with Content-Type header.
DELETE/api/v1/documents/{document_id}
Delete a document and its KUs. Irreversible.
⚠️ Deleting a document removes all extracted KUs. This may affect RAG answers that relied on this document.
POST/api/v1/documents/batch NEW
Upload up to 20 documents in one request. Returns batch job ID.
| Parameter | Type | Description | |
|---|---|---|---|
| files | binary[] | Required | Up to 20 files |
| auto_extract | boolean | Optional | Auto-start KG extraction (default: false) |
💬 RAG Chat
POST/api/v1/chat
Ask a question against your Knowledge Graph. Returns grounded answer with source citations.
| Parameter | Type | Description | |
|---|---|---|---|
| question | string | Required | Technical question (max 2000 chars) |
| asset_id | string | Optional | Scope to specific asset |
| session_id | string | Optional | Continue conversation |
| max_sources | integer | Optional | Max citations (1-10, default: 5) |
| language | string | Optional | en, fr, de (default: auto) |
200 OK
{
"answer": "Alarm SV0401 (VRDY OFF) on Z-axis indicates servo amplifier not receiving ready signal. Most common cause: loose CN1B connector...",
"citations": [{"source": "fanuc_maintenance.pdf", "page": 312, "text": "Check CN1B connector...", "confidence": 0.94, "ku_id": "ku_f7e8d9"}],
"session_id": "sess_x7k2", "model": "claude-sonnet-4-20250514",
"search_time_ms": 42, "llm_time_ms": 1847, "total_time_ms": 1889, "n_sources": 2,
"usage": {"rag_queries_today": 48, "rag_queries_limit": 500}
}
💡 Include equipment context in your question for best results: manufacturer, model, subsystem.
POST/api/v1/chat/stream NEW
Streaming version. Returns Server-Sent Events (SSE) for real-time token output.
Python
resp = requests.post("https://noeud.ai/api/v1/chat/stream",
headers={"Authorization": f"Bearer {KEY}"},
json={"question": "What causes alarm SV0401?"}, stream=True)
for line in resp.iter_lines():
if line: print(line.decode(), end="", flush=True)
GET/api/v1/chat/sessions
List all chat sessions with message counts and timestamps.
POST/api/v1/chat/feedback
Rate an answer quality (1-5 stars) to improve future responses.
| Parameter | Type | Description | |
|---|---|---|---|
| session_id | string | Required | Session to rate |
| rating | integer | Required | 1-5 stars |
| comment | string | Optional | Free-text feedback |
🔧 Assets
GET/api/v1/assets
List all equipment assets.
200 OK
{"data": [{"id": "asset_f01a", "vendor": "Fanuc", "model": "0i-TF", "entity_type": "CNC Lathe", "callsign": "LATHE-07", "serial_number": "E04637281", "domain": "cnc_machining", "subsystems": [{"name": "Spindle"}, {"name": "Z-Axis Servo"}], "ku_count": 4580}]}
POST/api/v1/assets
Create a new asset manually.
| Parameter | Type | Description | |
|---|---|---|---|
| vendor | string | Required | Manufacturer name |
| model | string | Required | Model name |
| domain | string | Required | Technical domain |
| callsign | string | Optional | Field identifier |
| serial_number | string | Optional | Serial number |
POST/api/v1/assets/scan-nameplate NEW
Upload nameplate photo. Claude Vision extracts manufacturer, model, serial, year automatically.
| Parameter | Type | Description | |
|---|---|---|---|
| image | binary | Required | JPEG, PNG, HEIC (max 10MB) |
| auto_create | boolean | Optional | Auto-create asset (default: false) |
200 OK
{"vendor": "Fanuc", "model": "0i-TF", "serial": "E04637281", "year": "2019", "entity_type": "CNC Lathe", "confidence": 0.97}
PUT/api/v1/assets/{asset_id}
Update asset details (callsign, serial, subsystems).
DELETE/api/v1/assets/{asset_id}
Delete an asset. Requires password confirmation via
X-Confirm-Password header.🧠 Knowledge Graph
POST/api/v1/kg/extract
Start KG extraction. Multi-pass pipeline transforms PDFs into structured Knowledge Units.
| Parameter | Type | Description | |
|---|---|---|---|
| preset | string | Optional | economy (Sonnet+mini, ~$30) · optimal (Sonnet+GPT-4.1, ~$60) · max_quality (Opus+Sonnet, ~$250) |
| document_ids | array | Optional | Specific docs only |
| webhook_url | string | Optional | Notify on completion |
GET/api/v1/kg/jobs/{job_id}
Get extraction job progress (percent, phase, KUs extracted so far).
POST/api/v1/kg/query
Query the Knowledge Graph directly (without LLM). Returns matching Knowledge Units ranked by relevance.
| Parameter | Type | Description | |
|---|---|---|---|
| query | string | Required | Search query |
| limit | integer | Optional | Max results (default: 10) |
| min_confidence | float | Optional | Min score threshold (0-1) |
GET/api/v1/kg/stats
KG statistics: total KUs, entities, relations, domains, avg confidence.
GET/api/v1/kg/export NEW
Export KG in JSON, CSV, RDF/Turtle, or Neo4j Cypher format.
| Parameter | Type | Description | |
|---|---|---|---|
| format | string | Optional | json, csv, rdf, neo4j (default: json) |
| min_confidence | float | Optional | Filter by confidence (0-1) |
GET/api/v1/kg/entities
List all extracted entities (manufacturers, models, parameters, alarm codes, etc.).
🚀 Corpus Builder
POST/api/v1/corpus/build
Start automated documentation search. 44 queries per angle, finds and ranks PDFs.
| Parameter | Type | Description | |
|---|---|---|---|
| asset_ids | array | Required | Assets to document |
| angle | string | Optional | maintenance, operation, training, parts, all |
| max_pdfs | integer | Optional | Max PDFs (default: 80) |
| min_trust | float | Optional | Min trust score (0-1) |
GET/api/v1/corpus/jobs/{job_id}
Job progress: queries done, candidates found, PDFs downloaded, trust avg, ETA.
GET/api/v1/corpus/stats
Corpus statistics: total PDFs, internal docs, domains covered.
🎥 Vision Monitoring BETA
GET/api/v1/vision/cameras
List connected cameras and status.
200 OK
{"cameras": [{"id": "cam_hmi_01", "name": "Lathe 07 HMI", "status": "streaming", "resolution": "1920x1080", "anomaly_count_24h": 2, "uptime_24h": 99.8}]}
WSwss://noeud.ai/api/v1/vision/feed/{camera_id}
WebSocket for real-time camera feed with AI analysis. Receive frames and anomaly events.
JavaScript
const ws = new WebSocket(`wss://noeud.ai/api/v1/vision/feed/cam_01?token=${KEY}`);
ws.onmessage = (e) => {
const d = JSON.parse(e.data);
if (d.type === "anomaly") {
// d.alarm, d.kg_context, d.recommended_action
}
};
GET/api/v1/vision/alerts
List recent anomaly alerts across all cameras. Includes KG context and recommended procedures.
🔔 Webhooks
POST/api/v1/webhooks
Register a webhook endpoint for real-time event notifications.
| Parameter | Type | Description | |
|---|---|---|---|
| url | string | Required | HTTPS endpoint |
| events | array | Required | Events to subscribe |
| secret | string | Optional | Signing secret |
Event Types
| Event | Description |
|---|---|
| corpus.completed | Corpus Builder finished |
| corpus.failed | Corpus Builder failed |
| kg.completed | KG extraction finished |
| document.processed | Document processing done |
| vision.anomaly | Camera detected anomaly |
| vision.alarm | Critical alarm on HMI |
Payload Verification
Verify X-Noeud-Signature header with HMAC-SHA256:
Python
import hmac, hashlib
expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
valid = hmac.compare_digest(expected, signature)
👤 Account
GET/api/v1/account
Get account info, plan, usage limits.
GET/api/v1/account/usage
Current billing period usage.
{"plan": "pro", "assets": 8, "documents": 193, "knowledge_units": 35606, "rag_queries_today": 47, "rag_queries_limit": 500}
GET/api/v1/account/api-keys
List active API keys (up to 3). Create and revoke keys for zero-downtime rotation.
🏥 Health
GET/api/v1/health
System health. No authentication required.
{"status": "operational", "services": {"api": "up", "redis": "up", "worker": "up"}, "version": "1.2.0", "uptime_24h": 99.98}
Full status page: noeud.ai/portal/health
📦 SDKs & Tools
Python SDK STABLE
Install
pip install noeud-ai
Usage
from noeud import NoeudClient
client = NoeudClient(api_key="noeud_sk_...")
# Upload
doc = client.documents.upload("manual.pdf", domain="cnc_machining")
# Ask
answer = client.chat.ask("What causes alarm SV0401?")
print(answer.text)
for c in answer.citations:
print(f" {c.source} p.{c.page}")
# Scan nameplate
scan = client.assets.scan_nameplate("photo.jpg")
# Corpus builder
job = client.corpus.build(asset_ids=["asset_01"], angle="all")
job.wait()
print(f"Found {job.result.pdfs_count} PDFs")
# Export KG
client.kg.export(format="json", output="kg.json")
Node.js SDK COMING SOON
Install
npm install @noeud-ai/sdk
CLI Tool STABLE
Usage
pip install noeud-cli
noeud config set api_key noeud_sk_...
noeud upload manual.pdf --domain cnc_machining
noeud ask "What causes alarm SV0401?"
noeud assets list
noeud scan photo.jpg --auto-create
noeud kg export --format json -o kg.json
Postman Collection
📋 Changelog
v1.2.0March 15, 2026
- ADDED Nameplate scanner with Claude Vision
- ADDED Streaming chat (SSE)
- ADDED KG export (JSON/CSV/RDF/Neo4j)
- ADDED Batch upload, Chat feedback, Webhooks
- CHANGED Pro rate limits increased
v1.1.0February 20, 2026
- ADDED Vision monitoring (beta)
- ADDED Multi-language RAG (EN/FR/DE)
- ADDED Document tagging
v1.0.0January 15, 2026
- ADDED Initial release: docs, KG, RAG, assets, corpus, Python SDK
🧪 Sandbox
Test without affecting production. Sandbox uses CNC demo KG (35,606 KUs).
Sandbox URL
https://noeud.ai/api/v1/sandbox/
Use test key (noeud_sk_*_test_*). Same API, isolated data, Discovery-tier limits.
🆘 Support
- Email: api-support@noeud.ai
- Portal Chat: Bottom-right corner of portal
- Video Call: Book 30-min consultation
- Response: Pro 4h · Enterprise 1h
Always include request_id from error responses when reporting issues.