Navis N4 Terminal Operating System REST API

naftiko: 1.0.0-alpha2
info:
  label: Navis N4 Terminal Operating System REST API
  description: NAVIS N4 provides terminal operating system APIs for container port operations. APIs enable container tracking,
    vessel planning, berth scheduling, yard management, and gate operations for port terminals and intermodal facilities.
    Now operated by Kaleris, serving 650+ organizations across 95+ countries.
  tags:
  - Navis
  - API
  created: '2026-05-06'
  modified: '2026-05-06'
capability:
  consumes:
  - type: http
    namespace: navis
    baseUri: https://yourterminal.navis.example.com/apex/n4/api/v2
    description: Navis N4 Terminal Operating System REST API HTTP API.
    authentication:
      type: basic
      username: '{{NAVIS_USERNAME}}'
      password: '{{NAVIS_PASSWORD}}'
    resources:
    - name: units
      path: /units
      operations:
      - name: searchunits
        method: GET
        description: Search container units
        inputParameters:
        - name: unitNbr
          in: query
          type: string
          description: Container number (ISO 6346 format, e.g., MSCU1234567)
        - name: equipmentType
          in: query
          type: string
        - name: category
          in: query
          type: string
        - name: freightKind
          in: query
          type: string
        - name: positionLocType
          in: query
          type: string
        - name: lineOperator
          in: query
          type: string
          description: Shipping line SCAC code
        - name: vesselVisit
          in: query
          type: string
          description: Vessel visit identifier
        - name: limit
          in: query
          type: integer
        - name: offset
          in: query
          type: integer
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: units-unitid
      path: /units/{unitId}
      operations:
      - name: getunit
        method: GET
        description: Get container unit details
        inputParameters:
        - name: unitId
          in: path
          type: string
          required: true
          description: N4 unit identifier or ISO 6346 container number
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: vessel-visits
      path: /vessel-visits
      operations:
      - name: listvesselvisits
        method: GET
        description: List vessel visits
        inputParameters:
        - name: vesselName
          in: query
          type: string
        - name: status
          in: query
          type: string
        - name: arrivalFrom
          in: query
          type: string
        - name: arrivalTo
          in: query
          type: string
        - name: limit
          in: query
          type: integer
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: vessel-visits-visitid
      path: /vessel-visits/{visitId}
      operations:
      - name: getvesselvisit
        method: GET
        description: Get vessel visit details
        inputParameters:
        - name: visitId
          in: path
          type: string
          required: true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: vessel-visits-visitid-units
      path: /vessel-visits/{visitId}/units
      operations:
      - name: getvesselvisitunits
        method: GET
        description: Get units for a vessel visit
        inputParameters:
        - name: visitId
          in: path
          type: string
          required: true
        - name: category
          in: query
          type: string
        - name: limit
          in: query
          type: integer
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: gate-transactions
      path: /gate-transactions
      operations:
      - name: listgatetransactions
        method: GET
        description: List gate transactions
        inputParameters:
        - name: transactionType
          in: query
          type: string
        - name: containerNbr
          in: query
          type: string
        - name: truckId
          in: query
          type: string
        - name: fromDate
          in: query
          type: string
        - name: toDate
          in: query
          type: string
        - name: limit
          in: query
          type: integer
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: work-queues
      path: /work-queues
      operations:
      - name: getworkqueues
        method: GET
        description: Get active work queues
        inputParameters:
        - name: craneId
          in: query
          type: string
        - name: status
          in: query
          type: string
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: holds
      path: /holds
      operations:
      - name: listholds
        method: GET
        description: List active holds on units
        inputParameters:
        - name: unitNbr
          in: query
          type: string
        - name: holdType
          in: query
          type: string
        - name: limit
          in: query
          type: integer
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: navis-rest
    description: REST adapter for Navis N4 Terminal Operating System REST API.
    resources:
    - path: /units
      name: searchunits
      operations:
      - method: GET
        name: searchunits
        description: Search container units
        call: navis.searchunits
        outputParameters:
        - type: object
          mapping: $.
    - path: /units/{unitId}
      name: getunit
      operations:
      - method: GET
        name: getunit
        description: Get container unit details
        call: navis.getunit
        with:
          unitId: rest.unitId
        outputParameters:
        - type: object
          mapping: $.
    - path: /vessel-visits
      name: listvesselvisits
      operations:
      - method: GET
        name: listvesselvisits
        description: List vessel visits
        call: navis.listvesselvisits
        outputParameters:
        - type: object
          mapping: $.
    - path: /vessel-visits/{visitId}
      name: getvesselvisit
      operations:
      - method: GET
        name: getvesselvisit
        description: Get vessel visit details
        call: navis.getvesselvisit
        with:
          visitId: rest.visitId
        outputParameters:
        - type: object
          mapping: $.
    - path: /vessel-visits/{visitId}/units
      name: getvesselvisitunits
      operations:
      - method: GET
        name: getvesselvisitunits
        description: Get units for a vessel visit
        call: navis.getvesselvisitunits
        with:
          visitId: rest.visitId
        outputParameters:
        - type: object
          mapping: $.
    - path: /gate-transactions
      name: listgatetransactions
      operations:
      - method: GET
        name: listgatetransactions
        description: List gate transactions
        call: navis.listgatetransactions
        outputParameters:
        - type: object
          mapping: $.
    - path: /work-queues
      name: getworkqueues
      operations:
      - method: GET
        name: getworkqueues
        description: Get active work queues
        call: navis.getworkqueues
        outputParameters:
        - type: object
          mapping: $.
    - path: /holds
      name: listholds
      operations:
      - method: GET
        name: listholds
        description: List active holds on units
        call: navis.listholds
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: navis-mcp
    transport: http
    description: MCP adapter for Navis N4 Terminal Operating System REST API for AI agent use.
    tools:
    - name: searchunits
      description: Search container units
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: navis.searchunits
      with:
        unitNbr: tools.unitNbr
        equipmentType: tools.equipmentType
        category: tools.category
        freightKind: tools.freightKind
        positionLocType: tools.positionLocType
        lineOperator: tools.lineOperator
        vesselVisit: tools.vesselVisit
        limit: tools.limit
        offset: tools.offset
      inputParameters:
      - name: unitNbr
        type: string
        description: Container number (ISO 6346 format, e.g., MSCU1234567)
      - name: equipmentType
        type: string
        description: equipmentType
      - name: category
        type: string
        description: category
      - name: freightKind
        type: string
        description: freightKind
      - name: positionLocType
        type: string
        description: positionLocType
      - name: lineOperator
        type: string
        description: Shipping line SCAC code
      - name: vesselVisit
        type: string
        description: Vessel visit identifier
      - name: limit
        type: integer
        description: limit
      - name: offset
        type: integer
        description: offset
      outputParameters:
      - type: object
        mapping: $.
    - name: getunit
      description: Get container unit details
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: navis.getunit
      with:
        unitId: tools.unitId
      inputParameters:
      - name: unitId
        type: string
        description: N4 unit identifier or ISO 6346 container number
        required: true
      outputParameters:
      - type: object
        mapping: $.
    - name: listvesselvisits
      description: List vessel visits
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: navis.listvesselvisits
      with:
        vesselName: tools.vesselName
        status: tools.status
        arrivalFrom: tools.arrivalFrom
        arrivalTo: tools.arrivalTo
        limit: tools.limit
      inputParameters:
      - name: vesselName
        type: string
        description: vesselName
      - name: status
        type: string
        description: status
      - name: arrivalFrom
        type: string
        description: arrivalFrom
      - name: arrivalTo
        type: string
        description: arrivalTo
      - name: limit
        type: integer
        description: limit
      outputParameters:
      - type: object
        mapping: $.
    - name: getvesselvisit
      description: Get vessel visit details
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: navis.getvesselvisit
      with:
        visitId: tools.visitId
      inputParameters:
      - name: visitId
        type: string
        description: visitId
        required: true
      outputParameters:
      - type: object
        mapping: $.
    - name: getvesselvisitunits
      description: Get units for a vessel visit
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: navis.getvesselvisitunits
      with:
        visitId: tools.visitId
        category: tools.category
        limit: tools.limit
      inputParameters:
      - name: visitId
        type: string
        description: visitId
        required: true
      - name: category
        type: string
        description: category
      - name: limit
        type: integer
        description: limit
      outputParameters:
      - type: object
        mapping: $.
    - name: listgatetransactions
      description: List gate transactions
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: navis.listgatetransactions
      with:
        transactionType: tools.transactionType
        containerNbr: tools.containerNbr
        truckId: tools.truckId
        fromDate: tools.fromDate
        toDate: tools.toDate
        limit: tools.limit
      inputParameters:
      - name: transactionType
        type: string
        description: transactionType
      - name: containerNbr
        type: string
        description: containerNbr
      - name: truckId
        type: string
        description: truckId
      - name: fromDate
        type: string
        description: fromDate
      - name: toDate
        type: string
        description: toDate
      - name: limit
        type: integer
        description: limit
      outputParameters:
      - type: object
        mapping: $.
    - name: getworkqueues
      description: Get active work queues
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: navis.getworkqueues
      with:
        craneId: tools.craneId
        status: tools.status
      inputParameters:
      - name: craneId
        type: string
        description: craneId
      - name: status
        type: string
        description: status
      outputParameters:
      - type: object
        mapping: $.
    - name: listholds
      description: List active holds on units
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: navis.listholds
      with:
        unitNbr: tools.unitNbr
        holdType: tools.holdType
        limit: tools.limit
      inputParameters:
      - name: unitNbr
        type: string
        description: unitNbr
      - name: holdType
        type: string
        description: holdType
      - name: limit
        type: integer
        description: limit
      outputParameters:
      - type: object
        mapping: $.
binds:
- namespace: env
  keys:
    NAVIS_USERNAME: NAVIS_USERNAME
    NAVIS_PASSWORD: NAVIS_PASSWORD