Workflows

Create Workflow

Minimal: product_code + name. Opsional: prompt, reference docs, output format, webhook.

curl -X POST https://api.platform.kakak.ai/v1/workflows \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_code":"doc-01","name":"My Evaluator","output_format":"json"}'

Schema Inference

Upload contoh output — AI akan infer JSON Schema secara otomatis:

curl -X POST https://api.platform.kakak.ai/v1/workflows \
  -d '{"product_code":"doc-01","name":"...","output_schema_sample_id":"doc_sampleXYZ"}'

Schema difinalisasi saat workflow dibuat. Runs tidak pernah re-infer.

Output JSON Schema

Alternatif ke schema inference: tulis output_schema langsung sebagai JSON Schema (bersarang, boleh object/array/string/number/boolean di semua level):

curl -X POST https://api.platform.kakak.ai/v1/workflows \
  -d '{
    "product_code": "doc-01",
    "name": "...",
    "output_schema": {
      "type": "object",
      "required": ["output"],
      "properties": {
        "output": {
          "type": "object",
          "required": ["ringkasan", "detail_table"],
          "properties": {
            "ringkasan": { "type": "string" },
            "detail_table": {
              "type": "array",
              "items": {
                "type": "object",
                "required": ["item", "status"],
                "properties": {
                  "item": { "type": "string" },
                  "status": { "type": "string" }
                }
              }
            }
          }
        }
      }
    }
  }'

Bagaimana schema diterapkan

Schema disisipkan sebagai instruksi ke model saat run dijalankan, dan hasilnya divalidasi ulang di server setelah model merespons — validasi bekerja di setiap level nested (bukan cuma top-level), termasuk isi setiap elemen array. Ini berlaku sama di mode sync maupun async.

Percobaan perbaikan otomatis (repair pass)

Jika hasil pertama tidak lolos validasi, server otomatis meminta model memperbaiki output-nya satu kali (dokumen input dan instruksi asli tetap dikirim utuh — bukan diganti dengan prompt perbaikan) sebelum menyerah. Mode sync dibatasi 1x percobaan perbaikan (total 2 percobaan) mengikuti batas waktu; mode async mendapat 2x percobaan perbaikan (total 3 percobaan).

schema_validation_failed

Bila setelah percobaan perbaikan hasil tetap tidak sesuai output_schema, run berakhir dengan status: "failed" dan error.code: "schema_validation_failed" — kredit yang sudah direservasi untuk run tersebut dikembalikan penuh. Ini lebih baik daripada run succeeded dengan struktur output yang sebenarnya tidak sesuai kontrak yang Anda minta.

Melihat output sebuah run

Portal → menu Runs → klik ID run → kartu Output menampilkan output_json lengkap beserta status, token usage, dan kredit terpakai. Lewat API: GET /v1/runs/{run_id} pada field output (untuk run succeeded) atau error (untuk run failed).

Run sandbox (test-mode key kk_test_*, atau centang Sandbox di Playground portal) tidak pernah memanggil model — outputnya adalah stub bertanda [TEST] yang mengikuti seluruh struktur output_schema (termasuk satu elemen contoh untuk tiap array), bukan hasil evaluasi dokumen sungguhan. Gunakan sandbox untuk memvalidasi integrasi tanpa memotong kredit.

Endpoints

Delete: hanya workflow tanpa runs. Yang punya runs → archive dulu (PATCH status=archived).

Output Formats

json, markdown, docx, xlsx, csv. JSON/Markdown dikembalikan inline. DOCX/XLSX/CSV disimpan sebagai file — download via GET /runs/:id/output.