Kita Applications API

openapi: 3.2.0
info:
  title: Kita AI Underwriter Applications API
  version: v1
  summary: Create loan applications, upload borrower documents, and retrieve a deterministic credit picture and cited credit memo.
  description: 'The Kita AI Underwriter API turns borrower documents into a decision-ready credit file.

    Create an application, push documents, and poll for extraction, the deterministic credit

    picture (spread, adjustments, policy decision), and a cited credit memo.


    Authentication uses an organization API key prefixed `kita_uw_`, sent as either

    `Authorization: ApiKey <key>` or `Authorization: Bearer <key>`. Two scopes are enforced

    per endpoint: `read` for GET endpoints and `write` for mutations.


    Errors return `{ "message": "..." }` with a standard HTTP status. `POST /intake` is

    idempotent on `external_ref`.


    NOTE: Kita does not publish a machine-readable OpenAPI description. This document was

    generated by the API Evangelist enrichment pipeline from Kita''s own published API

    reference (https://www.kita.ai/documentation and the API.md in

    Kita-Technologies/kita-api-examples). Only operations, parameters, fields, and status

    codes that Kita documents are represented here.

    '
  contact:
    name: Kita Support
    email: support@kita.ai
    url: https://www.kita.ai/documentation
  x-source:
  - https://www.kita.ai/documentation
  - https://github.com/Kita-Technologies/kita-api-examples/blob/main/API.md
  x-generated-by: api-evangelist-enrichment-pipeline
  x-generated: '2026-07-19'
servers:
- url: https://underwriter.kita.ai/api/v1
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: Applications
  description: Loan application records.
paths:
  /intake:
    post:
      tags:
      - Applications
      operationId: intakeApplication
      summary: Create an application and upload documents in one call
      description: 'One-call create plus document upload. Send `multipart/form-data` with an `application`

        field carrying the JSON metadata plus repeated `file`/`files` parts, or

        `application/json` for metadata only. Pass `external_ref` for idempotency — a retried

        push returns the existing application with `"idempotent": true` and HTTP 200 instead

        of creating a duplicate.

        '
      x-scope: write
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                application:
                  type: string
                  description: JSON-encoded application metadata.
                file:
                  type: string
                  format: binary
                files:
                  type: array
                  items:
                    type: string
                    format: binary
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationCreate'
      responses:
        '201':
          description: Application created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationEnvelope'
        '200':
          description: Idempotent replay — the existing application for this `external_ref`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationEnvelope'
              example:
                data:
                  id: 3f1c9b6e-6b3a-4a1c-9e1f-2f8c1d5a7b90
                  app_id: APP-1234
                  status: awaiting_docs
                  idempotent: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          description: Application created but document upload failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /applications:
    post:
      tags:
      - Applications
      operationId: createApplication
      summary: Create an application
      description: Create application metadata only. Documents are uploaded separately.
      x-scope: write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationCreate'
            example:
              business_name: Rivera Auto Repair LLC
              borrower_email: owner@riveraauto.example
              loan_type: sba_7a
              loan_amount: 150000
              borrower_phone: '+15125550142'
              application_context: Use of proceeds
              send_outreach: false
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationEnvelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    get:
      tags:
      - Applications
      operationId: listApplications
      summary: List applications
      description: List applications for the calling organization, with offset pagination.
      x-scope: read
      parameters:
      - name: status
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ApplicationStatus'
      - name: limit
        in: query
        required: false
        description: Page size. Default 50, clamped to 1–200.
        schema:
          type: integer
          default: 50
          minimum: 1
          maximum: 200
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          minimum: 0
      responses:
        '200':
          description: A page of applications.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Application'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
              example:
                data: []
                pagination:
                  total: 137
                  limit: 25
                  offset: 0
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /applications/{id}:
    parameters:
    - $ref: '#/components/parameters/ApplicationId'
    get:
      tags:
      - Applications
      operationId: getApplication
      summary: Get an application
      description: Fetch a single application by UUID or human `app_id`. Includes `document_count`.
      x-scope: read
      responses:
        '200':
          description: The application.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Applications
      operationId: updateApplication
      summary: Update an application
      description: Update mutable fields — business_name, loan_type, loan_amount, application_context, status.
      x-scope: write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationUpdate'
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationEnvelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Applications
      operationId: deleteApplication
      summary: Delete an application
      description: Permanently deletes the application, its documents and storage, and the borrower if orphaned.
      x-scope: write
      responses:
        '200':
          description: Deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    BadRequest:
      description: Malformed body, missing fields, or bad parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found in this organization.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Valid key lacks the required scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing, malformed, unknown, or revoked API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        message:
          type: string
          description: Human-readable description of the error.
      required:
      - message
    ApplicationCreate:
      type: object
      required:
      - business_name
      - borrower_email
      - loan_type
      - loan_amount
      properties:
        business_name:
          type: string
          description: Legal business name.
        borrower_email:
          type: string
          format: email
        loan_type:
          type: string
          description: Must match an org loan product
          e.g. `sba_7a`.: null
        loan_amount:
          type: number
          exclusiveMinimum: 0
        borrower_phone:
          type: string
        application_context:
          type: string
          description: Loan purpose or free-text context.
        external_ref:
          type: string
          description: Unique loan/record ID. Enables idempotent intake.
        send_outreach:
          type: boolean
          default: false
          description: Email the borrower for missing documents.
    ApplicationStatus:
      type: string
      enum:
      - submitted
      - awaiting_docs
      - underwriting
      - question_raised
      - memo_drafted
      - approved
      - declined
    Application:
      type: object
      properties:
        id:
          type: string
          format: uuid
        app_id:
          type: string
          examples:
          - APP-1234
        status:
          $ref: '#/components/schemas/ApplicationStatus'
        file_completeness:
          type: number
        document_count:
          type: integer
        idempotent:
          type: boolean
          description: Present and true on an idempotent intake replay.
    ApplicationEnvelope:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Application'
    Pagination:
      type: object
      properties:
        total:
          type: integer
        limit:
          type: integer
        offset:
          type: integer
    ApplicationUpdate:
      type: object
      properties:
        business_name:
          type: string
        loan_type:
          type: string
        loan_amount:
          type: number
        application_context:
          type: string
        status:
          $ref: '#/components/schemas/ApplicationStatus'
  parameters:
    ApplicationId:
      name: id
      in: path
      required: true
      description: Application UUID or human `app_id` (e.g. `APP-1234`).
      schema:
        type: string
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: 'Organization API key prefixed `kita_uw_`, minted in Settings → API keys and shown once.

        Kita stores only SHA-256 hashes. Both `Authorization: ApiKey <key>` and

        `Authorization: Bearer <key>` are accepted. Keys carry `read` and/or `write` scope;

        a key missing the required scope receives 403.

        '