openapi: 3.0.3
info:
  title: Kpler Direct Access Aggregations Authentication API
  version: '1.0'
  description: 'REST API for the Kpler commodities intelligence platform, giving programmatic access to the same trades, flows, and vessel data available in the Kpler terminal. The same Direct Access endpoint surface is served per commodity platform from four hosts - Liquids (api.kpler.com), LNG (api-lng.kpler.com), LPG (api-lpg.kpler.com), and Dry (api-dry.kpler.com).


    ACCESS MODEL - Kpler APIs are customer-gated. Documentation (Direct Access user guides at *.dev.kpler.com and the developer portal at developers.kpler.com) and the Python SDK are public, but calling the API requires client credentials issued with a commercial Kpler subscription.


    ENDPOINTS MODELED - x-endpoints-modeled: this document describes only the endpoints and parameters confirmed from Kpler''s public Direct Access guides, the public Python SDK (python-sdk.dev.kpler.com), and Kpler''s public Postman workspace, including the documented example request https://api-dry.kpler.com/v1/trades?size=6&columns=trade_id,vessel_name,start,end&fromZones=Europe&toZones=Asia. The full parameter and response surface is only visible to authenticated customers, so responses are modeled loosely and additional documented endpoint families (port calls, ship-to-ship transfers, storage, contracts, prices, outages, fleet metrics, congestion, inventories, refineries, products, installations, zones, players) are noted but not fully modeled here. Nothing in this document is fabricated beyond that abridgement.'
  contact:
    name: Kpler Customer Success
    email: cs@kpler.com
    url: https://developers.kpler.com/
  x-access-model: customer-gated
  x-endpoints-modeled: true
servers:
- url: https://api.kpler.com
  description: Liquids platform (crude, CPP, DPP)
- url: https://api-lng.kpler.com
  description: LNG platform
- url: https://api-lpg.kpler.com
  description: LPG platform
- url: https://api-dry.kpler.com
  description: Dry platform (coal and dry bulk)
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Authentication
paths:
  /login:
    post:
      operationId: login
      tags:
      - Authentication
      summary: Exchange Kpler client credentials for a bearer token
      description: Returns an authorization token used as a bearer pass for subsequent API requests. Basic Authentication with encoded credentials in the Authorization header is also supported directly on data endpoints, without calling /login.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: Kpler account email.
                password:
                  type: string
                  description: Kpler account password.
              required:
              - email
              - password
      responses:
        '200':
          description: Authorization token issued.
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
        '401':
          description: Invalid credentials.
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Encoded Kpler client credentials in the Authorization header.
    bearerAuth:
      type: http
      scheme: bearer
      description: Token obtained from the /login endpoint.
externalDocs:
  description: Kpler Developer Portal
  url: https://developers.kpler.com/