Tinvio Jots API

openapi: 3.2.0
info:
  title: Tinvio Com Jots API
  version: '1.0'
  contact:
    email: build.with@jaz.ai
    name: API Support
    url: https://jaz.ai
  description: 'Operations tagged Jots across 2 of this provider''s published API definitions: tinvio-com-openapi-original.yaml, tinvio-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.getjaz.com
tags:
- description: Write, search, and review agent judgment records (jots), with per-entry acknowledgments and review dispositions (flag, reject, or endorse).
  name: Jots
paths:
  /api/v1/jots:
    post:
      description: 'Write a batch of agent judgment records (jots). Entries are independent: the response carries one ack record per entry in input order, and a bad entry (invalid kind/tier, blank call) NEVER fails the batch, it comes back with error + errorCode while the rest persist. An entry''s idempotencyKey makes retries safe: a replay returns the existing row''s resourceId with replayed=true. duplicateCount is a dedupe hint (prior jots in the organization sharing the content fingerprint). Rate valve: 600 writes per organization per minute, beyond that the whole request is rejected with 429. Doctrine for consistent entries: log a judgment when you chose among real alternatives and a write followed, or when you deliberately decided not to write; skip mechanical actions; jot after the write succeeds and carry the written record''s resourceId in refs, with RELATION stating what the write did (SUBJECT only for no-write entries). Tier anchors mirror the server''s independent re-score (tier_norm): CRITICAL = money out (a PAY ref), data destroyed (DELETE), external send or period lock (FINALIZE), or a RECOVERY that still drove a write; HIGH = the withheld write (RECOVERY with no mutation ref) or RISK/MATCH backed by a write; LOW = a DEVIATION with no write; MEDIUM = the rest. kind NOTE is the server fallback for a missing kind, never declare it. confidence: HIGH = clear rule or precedent, MEDIUM = pattern inference, LOW = a guess a reviewer should check. workflowLabel: prefer a canonical job name (month-end-close, quarter-end-close, year-end-close, bank-recon, gst-vat-filing, payment-run, credit-control, supplier-recon, audit-prep, fa-review, document-collection, statutory-filing), else short kebab-case. Keep entries tight: one factual line per field, never repeat content across fields, and always give why: a call without a basis is half a record.'
      operationId: create-jot
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Create Jots
      tags:
      - Jots
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateJotsRequest'
        description: The jots to create.
        required: true
    servers:
    - url: https://api.getjaz.com
  /api/v1/jots/search:
    post:
      description: 'Search agent judgment records (jots) in the caller''s organization. Filters: entity ref (TYPE:resourceId containment), kind, tier, dispositionVerb, freetext (case-insensitive substring over call and why), createdFrom/createdTo (epoch ms, inclusive), firstParty (true = only entries from Jaz-operated agent surfaces, server-stamped origin; false = only the rest), and pinned (true = only pinned entries, the same predicate the pinned sort uses; false = only unpinned). Sort is pinned server-side (tierNorm=CRITICAL OR withheldWrite first, then createdAt DESC), no client sort. Set includeStats=true for per-credential disposition counts alongside the page. Organization scope is stamped from the API key.'
      operationId: search-jot
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageableResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Search Jots
      tags:
      - Jots
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchJotsRequest'
        description: Search filters, sort, and pagination.
        required: true
    servers:
    - url: https://api.getjaz.com
  /api/v1/jots/{resourceId}/disposition:
    post:
      description: 'Append a review disposition (FLAG / REJECT / ENDORSE) to a jot. Dispositions are append-only, they annotate, never mutate the jot. With verb=REJECT and rollback=true the rollback is coordinated asynchronously by the platform: this request returns the disposition immediately (a null or partial rollbackOutcome means the rollback is still in flight, or an exhausted-retry ref is awaiting a repeat REJECT to re-drive it), and the per-ref outcomes (RESTORED / UNSUPPORTED_TYPE / NO_PRIOR_VERSION / EDITED_SINCE / SKIPPED_RELATION / SKIPPED_CAP / FAILED) land on the jot as each ref completes, readable via jot search (recall). Partial results are permanent: refs restore independently and are never auto-reverted, so a partial outcome can leave coupled records (an invoice and its sibling journal) on different versions - when that happens: Some linked records were not restored. Review the affected books. A repeat REJECT replays the existing disposition; with rollback=true a completed outcome returns as-is (zero new restores) while an incomplete one re-drives only the missing refs idempotently. rollback=true with FLAG or ENDORSE is rejected with 422 before any work. Deciding verbs (ENDORSE / REJECT) require a human principal - agent credentials may only FLAG (403 otherwise).'
      operationId: create-jot-disposition
      parameters:
      - description: Resource ID of the jot.
        in: path
        name: resourceId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Add Jot Disposition
      tags:
      - Jots
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddJotDispositionRequest'
        description: The disposition request.
        required: true
    servers:
    - url: https://api.getjaz.com
components:
  schemas:
    ErrorResponse:
      properties:
        error:
          allOf:
          - $ref: '#/components/schemas/ErrorResponseData'
          description: Error details.
      type: object
    CreateJotsRequest:
      properties:
        entries:
          description: Jot entries (1-100 per batch, per-entry independent).
          items:
            $ref: '#/components/schemas/CreateJotEntryRequest'
          maxItems: 100
          minItems: 1
          type: array
      required:
      - entries
      type: object
    BaseResponse:
      properties:
        data:
          description: The response object.
      type: object
    CreateJotEntryRequest:
      properties:
        agentLabel:
          description: Self-reported product and model; informative, never authoritative.
          example: jaz-Jaz/claude-fable-5
          type: string
        call:
          description: The decision, one line (server truncates beyond 600 chars with a parse flag).
          example: Posted to 6420 Travel, recurring Grab vendor pattern
          type: string
        citedRule:
          description: The organization rule, policy, threshold, or precedent applied.
          type: string
        confidence:
          description: Routing hint for review attention. Unrecognized values are accepted and stored.
          example: HIGH
          type: string
        frame:
          description: 'For set-shaped subjects: the query that defines the set, plus counts (server truncates beyond 480 chars).'
          example: search_bills status=UNPAID · 41 in scope, 4 deferred
          type: string
        idempotencyKey:
          description: 'Client-suppliable replay key: retrying with the same key returns the existing row''s resourceId instead of writing a duplicate.'
          type: string
        kind:
          description: Judgment kind. Unrecognized values are stored rather than rejected, so no fixed list is enforced.
          example: CLASSIFICATION
          type: string
        refs:
          description: Entity references in either accepted form (string grammar via raw, or object form). Normalized server-side rather than rejected.
          items:
            $ref: '#/components/schemas/JotRefRequest'
          type: array
        ruledOut:
          description: Alternatives considered and set aside (server truncates beyond 600 chars).
          type: string
        tier:
          description: Agent-declared severity tier. The server also computes a normalized tier; unrecognized values are accepted.
          example: MEDIUM
          type: string
        why:
          description: The basis for the call (server truncates beyond 900 chars).
          type: string
        workflowLabel:
          description: Short workflow label (e.g. month-end-close, payment-run, conversion).
          example: month-end-close
          type: string
        writePath:
          description: How the jot arrived. Defaults to TOOL. Invalid values are repaired server-side rather than rejected, so no fixed list is enforced.
          example: REST
          type: string
      type: object
    SearchJotsRequest:
      properties:
        filter:
          allOf:
          - $ref: '#/components/schemas/JotSearchFilter'
          description: Structured filter.
        includeStats:
          description: When true the response carries per-credential disposition counts (stats).
          type: boolean
        limit:
          default: 100
          description: Maximum number of results per page (max 1000).
          maximum: 1000
          minimum: 1
          type: integer
        offset:
          default: 0
          description: Zero-indexed row offset into the result set. Sort is fixed server-side, so no sort field is needed.
          maximum: 65536
          minimum: 0
          type: integer
      type: object
    JotSearchFilter:
      properties:
        createdFrom:
          description: Created-at lower bound, epoch milliseconds (inclusive).
          type: integer
        createdTo:
          description: Created-at upper bound, epoch milliseconds (inclusive).
          type: integer
        dispositionVerb:
          description: Keeps only jots carrying at least one disposition with this verb.
          enum:
          - FLAG
          - REJECT
          - ENDORSE
          type: string
        firstParty:
          description: When true, keep only first-party entries (written by Jaz-operated agent surfaces, with a server-stamped origin); false keeps only the rest. Omit for all entries.
          type: boolean
        freetext:
          description: Case-insensitive substring over call and why.
          type: string
        kind:
          description: Filter by judgment kind (exact match).
          type: string
        pinned:
          description: When true, keep only pinned entries (declared or derived CRITICAL severity, or a withheld write, the same predicate the pinned sort uses); false keeps only unpinned. Omit for all entries.
          type: boolean
        ref:
          description: Entity ref as TYPE:resourceId (matched by containment over refs).
          example: INVOICE:41f626a3-9635-410c-bb5b-f34443e6903e
          type: string
        tier:
          description: Filter by agent-declared severity tier (exact match).
          type: string
      type: object
    PageableResponse:
      properties:
        data:
          description: Result rows for the requested page.
        totalElements:
          description: Total number of records matching the query.
          type: integer
        totalPages:
          description: Total number of pages.
          type: integer
      type: object
    AddJotDispositionRequest:
      properties:
        note:
          description: Optional reviewer note (flagging costs a sentence; endorsement is cheap).
          type: string
        resourceId:
          description: Jot resource ID (UUIDv4).
          type: string
        rollback:
          default: false
          description: 'When true (REJECT only), asynchronously roll back the jot''s mutation-relation refs to their pre-agent versions; the per-ref outcomes land on the jot and are readable via recall (jot search). rollback:true with FLAG or ENDORSE is rejected with 422 before any work. Repeating a REJECT with rollback:true is safe: a completed outcome replays as-is while an incomplete one (still in flight, or an exhausted-retry ref) re-drives only the missing refs idempotently.'
          type: boolean
        verb:
          description: Review verb.
          enum:
          - FLAG
          - REJECT
          - ENDORSE
          example: ENDORSE
          type: string
      required:
      - resourceId
      - verb
      type: object
    JotRefRequest:
      properties:
        field:
          description: 'Object form: optional field path for field-level judgments.'
          example: currencyCode
          type: string
        id:
          description: 'Object form: entity resource ID verbatim from an API response.'
          example: 41f626a3-9635-410c-bb5b-f34443e6903e
          type: string
        raw:
          description: 'String grammar form: TYPE:resourceId[#fieldPath][:RELATION]. Wins when both forms are present.'
          example: INVOICE:41f626a3-9635-410c-bb5b-f34443e6903e:CREATE
          type: string
        relation:
          description: 'Object form: relation role, defaulting to SUBJECT. Invalid values are repaired server-side rather than rejected.'
          example: CREATE
          type: string
        type:
          description: 'Object form: platform entity type, UPPER_SNAKE (e.g. INVOICE, BILL, JOURNAL).'
          example: INVOICE
          type: string
      type: object
    ErrorResponseData:
      properties:
        error_type:
          description: Error category, for example validation_error, invalid_request_body, or internal_server_error.
          example: validation_error
          type: string
        errors:
          description: Error messages describing what went wrong.
          items:
            type: string
          type: array
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: Organization API key. Pass it in the x-jk-api-key header on every request.
      in: header
      name: x-jk-api-key
      type: apiKey
x-refined-from:
- tinvio-com-openapi-original.yaml
- tinvio-com-openapi.yml