Folders & Schemas

Folders group documents (e.g. by applicant). Schemas define custom extraction shapes that override the default output.

Folders

Custom Extraction Schemas

Authentication and identifiers

Use Authorization: Bearer $KITA_API_KEY. Reads require document:read; folder creation and schema mutations require document:write. Use the id from create/list responses. Folder IDs are UUIDs, not numeric document IDs. Validate the format client-side: malformed folder IDs currently return 500; an unknown, well-formed UUID returns 404.

Create and use a folder

curl -X POST "https://api.kita.ai/api/v1/folders" \
  -H "Authorization: Bearer $KITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Loan 44821","source":"los","source_id":"44821"}'

name is required (1–100 characters). Optional: color, source, source_id, source_url. With both source and source_id, repeated creation returns the existing folder and updates its name and any supplied color/source URL.

A new folder returns 201 with { "folder": { "id": "…" }, "created": true }; an existing one returns 200 with created: false (folder fields abbreviated). GET /api/v1/folders returns { "folders": [...] } and accepts a source filter. GET /api/v1/folders/{id}/documents returns { "documents": [...] } with id, fileName, documentType, status, uploadedAt, and completedAt per file.

Define a custom extraction schema

curl -X POST "https://api.kita.ai/api/v1/schemas" \
  -H "Authorization: Bearer $KITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document_type": "loan_summary",
    "display_name": "Loan summary",
    "schema_definition": {
      "sections": {
        "summary": {
          "type": "object",
          "fields": { "borrower_name": { "type": "string" } }
        }
      }
    }
  }'

Required: document_type (must match ^[a-z][a-z0-9_]{2,99}$), non-empty display_name, and schema_definition. Optional: description, category. schema_definition.sections is an object of named sections. Each section has type object or array; define object fields in fields, or array item fields in item_schema. Field types are string, number, integer, currency, date, boolean, array, or object. A slug matching a built-in document type creates an additive override.

Creation returns 201 with { "schema": { ... } }. List returns { "schemas": [...] }; get and update return { "schema": { ... } }. Use the schema ID for get/update/delete and document_type when uploading documents.

PUT /api/v1/schemas/{id} accepts any of display_name, description, category, and schema_definition; omitted fields are preserved. A supplied schema replaces the definition and increments its version. The type slug is not editable. DELETE deactivates the schema and returns 200 with success: true and a deleted object containing id and document_type.

Invalid definitions return 400 INVALID_SCHEMA; an active duplicate type returns 409 DUPLICATE_SCHEMA. Missing/inactive schemas return 404 SCHEMA_NOT_FOUND. An ineligible plan returns 403; reaching 20 active schemas returns 400 SCHEMA_LIMIT_REACHED.