Referensi API NextPDF Connect

Sekilas

Halaman ini merupakan referensi tingkat simbol untuk server NextPDF Connect (nextpdf/server). Halaman ini mencantumkan setiap tool berdasarkan nama tool yang terdaftar dan kelas implementasinya, serta mendokumentasikan layanan gRPC NextPDFConnect, termasuk metode Remote Procedure Call (RPC) beserta pesan permintaan dan responsnya. Halaman ini juga mendefinisikan kontrak autentikasi, error, dan batas laju yang digunakan bersama di semua transport.

Server mengekspos satu registri tool melalui tiga transport: Model Context Protocol (MCP) di atas standard input dan standard output, Application Programming Interface (API) berbasis Representational State Transfer (REST), dan gRPC. Setiap transport mendokumentasikan detail wire masing-masing pada halaman terpisah: lihat MCP transport, REST transport, dan gRPC transport. Halaman ini mengatalogkan simbol-simbol yang dibawa oleh transport tersebut.

Nama tool, kelas, dan tingkat risiko dibaca dari implementasi tool di src/Tools/. Jumlah tool yang diekspos oleh sebuah deployment merupakan properti runtime; lihat Tool catalog. Boot and discovery menjelaskan cara penentuan tingkat.

Ketersediaan transport

Sebuah tool tersedia melalui setiap transport yang dijalankan oleh deployment. Transport berjalan sebagai proses independen; menjalankan satu transport tidak otomatis menjalankan transport yang lain.

Transport	Titik masuk	Format wire	Autentikasi
MCP	`bin/nextpdf-mcp`	JavaScript Object Notation Remote Procedure Call (JSON-RPC) 2.0 di atas stdio	Batasan proses sistem operasi (tanpa kunci API)
REST	`bin/nextpdf-server`	HTTP, OpenAPI 3.1	Kunci API Bearer pada header `Authorization` permintaan
gRPC	`bin/nextpdf-grpc`	Protocol Buffers, paket `nextpdf.connect.v1`	Token Bearer pada metadata panggilan `authorization` gRPC

Melalui MCP, Anda memanggil tool dengan tools/call dan nama tool yang terdaftar. Melalui REST dan gRPC, Anda mengakses kapabilitas engine yang sama melalui permukaan render, operation, dan capability; lihat tabel rute REST transport dan tabel RPC gRPC transport.

Autentikasi dan tingkat risiko

Autentikasi kunci API

Transport REST dan gRPC mewajibkan kunci API Bearer pada setiap permintaan, kecuali probe kesehatan yang tidak terautentikasi. Kunci berbentuk npk_live_{kid}_{secret}: kid adalah identifier delapan karakter untuk mencari record, sedangkan bagian secret membawa entropinya. Server hanya menyimpan digest SHA-256 dari kunci dan membandingkan token yang diberikan dalam waktu konstan, sehingga kunci yang tidak valid tidak mengungkapkan apa pun melalui timing. REST membaca token dari header Authorization: Bearer …; gRPC membaca token yang sama dari metadata panggilan authorization. Transport MCP berbasis stdio tidak memiliki kunci API karena berjalan sebagai subproses lokal yang dipercaya oleh klien yang meluncurkannya. Security and operations mendokumentasikan model autentikasi secara lengkap.

Empat tingkat risiko

Setiap tool mendeklarasikan salah satu dari empat tingkat risiko terurut, yang didefinisikan oleh enum RiskLevel di src/Config/RiskLevel.php.

tingkat	Kasus enum	Nilai	Efek
Safe	`RiskLevel::Safe`	0	Hanya-baca, tanpa efek samping. Dieksekusi otomatis.
Caution	`RiskLevel::Caution`	1	Membuat atau mengubah state dalam memori. Dieksekusi otomatis, dicatat dalam audit.
Review	`RiskLevel::Review`	2	Menghasilkan keluaran yang dapat disalahgunakan. Dieksekusi otomatis, dicatat dalam audit.
ApprovalRequired	`RiskLevel::ApprovalRequired`	3	Bersifat destruktif, legal, atau kritis terhadap privasi. Memerlukan konfirmasi manusia.

Risiko efektif sebuah tool hanya ditentukan oleh dua sumber: deklarasi riskLevel() milik tool itu sendiri, dan penggantian (override) konfigurasi operator opsional yang hanya boleh menaikkan risiko, tidak pernah menurunkan tool ApprovalRequired. Lihat HITL risk tiers dan Configuration.

Bagaimana token persetujuan mengalir

Saat Anda memanggil tool ApprovalRequired tanpa token yang valid, ConfirmationGate (src/Mcp/ConfirmationGate.php) mengembalikan token tantangan sekali pakai alih-alih menjalankan tool tersebut. Agen meneruskan tantangan itu kepada manusia, lalu memanggil ulang tool yang sama dengan token yang diterbitkan pada argumen _confirmation_token. Token tersebut mengikat nama tool, sebuah nonce acak, dan time-to-live (TTL) 300 detik. Token ini tidak mengikat argumen dan bukan merupakan kredensial autentikasi. Pada REST, kunci API Bearer tetap mengautentikasi permintaan, dan gate yang sama berjalan di executor tool bersama sebelum operasi yang di-gate. Pada gRPC, gate yang sama berjalan sebelum dispatch operasi. Mekanisme tantangan dan token identik di seluruh transport.

Tool dan endpoint

Tabel ini mendokumentasikan setiap tool berdasarkan nama tool yang terdaftar (kolom Symbol) dan kelas implementasinya. Tool dikelompokkan berdasarkan tingkat dan kategori. Semua kelas Abstract Syntax Tree (AST) dan mutation berada di bawah src/Tools/Ast dan src/Tools/Ast/Mutation; kelas extraction berada di bawah src/Tools/Extraction; kelas lainnya berada di bawah src/Tools/Core.

Tool dokumen inti

Symbol	Parameter	Perilaku standar	Mengembalikan	Memunculkan exception atau gagal karena	Catatan
`create_pdf`	`page_size` (standar `A4`), `orientation` (`portrait`/`landscape`), `title`, `author`; tidak ada yang wajib.	Membuat dokumen satu halaman dalam memori; menetapkan metadata bila disediakan.	JSON berisi `document_id`, `page_count`, `page_size`, `orientation`.	Mengembalikan hasil error berisi pesan engine bila gagal.	Kelas `CreatePdfTool`. Risiko `RiskLevel::Caution`. Tingkat core. Nilai `document_id` yang dikembalikan menjadi masukan untuk setiap operasi berikutnya.
`add_page`	`document_id` (wajib), ukuran halaman dan orientasi opsional.	Menambahkan satu halaman ke dokumen.	JSON berisi jumlah halaman terbaru.	Hasil error jika `document_id` tidak dikenal.	Kelas `AddPageTool`. Risiko `RiskLevel::Caution`. Tingkat core.
`add_text`	`document_id` (wajib), `text` (wajib), posisi dan gaya opsional.	Menambahkan teks ke dokumen.	Ringkasan status dokumen dalam JSON.	Hasil error jika `document_id` tidak dikenal.	Kelas `AddTextTool`. Risiko `RiskLevel::Caution`. Tingkat core.
`add_image`	`document_id` (wajib), `source` (wajib: path berkas atau base64), penempatan opsional.	Menambahkan gambar dari path berkas atau data base64.	Ringkasan status dokumen dalam JSON.	Hasil error jika sumber tidak dapat dibaca atau `document_id` tidak dikenal.	Kelas `AddImageTool`. Risiko `RiskLevel::Caution`. Tingkat core.
`add_table`	`document_id` (wajib), `html` (wajib).	Merender tabel Hypertext Markup Language (HTML) ke dalam dokumen.	Ringkasan status dokumen dalam JSON.	Hasil error jika markup tidak valid atau `document_id` tidak dikenal.	Kelas `AddTableTool`. Risiko `RiskLevel::Caution`. Tingkat core.
`set_font`	`document_id` (wajib), `family` (wajib), ukuran dan gaya opsional.	Menetapkan huruf untuk operasi teks berikutnya.	Konfirmasi JSON tentang huruf yang aktif.	Hasil error jika huruf atau `document_id` tidak dikenal.	Kelas `SetFontTool`. Risiko `RiskLevel::Caution`. Tingkat core.
`output_pdf`	`document_id` (wajib), `file_path` (opsional), `destroy` (standar `true`).	Memfinalisasi dokumen; menulis ke `file_path`, atau mengembalikan base64 bila dihilangkan; secara standar menghancurkan dokumen.	JSON berisi `file_path` dan `file_size`, atau `base64` dan `file_size`.	Hasil error jika `document_id` tidak dikenal; kegagalan path containment saat menulis di luar direktori basis.	Kelas `OutputPdfTool`. Risiko `RiskLevel::ApprovalRequired`. Tingkat core. Penulisan berkas melewati gate konfirmasi; mode base64 tidak.
`preview_layout`	`document_id` (wajib).	Mengembalikan ringkasan tata letak tanpa merender PDF final.	Ringkasan tata letak dalam JSON.	Hasil error jika `document_id` tidak dikenal.	Kelas `PreviewLayoutTool`. Risiko `RiskLevel::Safe`. Tingkat core.
`parse_pdf`	`document_id` (wajib).	Memeriksa metadata struktural: jumlah halaman, huruf, gambar, enkripsi, dan Info Dictionary.	Metadata struktural dalam JSON.	Hasil error jika dokumen cacat.	Kelas `ParsePdfTool`. Risiko `RiskLevel::Safe`. Tingkat core. Hanya terdaftar saat `NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED` bernilai `true` atau `1`.

Tool diagnostik inti

Symbol	Parameter	Perilaku standar	Mengembalikan	Memunculkan exception atau gagal karena	Catatan
`diagnostic.doctor`	tidak ada.	Menjalankan pemeriksaan kesehatan dan mengembalikan diagnostik lingkungan terstruktur.	Laporan lingkungan dalam JSON.	Hasil error jika pemeriksaan internal gagal.	Kelas `DiagnosticDoctorTool`. Risiko `RiskLevel::Safe`. Tingkat core. Tidak memerlukan dokumen dan tidak memerlukan konfirmasi.
`diagnostic.capabilities`	tidak ada.	Mencantumkan kapabilitas beserta informasi tingkat dan status.	Daftar kapabilitas dalam JSON.	Hasil error jika terjadi kegagalan internal.	Kelas `DiagnosticCapabilitiesTool`. Risiko `RiskLevel::Safe`. Tingkat core.
`diagnostic.inspect`	`document_id` (wajib).	Memeriksa PDF dan mengembalikan metadata struktural.	Metadata struktural dalam JSON.	Hasil error jika `document_id` tidak dikenal.	Kelas `DiagnosticInspectTool`. Risiko `RiskLevel::Safe`. Tingkat core.
`diagnostic.verify`	`document_id` (wajib), profil PDF/A atau PDF/UA opsional.	Memverifikasi integritas struktural; secara opsional memvalidasi PDF/A atau PDF/UA dengan menjalankan subproses VeraPDF.	Laporan verifikasi dalam JSON.	Hasil error jika subproses gagal, timeout, atau masukan terlalu besar.	Kelas `DiagnosticVerifyTool`. Risiko `RiskLevel::Caution`. Tingkat core. Masukan dibatasi maksimum 50 mebibyte (MiB).

Tool barcode inti

Symbol	Parameter	Perilaku standar	Mengembalikan	Memunculkan exception atau gagal karena	Catatan
`generate_barcode`	`payload` (wajib), `format` (misalnya QR Code, DataMatrix).	Menghasilkan matriks modul barcode dua dimensi untuk payload.	Matriks modul dalam JSON.	Hasil error jika `format` tidak didukung atau payload tidak valid.	Kelas `BarcodeTool`. Risiko `RiskLevel::Caution`. Tingkat core. `BarcodeTool` hanya terdaftar saat registri encoder inti `barcode` tersedia dalam `nextpdf/core` yang terpasang; nama tool yang terdaftar adalah `generate_barcode`.

Tool privasi Enterprise

Tool ini membungkus kelas privasi Enterprise dan hanya terdaftar pada tingkat Enterprise saat kelas-kelas tersebut dapat di-autoload. Tool ini beroperasi pada konten teks biasa.

Symbol	Parameter	Perilaku standar	Mengembalikan	Memunculkan exception atau gagal karena	Catatan
`redact_pdf`	`content` (wajib), opsi deteksi opsional.	Secara destruktif meredaksi informasi yang dapat mengidentifikasi pribadi (PII) dalam konten teks biasa menggunakan engine redaksi Enterprise.	JSON berisi konten yang telah diredaksi dan hash SHA-256.	Hasil error jika kelas Enterprise tidak ada atau deteksi gagal.	Kelas `RedactPdfTool`. Risiko `RiskLevel::Review`. Tingkat enterprise.
`deidentify_pdf`	`content` (wajib), `strategy` (redact atau suppress).	Menerapkan strategi de-identifikasi sistematis pada konten teks biasa menggunakan de-identifier Enterprise.	JSON berisi konten hasil de-identifikasi.	Hasil error jika kelas Enterprise tidak ada.	Kelas `DeIdentifyPdfTool`. Risiko `RiskLevel::Review`. Tingkat enterprise.
`zone_redact_pdf`	`content` (wajib), `zones` (halaman beserta daftar persegi panjang ternormalisasi).	Menerapkan redaksi zona berbasis koordinat menggunakan engine redaksi Enterprise.	JSON berisi konten yang telah diredaksi.	Hasil error jika zona tidak valid atau kelas Enterprise tidak ada.	Kelas `ZoneRedactionTool`. Risiko `RiskLevel::Review`. Tingkat enterprise.

Tool baca abstract syntax tree (AST)

Tool ini disertakan bersama server, terdaftar pada tingkat Pro, dan di-gate oleh NEXTPDF_AST_TOOLS_ENABLED (diaktifkan secara standar). Tool ini bersifat hanya-baca.

Symbol	Parameter	Perilaku standar	Mengembalikan	Memunculkan exception atau gagal karena	Catatan
`get_document_ast`	`pdf_data` (wajib).	Membangun AST semantik: pohon node lengkap dengan jangkar sitasi untuk setiap elemen struktural.	Pohon node dalam JSON beserta sebuah ETag untuk kontrol konkurensi.	Hasil error jika dokumen cacat.	Kelas `GetDocumentAstTool`. Risiko `RiskLevel::Safe`. Tingkat pro.
`get_ast_node`	`pdf_data` (wajib), `node_id` (wajib).	Mengambil satu node AST beserta seluruh anaknya.	Node beserta anaknya dalam JSON.	Hasil error jika `node_id` tidak dikenal.	Kelas `GetAstNodeTool`. Risiko `RiskLevel::Safe`. Tingkat pro.
`get_ast_diff`	`original_pdf_data` (wajib), `modified_pdf_data` (wajib).	Membandingkan dua dokumen secara struktural melalui AST semantiknya.	Node yang ditambahkan, dihapus, dan diubah dalam JSON.	Hasil error jika dokumen masukan cacat.	Kelas `GetAstDiffTool`. Risiko `RiskLevel::Safe`. Tingkat pro.
`search_ast_nodes`	`pdf_data` (wajib), filter tipe, indeks halaman, dan teks opsional.	Mencari node AST berdasarkan tipe, indeks halaman, atau konten teks.	Daftar node datar yang cocok beserta anak dangkalnya dalam JSON.	Hasil error jika dokumen cacat.	Kelas `SearchAstNodesTool`. Risiko `RiskLevel::Safe`. Tingkat pro.
`extract_cited_text`	`pdf_data` (wajib), `headings_only` opsional.	Mengekstrak blok teks dengan jangkar sitasi (halaman, kotak pembatas, tingkat keyakinan).	Blok teks tersitasi dalam JSON.	Hasil error jika dokumen cacat.	Kelas `ExtractCitedTextTool`. Risiko `RiskLevel::Safe`. Tingkat pro. Kategori `ast`.
`extract_cited_tables`	`pdf_data` (wajib).	Mengekstrak blok tabel dengan jangkar sitasi; mengembalikan matriks sel berurutan per baris (row-major) per node Table.	Matriks tabel beserta jangkar dalam JSON.	Hasil error jika dokumen cacat.	Kelas `ExtractCitedTablesTool`. Risiko `RiskLevel::Safe`. Tingkat pro. Kategori `extraction`.

Tool mutasi AST

Tool ini disertakan bersama server, terdaftar pada tingkat Pro, dan di-gate oleh NEXTPDF_MUTATION_TOOLS_ENABLED (diaktifkan secara standar). Keempatnya adalah ApprovalRequired dan menggunakan optimistic concurrency control (OCC) melalui sebuah ETag.

Symbol	Parameter	Perilaku standar	Mengembalikan	Memunculkan exception atau gagal karena	Catatan
`apply_ast_mutations`	`pdf_data`, `etag`, `idempotency_key`, `mutations` (semua wajib).	Menerapkan sekumpulan mutasi secara atomik; memutar ulang hasil yang di-cache untuk `idempotency_key` yang berulang.	JSON berisi PDF yang telah dimutasi dan sebuah ETag baru.	Konflik OCC saat ETag basi; error validasi jika mutasi cacat.	Kelas `ApplyAstMutationsTool`. Risiko `RiskLevel::ApprovalRequired`. Tingkat pro.
`delete_ast_node`	`pdf_data`, `node_id`, `etag` (semua wajib).	Menghapus node dalam mode overlay (konten asli ditutupi, tidak dihapus secara fisik).	JSON berisi PDF yang telah dimodifikasi dan sebuah ETag baru.	Konflik OCC saat ETag basi; error jika `node_id` tidak dikenal.	Kelas `DeleteAstNodeTool`. Risiko `RiskLevel::ApprovalRequired`. Tingkat pro.
`insert_ast_node`	`pdf_data`, `parent_node_id`, `position`, `etag`, `node` (semua wajib).	Menyisipkan node baru sebagai anak dari induk pada posisi yang ditentukan.	JSON berisi PDF yang telah dimodifikasi dan sebuah ETag baru.	Konflik OCC saat ETag basi; error validasi jika node cacat.	Kelas `InsertAstNodeTool`. Risiko `RiskLevel::ApprovalRequired`. Tingkat pro.
`update_ast_node`	`pdf_data`, `node_id`, `etag`, `updates` (semua wajib).	Memperbarui konten teks node.	JSON berisi PDF yang telah dimodifikasi dan sebuah ETag baru.	Konflik OCC saat ETag basi; error jika `node_id` tidak dikenal.	Kelas `UpdateAstNodeTool`. Risiko `RiskLevel::ApprovalRequired`. Tingkat pro.

Skema permintaan dan respons

Transport gRPC mendefinisikan skema bertipe milik server dalam paket Protocol Buffers nextpdf.connect.v1, di proto/nextpdf/connect/v1/*.proto. Layanan dan pesan-pesannya merupakan simbol skema kanonis.

Layanan `NextPDFConnect`

Layanan NextPDFConnect mengekspos RPC unary dan server-streaming. Simbol skema adalah nama metode RPC serta pesan permintaan dan respons yang dibawanya.

RPC	Pesan permintaan	Pesan respons	Bentuk
`Render`	`RenderRequest`	`RenderResponse`	Unary. Render stateless sinkron.
`RenderStream`	`RenderRequest`	`RenderChunk` (stream)	Server-streaming. Render dikirimkan sebagai potongan (chunk) terurut.
`SubmitJob`	`SubmitJobRequest`	`JobResponse`	Unary. Mengirimkan job render asinkron.
`GetJobStatus`	`GetJobStatusRequest`	`JobResponse`	Unary. Memantau status job.
`GetJobResult`	`GetJobResultRequest`	`RenderResponse`	Unary. Mengunduh hasil yang telah selesai.
`GetJobResultStream`	`GetJobResultRequest`	`RenderChunk` (stream)	Server-streaming. Mengunduh hasil yang telah selesai sebagai potongan (chunk).
`CancelJob`	`CancelJobRequest`	`JobResponse`	Unary. Membatalkan atau menghapus job.
`CreateSession`	`CreateSessionRequest`	`SessionResponse`	Unary. Membuat sesi pembangunan dokumen.
`GetSession`	`GetSessionRequest`	`SessionResponse`	Unary. Mengambil metadata sesi.
`DestroySession`	`DestroySessionRequest`	`DestroySessionResponse`	Unary. Menghancurkan sesi beserta dokumennya.
`SessionOperation`	`SessionOperationRequest`	`SessionResponse`	Unary. Mengeksekusi operasi pada dokumen sesi.
`SessionRender`	`SessionRenderRequest`	`RenderResponse`	Unary. Merender dokumen sesi menjadi PDF.
`SessionRenderStream`	`SessionRenderRequest`	`RenderChunk` (stream)	Server-streaming. Merender dokumen sesi sebagai potongan (chunk).
`ExecuteCapability`	`CapabilityRequest`	`CapabilityResponse`	Unary. Mengeksekusi operasi capability yang di-gate per tingkat.
`GetCapabilities`	`GetCapabilitiesRequest`	`GetCapabilitiesResponse`	Unary. Mendaftar kapabilitas untuk klien yang terautentikasi.
`HealthCheck`	`HealthCheckRequest`	`HealthCheckResponse`	Unary. Probe liveness.
`ReadinessCheck`	`ReadinessCheckRequest`	`ReadinessCheckResponse`	Unary. Probe readiness.

Simbol pesan

Pesan permintaan dan respons adalah simbol struktural skema. Pesan render, RenderRequest, RenderResponse, dan RenderChunk yang streaming, membawa ukuran halaman, orientasi, operasi terurut, dan byte PDF yang dihasilkan. Pesan job, SubmitJobRequest, GetJobStatusRequest, GetJobResultRequest, CancelJobRequest, dan JobResponse, memodelkan siklus hidup job asinkron, dengan metadata job disimpan dalam pesan JobData. Pesan sesi, CreateSessionRequest, SessionResponse, GetSessionRequest, DestroySessionRequest, DestroySessionResponse, SessionOperationRequest, dan SessionRenderRequest, memodelkan siklus hidup sesi berstate, dengan metadata sesi disimpan dalam pesan SessionData. Pesan capability, CapabilityRequest, CapabilityResponse, GetCapabilitiesRequest, dan GetCapabilitiesResponse, membawa dispatch operasi yang di-gate per tingkat serta introspeksi. Pesan sistem, HealthCheckRequest, HealthCheckResponse, ReadinessCheckRequest, dan ReadinessCheckResponse, membawa status liveness dan readiness.

Berkas .proto yang disertakan adalah kontrak wire resmi; lihat referensi transport gRPC di gRPC transport.

Model error

Server melaporkan kegagalan dengan mekanisme error native setiap transport. Setiap transport mempertahankan kondisi logis yang sama; hanya pengkodeannya yang berbeda.

MCP

Error MCP adalah objek error JSON-RPC 2.0. Metode yang tidak dikenal mengembalikan method-not-found (-32601); pesan yang bukan JSON-RPC valid mengembalikan invalid-request (-32600); masukan yang tidak dapat diurai mengembalikan parse-error (-32700). Tool yang gagal mengembalikan respons JSON-RPC sukses dengan konten yang menandai error tersebut, alih-alih error di tingkat transport, sehingga agen dapat membaca pesannya. Tantangan konfirmasi untuk tool ApprovalRequired juga merupakan respons yang sukses, bukan error.

REST

REST menggunakan kode status Hypertext Transfer Protocol (HTTP) dengan semantik yang didefinisikan oleh RFC 9110. Status 200 membawa hasil; 400 dikembalikan saat sebuah field permintaan gagal validasi format; 401 dikembalikan saat tidak ada kunci API valid yang diberikan dan membawa header tantangan WWW-Authenticate: Bearer; 403 dikembalikan saat tingkat kunci valid tidak berhak atas operasi tersebut; 404 dikembalikan saat rute yang di-gate per tingkat tidak terdaftar karena paketnya tidak ada. Body error yang dapat dibaca mesin adalah dokumen Problem Details sesuai RFC 9457, disajikan dengan media type application/problem+json dan Uniform Resource Identifier (URI) type yang stabil untuk setiap kondisi. Kegagalan validasi pada tingkat field dicantumkan dalam body. Sebagai langkah pengerasan terhadap path-traversal, document_id yang tidak cocok dengan pola doc_[a-f0-9]{24} ditolak dengan 400 sebelum tool dijalankan. REST transport mendokumentasikan pipeline middleware REST dan tabel rute.

gRPC

gRPC menggunakan kode status gRPC standar. Token yang hilang, cacat, tidak dikenal, dinonaktifkan, atau kedaluwarsa menggagalkan panggilan dengan UNAUTHENTICATED alih-alih status HTTP. Detail error yang kaya mencerminkan bentuk Problem Details REST dan dibawa dalam detail status gRPC, sehingga URI type dari error tersebut konsisten di seluruh transport.

Lihat juga RFC 9110 (HTTP Semantics) untuk semantik kode status dan RFC 9457 (Problem Details for HTTP APIs) untuk format body error.

RFC 9110: https://www.rfc-editor.org/rfc/rfc9110
RFC 9457: https://www.rfc-editor.org/rfc/rfc9457

Batas laju dan kuota

Transport REST menerapkan pembatasan laju per-alamat-Internet-Protocol (per-IP) dan per-klien dalam pipeline middleware-nya, ditambah batas ukuran body dan payload per tingkat serta timeout per permintaan. Plafon ini adalah nilai konfigurasi, bukan konstanta yang di-hard-code:

Plafon payload per tingkat (corePayloadLimit, proPayloadLimit, enterprisePayloadLimit) dan timeout yang sesuai berlaku pada REST sesuai tingkat kunci yang terautentikasi. Lihat Configuration.
Penyimpanan dokumen dalam memori dibatasi oleh max_documents (standar 50) dan document_ttl (standar 1800 detik).
State batas laju dan idempotensi bersifat per-worker kecuali NEXTPDF_REDIS_HOST dikonfigurasi untuk penyimpanan bersama. Lihat Deployment.

Saat penyimpanan batas laju dan idempotensi digunakan bersama, pengiriman job asinkron identik yang berulang akan dideduplikasi oleh idempotency_key. Transport MCP menangani satu permintaan dalam satu waktu melalui pipa dan mendeduplikasi id permintaan yang berulang dari buffer 64-entri alih-alih menerapkan batas laju jaringan.

Catatan pengembangan

Baca nama tool, kelas, dan tingkat risiko dari sumber di bawah src/Tools/; jangan mengasumsikan total yang tetap. Kueri server yang sedang berjalan untuk memperoleh hitungan otoritatif, sebagaimana ditunjukkan pada Tool catalog.
Regenerasi stub klien gRPC dari berkas proto/nextpdf/connect/v1/*.proto yang disertakan; paket dan namespace-nya adalah nextpdf.connect.v1. Jangan menyunting secara manual kelas pesan yang dibangkitkan.
Tool ApprovalRequired menjawab dengan tantangan konfirmasi pada panggilan pertama. Bangun jalur retry: teruskan tantangan, lalu panggil ulang dengan _confirmation_token sebelum Anda merilis integrasi yang menggerakkan output_pdf atau tool mutasi apa pun.
Rute atau capability yang di-gate per tingkat tetapi tidak terpasang bukanlah kegagalan autentikasi: REST mengembalikan 404 untuk rute yang tidak ada, dan ExecuteCapability gRPC melaporkan operasi tersebut sebagai tidak tersedia. Perlakukan tingkat Pro atau Enterprise yang tidak ada sebagai operasi yang diharapkan, bukan kesalahan.
Jauhkan kunci API dari kontrol sumber; mount kunci dari berkas secret dan utamakan penyimpanan kunci berbasis berkas yang melakukan hot-reload sehingga rotasi tidak memerlukan restart. Lihat Security and operations.

Lihat juga

Developer guide — arsitektur, siklus hidup, titik ekstensi, dan daftar periksa pengujian
Tool catalog — kumpulan tool core terverifikasi dan hitungan runtime
HITL risk tiers — model risiko dan tantangan konfirmasi
MCP transport · REST transport · gRPC transport — detail wire per-transport
Security and operations — autentikasi, keamanan transport, dan model ancaman