Public API · v1

Knowentra API Referansı

Public v1 yüzeyinin endpoint, parametre, yetki, pagination, request/response ve hata sözleşmesi. Örnek kimlikler sentetiktir; kurulu sürümünüzün route sözleşmesi her zaman son teknik kaynaktır.

İlk isteği gönder Rehberleri incele

Base path

/api/v1

Authentication

X-API-Key

Content

application/json

Upload

multipart/form-data

Kimlik ve kapsam

Anahtarı header'da taşıyın

API anahtarını query string'e, URL'ye veya istemci loguna koymayın. Anahtarı secret manager'dan okuyup her istekte X-API-Key header'ı ile gönderin.

Workspace anahtarı yalnız bağlı workspace'i hedefleyebilir. Personal anahtar, workspace allowPersonalApiKeys politikasını kapattıysa 403 alır.

Read endpoint'leri read; deployment, yükleme, güncelleme ve silme işlemleri write yetkisi ister. Kaynak bulunamadı ve erişim reddedildi durumları bazı endpoint'lerde kaynak varlığını gizlemek için aynı 404 yanıtını kullanır.

GET workflows

curl --get "https://knowentra.example/api/v1/workflows" \
  --header "X-API-Key: $KNOWENTRA_API_KEY" \
  --data-urlencode "workspaceId=ws_demo" \
  --data-urlencode "deployedOnly=true" \
  --data-urlencode "limit=25"

Listeleme sözleşmesi

İki pagination modeli

Opaque cursor

Workflow, execution log ve audit listelerinde response içindeki nextCursor değerini değiştirmeden sonraki isteğe verin. Cursor'ın içeriğine güvenmeyin veya kendiniz üretmeyin.

?limit=50&cursor=eyJzb3J0T3JkZXIiOjF9

Limit + offset

Knowledge document ve table row listeleri limit/offset kullanır. Liste değişirken sayfa kayması oluşabileceği için uzun taramalarda sabit filtre ve sıralama kullanın.

?limit=50&offset=100

Endpoint group

Workflow

Workflow envanteri ve deployment yaşam döngüsü. Listeleme cursor tabanlıdır.

GET

/api/v1/workflows

Arşivlenmemiş workflow'ları listeler.

read

Girdi: query: workspaceId*, folderId?, deployedOnly=false, limit=50 (1–100), cursor?
Başarılı çıktı: data[], nextCursor?, limits

GET

/api/v1/workflows/{id}

Aktif workflow metadatasını, değişkenleri ve input tanımlarını getirir.

read

Girdi: path: id*
Başarılı çıktı: data{ workflow }, limits

POST

/api/v1/workflows/{id}/deploy

Yeni deployment sürümü oluşturup workflow'u yayınlar.

write

Girdi: json optional: name*, description?
Başarılı çıktı: data{ id, isDeployed, deployedAt, version?, warnings[] }, limits

DELETE

/api/v1/workflows/{id}/deploy

Workflow'u yayından kaldırır; tanımı silmez.

write

Girdi: path: id*
Başarılı çıktı: data{ id, isDeployed:false, deployedAt:null, warnings[] }, limits

POST

/api/v1/workflows/{id}/rollback

Belirtilen veya bir önceki deployment sürümünü etkinleştirir.

write

Girdi: json optional: version? (positive integer)
Başarılı çıktı: data{ id, isDeployed, deployedAt, version, warnings[] }, limits

Endpoint group

Knowledge

Bilgi tabanı, belge ingestion ve yetkili semantik/etiket araması.

GET

/api/v1/knowledge

Workspace içindeki bilgi tabanlarını listeler.

read

Girdi: query: workspaceId*
Başarılı çıktı: success, data{ knowledgeBases[], totalCount }

POST

/api/v1/knowledge

Sunucunun embedding modeliyle yeni bilgi tabanı oluşturur.

write

Girdi: json: workspaceId*, name* (≤255), description? (≤1000), chunkingConfig?
Başarılı çıktı: success, data{ knowledgeBase, message }

GET

/api/v1/knowledge/{id}

Bilgi tabanı ayrıntısını getirir.

read

Girdi: path: id* · query: workspaceId*
Başarılı çıktı: success, data{ knowledgeBase }

PUT

/api/v1/knowledge/{id}

Ad, açıklama veya chunking ayarlarını kısmi günceller.

write

Girdi: json: workspaceId* + one of name?, description?, chunkingConfig?
Başarılı çıktı: success, data{ knowledgeBase, message }

DELETE

/api/v1/knowledge/{id}

Bilgi tabanını yetki ve workspace kapsamında siler.

write

Girdi: path: id* · query: workspaceId*
Başarılı çıktı: success, data{ message }

GET

/api/v1/knowledge/{id}/documents

Belgeleri offset tabanlı olarak listeler.

read

Girdi: query: workspaceId*, limit=50 (1–100), offset=0, search?, enabledFilter=all|enabled|disabled, sortBy?, sortOrder=desc|asc
Başarılı çıktı: success, data{ documents[], pagination }

POST

/api/v1/knowledge/{id}/documents

Belgeyi multipart olarak yükler ve işleme kuyruğuna alır.

write

Girdi: multipart: workspaceId*, file*
Başarılı çıktı: success, data{ document, message }

GET

/api/v1/knowledge/{id}/documents/{documentId}

Tek belge ve işleme durumunu getirir.

read

Girdi: path: id*, documentId* · query: workspaceId*
Başarılı çıktı: success, data{ document }

DELETE

/api/v1/knowledge/{id}/documents/{documentId}

Belgeyi ve ilişkili arama verisini kaldırır.

write

Girdi: path: id*, documentId* · query: workspaceId*
Başarılı çıktı: success, data{ message }

POST

/api/v1/knowledge/search

En fazla 20 bilgi tabanında query ve/veya etiket filtresiyle arar.

read

Girdi: json: workspaceId*, knowledgeBaseIds*, query?, topK=10 (1–100), tagFilters? · query or tagFilters required
Başarılı çıktı: success, data{ results[], query, knowledgeBaseIds[], topK, totalResults }

Endpoint group

Tables

Şemalı tablolar, kolonlar ve tekil/toplu satır işlemleri.

GET

/api/v1/tables

Workspace tablolarını listeler.

read

Girdi: query: workspaceId*
Başarılı çıktı: success, data{ tables[] }

POST

/api/v1/tables

En az bir kolonlu tablo oluşturur.

write

Girdi: json: workspaceId*, name*, description?, schema{ columns[{ name, type, required?, unique? }] }
Başarılı çıktı: success, data{ table }

GET

/api/v1/tables/{tableId}

Tabloyu şemasıyla birlikte getirir.

read

Girdi: path: tableId* · query: workspaceId*
Başarılı çıktı: success, data{ table }

DELETE

/api/v1/tables/{tableId}

Tabloyu workspace kapsamında siler.

write

Girdi: path: tableId* · query: workspaceId*
Başarılı çıktı: success, data{ deleted }

POST

/api/v1/tables/{tableId}/columns

Kolonu belirtilen konuma ekler.

write

Girdi: json: workspaceId*, column{ name*, type*, required?, unique?, position? }
Başarılı çıktı: success, data{ table }

PATCH

/api/v1/tables/{tableId}/columns

Kolon adını veya özelliklerini günceller.

write

Girdi: json: workspaceId*, columnName*, updates{ name?, type?, required?, unique? }
Başarılı çıktı: success, data{ table }

DELETE

/api/v1/tables/{tableId}/columns

Kolonu adıyla siler.

write

Girdi: json: workspaceId*, columnName*
Başarılı çıktı: success, data{ table }

GET

/api/v1/tables/{tableId}/rows

Satırları filtre, sıralama ve offset ile listeler.

read

Girdi: query: workspaceId*, filter? (JSON), sort? (JSON), limit?, offset?, includeTotal=true
Başarılı çıktı: success, data{ rows[], pagination }

POST

/api/v1/tables/{tableId}/rows

Tek satır veya rows dizisiyle toplu satır ekler.

write

Girdi: json single: workspaceId*, data*, afterRowId? | beforeRowId? · batch: workspaceId*, rows[]
Başarılı çıktı: success, data{ row | rows[] }

PUT

/api/v1/tables/{tableId}/rows

Boş olmayan filtreyle eşleşen satırları toplu günceller.

write

Girdi: json: workspaceId*, filter*, data*, limit?
Başarılı çıktı: success, data{ updatedCount }

DELETE

/api/v1/tables/{tableId}/rows

Filtre veya rowIds ile sınırlı toplu silme yapar.

write

Girdi: json: workspaceId*, exactly one of filter* or rowIds*, limit?
Başarılı çıktı: success, data{ deletedCount }

GET

/api/v1/tables/{tableId}/rows/{rowId}

Tek satırı getirir.

read

Girdi: path: tableId*, rowId* · query: workspaceId*
Başarılı çıktı: success, data{ row }

PATCH

/api/v1/tables/{tableId}/rows/{rowId}

Tek satır verisini günceller.

write

Girdi: json: workspaceId*, data*
Başarılı çıktı: success, data{ row }

DELETE

/api/v1/tables/{tableId}/rows/{rowId}

Tek satırı siler.

write

Girdi: path: tableId*, rowId* · query: workspaceId*
Başarılı çıktı: success, data{ deleted }

POST

/api/v1/tables/{tableId}/rows/upsert

Unique kolon üzerinden tekrar çalıştırılabilir insert/update yapar.

write

Girdi: json: workspaceId*, data*, conflictTarget?
Başarılı çıktı: success, data{ row, created }

Endpoint group

Files

Workflow dosyalarının listelenmesi, yüklenmesi, indirilmesi ve silinmesi.

GET

/api/v1/files

Workspace dosyalarını listeler.

read

Girdi: query: workspaceId*
Başarılı çıktı: success, data{ files[], totalCount }

POST

/api/v1/files

En fazla 100 MB dosya yükler.

write

Girdi: multipart: workspaceId*, file*
Başarılı çıktı: success, data{ file, message }

GET

/api/v1/files/{fileId}

Dosyayı binary gövde olarak indirir.

read

Girdi: path: fileId* · query: workspaceId*
Başarılı çıktı: binary + Content-Type/Content-Disposition

DELETE

/api/v1/files/{fileId}

Dosyayı workspace kapsamında siler.

write

Girdi: path: fileId* · query: workspaceId*
Başarılı çıktı: success, data{ message }

Endpoint group

Logs & Audit

Workflow çalıştırma izleri ile organizasyon kapsamlı audit olayları.

GET

/api/v1/logs

Çalıştırma loglarını filtreleyip cursor ile sayfalar.

read

Girdi: query: workspaceId*, workflowIds?, folderIds?, triggers?, level=info|error?, startDate?, endDate?, executionId?, duration/cost/model filters?, details=basic|full, includeTraceSpans=false, includeFinalOutput=false, limit=100 (≤1000), cursor?, order=desc|asc
Başarılı çıktı: data[], nextCursor?, limits

GET

/api/v1/logs/{id}

Tek log kaydının ayrıntısını getirir.

read

Girdi: path: id*
Başarılı çıktı: data{ log }, limits

GET

/api/v1/logs/executions/{executionId}

Bir execution'a ait ilişkili iz kayıtlarını getirir.

read

Girdi: path: executionId*
Başarılı çıktı: data{ execution, logs[] }, limits

GET

/api/v1/audit-logs

Enterprise organizasyon audit olaylarını listeler; org admin/owner gerekir.

org admin

Girdi: query: action?, resourceType?, resourceId?, workspaceId?, actorId?, startDate?, endDate?, includeDeparted=false, limit=50 (1–100), cursor?
Başarılı çıktı: data[], nextCursor?, limits

GET

/api/v1/audit-logs/{id}

Organizasyon kapsamındaki tek audit olayını getirir.

org admin

Girdi: path: id*
Başarılı çıktı: data{ auditLog }, limits

POST

/api/v1/copilot/chat

Kaldırılmış eski endpoint; tüm çağrılara 410 Gone döner.

kaldırıldı

Girdi: do not use
Başarılı çıktı: 410 { success:false, error }

Uçtan uca örnekler

Gerçek sözleşmeye uygun çağrılar

GET workflows · request

curl --get "https://knowentra.example/api/v1/workflows" \
  --header "X-API-Key: $KNOWENTRA_API_KEY" \
  --data-urlencode "workspaceId=ws_demo" \
  --data-urlencode "deployedOnly=true" \
  --data-urlencode "limit=25"

200 · response

{
  "data": [
    {
      "id": "wf_invoice_review",
      "name": "Invoice review",
      "workspaceId": "ws_demo",
      "isDeployed": true,
      "deployedAt": "2026-07-30T09:15:00.000Z",
      "runCount": 184,
      "lastRunAt": "2026-07-31T06:40:12.000Z",
      "createdAt": "2026-06-08T10:00:00.000Z",
      "updatedAt": "2026-07-30T09:15:00.000Z"
    }
  ],
  "nextCursor": "eyJzb3J0T3JkZXIiOjF9",
  "limits": { "...": "plan and usage metadata" }
}

POST knowledge/search · request

curl "https://knowentra.example/api/v1/knowledge/search" \
  --header "X-API-Key: $KNOWENTRA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "workspaceId": "ws_demo",
    "knowledgeBaseIds": ["kb_policies"],
    "query": "Expense approval limit",
    "topK": 5,
    "tagFilters": [
      { "tagName": "Status", "operator": "eq", "value": "active" }
    ]
  }'

200 · response

{
  "success": true,
  "data": {
    "results": [
      {
        "documentId": "doc_expense_policy",
        "documentName": "Expense Policy.pdf",
        "sourceUrl": null,
        "content": "Manager approval is required...",
        "chunkIndex": 7,
        "metadata": { "Status": "active" },
        "similarity": 0.89
      }
    ],
    "query": "Expense approval limit",
    "knowledgeBaseIds": ["kb_policies"],
    "topK": 5,
    "totalResults": 1
  }
}

POST table row upsert

curl "https://knowentra.example/api/v1/tables/tbl_suppliers/rows/upsert" \
  --header "X-API-Key: $KNOWENTRA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "workspaceId": "ws_demo",
    "conflictTarget": "supplier_code",
    "data": {
      "supplier_code": "SUP-1042",
      "risk_level": "medium",
      "reviewed": false
    }
  }'

POST multipart file upload

curl "https://knowentra.example/api/v1/files" \
  --header "X-API-Key: $KNOWENTRA_API_KEY" \
  --form "workspaceId=ws_demo" \
  --form "file=@./quarterly-report.pdf"

Chunking sınırları

Knowledge create/update için maxSize 100–4000, minSize 1–2000 ve overlap 0–500 aralığındadır. Varsayılan değerler sırasıyla 1024, 100 ve 200'dür. Embedding modeli ve boyutu public request'ten seçilmez; sunucu yapılandırmasından gelir.

Hata ve retry

Durum kodunu ve response gövdesini birlikte okuyun

400

Invalid parameter/body, malformed JSON, invalid filter or deployment state

401

Missing or invalid API key; authentication/rate-limit check failure

402

Usage limit blocks a metered operation such as semantic search

403

Workspace scope, personal-key policy, role, or permission denial

404

Resource missing or intentionally hidden because access is denied

409

Conflict such as a duplicate workspace filename

410

Removed endpoint; currently /api/v1/copilot/chat

413

Upload body or file exceeds the accepted size limit

415

Knowledge document media type is not supported

423

Workflow locked by a conflicting mutable operation

429

API rate limit exceeded; honor Retry-After

500

Unexpected server-side failure

400 · validation error

{
  "error": "Invalid parameters",
  "details": [
    {
      "path": ["query", "workspaceId"],
      "message": "workspaceId query parameter is required"
    }
  ]
}

429 · rate limit

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-07-31T10:01:00.000Z
Retry-After: 42

{
  "error": "Rate limit exceeded",
  "message": "API rate limit exceeded. Please retry after ...",
  "retryAfter": 1785488460000
}

Retry edin

429 ve geçici 5xx yanıtlarında Retry-After varsa uygulayın; yoksa jitter içeren exponential backoff kullanın.

Kör retry yapmayın

400, 401, 403, 404, 410 ve 413 çoğunlukla istek, kimlik veya ürün durumu değişmeden düzelmez.

Yazmaları koruyun

Upsert gibi tekrar çalıştırılabilir endpoint'leri tercih edin. Deploy veya toplu yazma retry'ından önce sonucu GET ile doğrulayın.

Public API ile iç servis köprüsünü ayırın

Agent katmanının connector kataloğunu keşfetmek ve izinli operasyon çalıştırmak için kullandığı iç tools köprüsü public v1 anahtar yüzeyinin parçası değildir. /tools/catalog, /integrations ve /tools/execute yollarını public client entegrasyonu gibi belgelemeyin veya doğrudan açmayın.

Admin v1 route'ları da ayrı bir yönetim sözleşmesi ve admin kimlik doğrulaması kullanır. Public automation anahtarlarına admin route erişimi vermeyin.