openapi.yml

openapi: 3.0.3
info:
  title: FAPI Catalog API
  description: |
    OEM cross-reference database for auto parts. Look up parts by article
    number, manufacturer, vehicle applicability, and find equivalent parts
    across brands.

    ## Authorization

    Every endpoint requires an API key in the `Authorization` header:

    ```
    Authorization: Bearer <key>
    ```

    A key never belongs in a URL: URLs reach access logs, browser history and
    every proxy on the way. A refusal carries a `MessageList` whose `i` tells
    which check refused (see the 401, 403 and 503 responses).

    ## Getting a key

    Register at [id.iisis.ru](https://id.iisis.ru) and issue a key for this
    API on the "Keys" page of your account. A new account starts on a trial
    package of credits, granted once; `GET /usage` shows what is left of it.
    VIN decoding (`GET /vin`) is not part of the package: it is billed to a
    prepaid balance of its own. Questions — `development.iisis@gmail.com` or
    [fapi.iisis.ru](https://fapi.iisis.ru).
  version: "4.12.0"
  contact:
    email: development.iisis@gmail.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html

servers:
  - url: https://fapi.iisis.ru/fapi/v2
    description: Main API host

tags:
  - name: manufacturerList
    description: Manufacturers (brands).
  - name: productList
    description: Parts, attributes, vehicle applicability, images, and search helpers.
  - name: analogList
    description: Cross-references (analogs / equivalent parts).
  - name: catalogDt
    description: Lookup against the non-original parts catalog (by vehicle make / model / modification / node).
  - name: account
    description: Your own account — plan, usage and balance.

security:
  - bearer: []

paths:
  /imageList:
    get:
      tags:
        - productList
      summary: Get a part image
      description: Returns a JPEG image of the part. When the part has no image, `imgd` decides between a placeholder image and `404`.
      parameters:
        - in: query
          name: mfi
          description: Manufacturer index.
          required: true
          schema:
            type: integer
            default: 13007
        - in: query
          name: n
          description: Part number (article).
          required: true
          schema:
            type: string
            default: "10100"
        - in: query
          name: imgd
          description: "(Image Default) Behaviour when no image is found for the part: true returns a default placeholder image; false returns 404. Defaults to true."
          required: false
          schema:
            type: boolean
            default: true
        - in: query
          name: width
          description: Image width in pixels.
          required: false
          schema:
            type: integer
            default: 200
      responses:
        '200':
          description: JPEG image bytes — the part's image, or the placeholder when it has none and `imgd` is not false.
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: The part has no image (only when imgd=false).
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /manufacturerList:
    get:
      tags:
        - manufacturerList
      summary: List all manufacturers
      description: Returns the full list of manufacturers (brands), plus a separate list of manufacturer name aliases. Typically called once and cached on the client; the `dbi` value on each manufacturer is the key used by other endpoints.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManufacturerListFull'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /productList:
    get:
      tags:
        - productList
      summary: Look up parts by article number
      description: Returns parts matching the given article number — of every brand, or of one brand when `mfi` is given — together with their manufacturers, cross-references, and any messages. The response shape is the same composite object as `/analogList`.
      parameters:
        - in: query
          name: n
          description: Part article number, or the leading portion of one.
          required: true
          schema:
            type: string
            default: A00742
        - in: query
          name: mfi
          description: Manufacturer index (optional, narrows results to a specific brand).
          required: false
          schema:
            type: integer
        - in: query
          name: comparison
          description: If set, `n` is treated as a search prefix / pattern rather than an exact article number.
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalogListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /productNumberList:
    get:
      tags:
        - productList
      summary: Autocomplete part numbers
      description: Returns a flat list of part numbers matching the given prefix. Useful for type-ahead suggestions.
      parameters:
        - in: query
          name: n
          description: Part article number, or the leading portion of one.
          required: true
          schema:
            type: string
            default: A00742
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /barcodeList:
    get:
      tags:
        - productList
      summary: Find parts by barcode
      description: |
        Returns the parts a barcode on a part's box identifies, in the same composite
        object as `/productList`, after the code as it was read (`barcode`: its digits, its
        format and its 14-digit GTIN). One code may identify several parts — the same product
        sold under several brands — and all of them are returned. The other way round, the
        barcodes of a part, is `/productBarcodeList`.

        EAN-13, EAN-8, UPC-A and GTIN-14 are one number written in different widths and are
        read as such: a UPC-A finds the part listed under its EAN-13. Spaces are ignored. A
        code that is not one of these, or whose check digit does not match, is refused with
        `400` before anything is looked up.

        A part FAPI's catalog holds comes with its catalog fields; a part only the barcode
        data knows comes with its manufacturer and article number — enough to ask
        `/analogList` for its cross-references.

        A code that identifies a part is charged at this method's price; a valid code that
        identifies none is charged as an empty answer; a `400` is not charged.
      parameters:
        - in: query
          name: code
          description: The barcode's digits — EAN-13, EAN-8, UPC-A or GTIN-14.
          required: true
          schema:
            type: string
            default: "4019064140399"
      responses:
        '200':
          description: OK — the parts the code identifies; empty lists when it identifies none.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BarcodeListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          description: The lookup failed on the server; the body is empty. Not charged.
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /productBarcodeList:
    get:
      tags:
        - productList
      summary: Get the barcodes of a part
      description: |
        Returns the barcodes of a part given by its manufacturer and article number —
        EAN-13, EAN-8, UPC-A or GTIN-14, each with its format and its 14-digit GTIN.

        Only codes that lead back to the part are returned: looking any of them up with
        `/barcodeList` finds this part. A part may have several codes (different package
        sizes, a code replaced over the years); the most reliable come first.

        Charged at this method's price when the part has codes; a part without codes is
        charged as an empty answer; a `400` is not charged.
      parameters:
        - in: query
          name: mfi
          description: Manufacturer index (see `/manufacturerList`).
          required: true
          schema:
            type: integer
            default: 11632
        - in: query
          name: n
          description: Part article number, in any spelling — spaces and punctuation are ignored.
          required: true
          schema:
            type: string
            default: "66235"
      responses:
        '200':
          description: OK — the part's codes; an empty list when it has none.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductBarcodeListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          description: The lookup failed on the server; the body is empty. Not charged.
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /productParameterList:
    get:
      tags:
        - productList
      summary: Get extra attributes of a part
      description: |
        Returns the list of key/value attributes (weight, dimensions, etc.) attached to a specific part.

        A part the catalog does not hold under this manufacturer is answered with an empty list,
        like a part without attributes.

        Charged at this method's price when the part has attributes; an empty list is charged
        as an empty answer; a `400` or a `500` is not charged.
      parameters:
        - in: query
          name: n
          description: Part article number.
          required: true
          schema:
            type: string
            default: "10100"
        - in: query
          name: mfi
          description: Manufacturer index.
          required: true
          schema:
            type: integer
            default: 13007
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParameterListResponse'
        '400':
          description: |
            `n` is empty, or `mfi` is missing, not a number or not a known manufacturer
            (see `/manufacturerList`); the body is empty. Not charged.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          description: The lookup failed on the server; the body is empty. Not charged.
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /productApplicabilityList:
    get:
      tags:
        - productList
      summary: Vehicle applicability for a part
      description: |
        Returns the vehicles (manufacturer / model / modification) the given part fits.

        When `mfi` is the brand of a passenger-car manufacturer, `n` is read as that
        manufacturer's original (OE) number as well: the answer lists the
        vehicles of that brand which the aftermarket parts cross-referenced to
        the number fit. Only the brand's own vehicles count — a universal part
        that also replaces the number does not bring in every other make it
        fits. A vehicle that a single parts maker alone links to the number is
        left out once others are confirmed by two or more; a number only one
        parts maker references keeps all its vehicles.

        A brand that is both a parts maker and a vehicle manufacturer gets both
        answers in one list, each vehicle once. `[]` lists mean nothing is
        known — a normal answer.
      parameters:
        - in: query
          name: mfi
          description: Manufacturer index — the part's maker, or a vehicle manufacturer to look its original number up.
          required: true
          schema:
            type: integer
            default: 12738
        - in: query
          name: n
          description: Part article number, or an original (OE) number of the vehicle manufacturer given in `mfi`.
          required: true
          schema:
            type: string
            default: "AG+251"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /part:
    get:
      tags:
        - analogList
      summary: The card of one article
      description: |
        The article the way a catalogue shows it: the part and its `status` — `current`, or
        `replaced` with `current` naming the number at the end of its replacement chain —
        and its links in blocks: `replacedBy` (the part is discontinued, these replace it),
        `replaces` (its former numbers), `oe` (original numbers of vehicle manufacturers'
        brands) and `analogs` (equivalent parts of other brands, best first). Every link
        carries `rp`/`rm` and `mfc` when the manufacturer itself vouches for it. The same
        cross-references `/analogList` answers, grouped.

        With `n` alone, a number several brands carry answers `candidates` and no card: ask
        again with `mfi`. One candidate is answered as its card. Nothing known is
        `{"candidates": []}`.
      parameters:
        - in: query
          name: n
          description: Part article number.
          required: true
          schema:
            type: string
            default: "LRc 0127"
        - in: query
          name: mfi
          description: Manufacturer index — `dbi` of the part's brand, or `mfi` of a candidate.
          required: false
          schema:
            type: integer
        - in: query
          name: r
          description: A link is listed when its rating (`rp - rm`) exceeds this. Default 0.
          required: false
          schema:
            type: integer
            default: 0
        - in: query
          name: limit
          description: At most this many analogs (the other blocks are whole). Default 200, at most 1000.
          required: false
          schema:
            type: integer
            default: 200
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartCard'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /analogList:
    get:
      tags:
        - analogList
      summary: Get cross-references for a part
      description: Returns the cross-reference graph for the given part article number — manufacturers, products, and the analog links between them.
      parameters:
        - in: query
          name: n
          description: Part article number.
          required: true
          schema:
            type: string
            default: A0074207920
        - in: query
          name: mfi
          description: Manufacturer index (optional, narrows results to a specific brand).
          required: false
          schema:
            type: integer
        - in: query
          name: r
          description: Filter results by minimum cross-reference confidence rating. Higher values return fewer but more verified crosses. 0 = no filter.
          required: false
          schema:
            type: integer
            default: 0
        - in: query
          name: o
          description: |
            Additional filter mode:
            - `NOT_USE` — no extra filter.
            - `ONLY_OWN` — only crosses you have voted on (verified or broken); ignores `r`.
            - `CORRECT_AR` — only verified crosses combined with the rating filter. An analog marked verified is included even if its rating is below the threshold.
          required: false
          schema:
            type: string
            enum:
              - NOT_USE
              - ONLY_OWN
              - CORRECT_AR
            default: NOT_USE
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalogListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /catalogList/dt/manufacturerList:
    get:
      tags:
        - catalogDt
      summary: List vehicle manufacturers (catalog)
      description: Returns the manufacturers available for the vehicle-catalog dropdown.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManufacturerList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /catalogList/dt/modelList:
    get:
      tags:
        - catalogDt
      summary: List vehicle models for a manufacturer
      description: Returns the models that belong to a given vehicle manufacturer.
      parameters:
        - in: query
          name: mfi
          description: Manufacturer identifier.
          required: true
          schema:
            type: integer
            default: 111
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /catalogList/dt/modificationList:
    get:
      tags:
        - catalogDt
      summary: List modifications of a vehicle model
      description: Returns the modifications (engine / body / drive variants) of a given vehicle model.
      parameters:
        - in: query
          name: mi
          description: Model identifier (dbi).
          required: true
          schema:
            type: integer
            default: 4846
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModificationList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /catalogList/dt/treeList:
    get:
      tags:
        - catalogDt
      summary: Node tree for a vehicle modification
      description: Returns the tree of part-group nodes for the given vehicle modification.
      parameters:
        - in: query
          name: mi
          description: Modification identifier (dbi).
          required: true
          schema:
            type: integer
            default: 124170
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TreeNode'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /catalogList/dt/productList:
    get:
      tags:
        - catalogDt
      summary: List parts for a catalog node
      description: Returns the parts attached to a given node within a given vehicle modification.
      parameters:
        - in: query
          name: nodei
          description: Node identifier (dbi).
          required: true
          schema:
            type: integer
            default: 100259
        - in: query
          name: modi
          description: Modification identifier (dbi).
          required: true
          schema:
            type: integer
            default: 124170
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CatalogProductRow'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /catalogList/dt/productListOEM:
    get:
      tags:
        - catalogDt
      summary: Original (OE) numbers for a catalog node
      description: |
        The vehicle maker's original numbers for a (node, modification) pair —
        the counterpart of `/catalogList/dt/productList`, which returns the
        aftermarket parts for the same pair. Match on `ns`; the spelling in `n`
        comes from the source and may differ between answers. `[]` means the
        node has no originals — a normal answer. Send `Accept-Encoding: gzip`:
        answers reach hundreds of kilobytes and compress about eightfold.

        The answer is the modification's, not one car's. It lists every
        original number the aftermarket parts fitted to this modification
        replace, so it knows neither the side of installation, nor the factory
        options, nor the build date inside the modification's production
        years: a node may return several numbers where the maker's own parts
        catalog shows one for a given VIN — a left and a right part, or two
        spellings of one number. Decoding a VIN narrows the vehicle down to
        the modification and no further; where a part has such variants,
        confirm the number to order in the maker's catalog.

        Rows come brand by brand, the vehicle's own first, and inside a brand
        the most widely confirmed number first (`sources`), equal ones by
        number. The order says how well established a number is, not which of
        them fits a particular car.
      parameters:
        - in: query
          name: modi
          description: Modification identifier — `dbi` from `/catalogList/dt/modificationList`.
          required: true
          schema:
            type: integer
            default: 137147
        - in: query
          name: nodei
          description: Node identifier — `i` from `/catalogList/dt/treeList`.
          required: true
          schema:
            type: integer
        - in: query
          name: family
          description: |
            `1` adds the numbers of the maker's platform relatives (Vauxhall →
            Opel and General Motors, Mini → BMW, Infiniti → Nissan). The relation
            is directed: Opel does not get Vauxhall's numbers. Only `0` or `1`;
            anything else is a 400.
          required: false
          schema:
            type: integer
            enum: [0, 1]
            default: 0
        - in: query
          name: strict
          description: |
            `1` drops numbers the market files under another brand or as another
            part; `0` returns the full list, source errors included. Only `0` or
            `1`; anything else is a 400.
          required: false
          schema:
            type: integer
            enum: [0, 1]
            default: 1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OemRow'
        '400':
          description: "`modi` or `nodei` missing or not a number, or `family` / `strict` not `0` or `1`. Empty body."
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /vin:
    get:
      tags:
        - catalogDt
      summary: Identify a vehicle by VIN
      description: |
        Decodes a VIN into one vehicle. The answer is the VIN decoder's own,
        relayed unchanged: its fields are listed below as they are today, and
        the decoder may add fields at any time — ignore the ones you do not
        know. `dt_type_id` is the modification key of the catalogue routes:
        `mi` of `/catalogList/dt/treeList`, `modi` of
        `/catalogList/dt/productList` and `/catalogList/dt/productListOEM`.
        `confidence` says how deep the vehicle was identified; a VIN nothing
        is known about is still a 200.

        Your key must open VIN decoding as well as this API: it is presented
        to the VIN decoder on your behalf, and decoding is billed to you there.
        A key that does not is refused with `i=15` and the decoder's own code
        (`unknown_key`, `key_expired`, `identity_unavailable`). Decoding may
        also be refused over your account's balance there rather than your
        key — see the `402` and `503` responses below — and never billed
        when it is: `vin` in `GET /usage` shows that balance.

        The answer's codes are the same in every language. Pass `lang` to
        get, next to them, `labels` — each code's name in that language — and
        `model_name` and `modification_name` in it. Without `lang` the answer
        is exactly what it was before the parameter existed.
      parameters:
        - in: query
          name: vin
          description: 17-character VIN (ISO 3779 — digits and Latin letters except I, O, Q; case-insensitive). Checked by the VIN decoder; anything else is a 400.
          required: true
          schema:
            type: string
            minLength: 17
            maxLength: 17
            default: XWF0AHL30D0011102
        - in: query
          name: lang
          description: |
            Language to answer in: an ISO 639-1 code the vehicle catalog
            holds (`ru`, `en`, `tr`, `de`, `fr`, `es`, … — 43 languages),
            case-insensitive. Adds `labels` and names the model and the
            modification in that language; the codes and `dt_card` never
            change with it. A language the catalog does not hold is a 400,
            never an answer in another language.
          required: false
          schema:
            type: string
            minLength: 2
            maxLength: 2
            example: tr
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VinResponse'
        '400':
          description: |
            VIN missing or not ISO 3779, or VIN decoding is not configured on
            this host: an empty body. Or `lang` names a language the vehicle
            catalog does not hold: `i=15`, code `lang_unsupported`, with the
            decoder's own sentence. Refused before decoding runs, so never
            charged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageList'
        '401':
          description: No key, an expired key, or `i=15` — the VIN decoder refused the key as expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageList'
        '403':
          description: The key was refused (see `Forbidden`), or `i=15` — the key does not open VIN decoding.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageList'
        '402':
          description: |
            Your account's prepaid balance for VIN decoding is exhausted
            (`i=15`, code `balance_exhausted`). Top up the balance —
            retrying will not help. That balance alone decides it: no plan
            of this API opens or closes VIN decoding, the trial included
            (`i=22`, answered to a trial account until 2026-10-02, is
            retired and never reused). Not charged: a 402 is refused before
            decoding runs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageList'
        '500':
          description: The VIN decoder did not answer. Empty body.
        '503':
          description: |
            The key could not be checked right now, here (`i=13`) or by the
            VIN decoder (`i=15`); or the VIN decoder's own balance check is
            down (`i=15`, code `balance_unavailable`, unrelated to your key).
            Repeat after `Retry-After`.
          headers:
            Retry-After:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageList'

  /usage:
    get:
      tags:
        - account
      summary: Read your own plan, usage and balances
      description: |
        Your own billing position, read from the billing gate's in-process snapshot: never a
        database read on this call, and never older than `ts`. Balance only for now — usage
        history is planned as a later addition to this same route.

        Next to it, `vin` is your prepaid balance for VIN decoding (`GET /vin`), read at the
        VIN decoder with your key on every call. When the decoder gives no balance, `vin.st`
        says why and the account is answered all the same: `no_access` — your key does not
        open VIN decoding; `unavailable` — the decoder could not be read in time, ask again
        later.

        Free and never gated: even a request that would be refused for non-payment on every
        other route still gets a `200` here, never a `402` — `st` and `d` say exactly what a
        request elsewhere would be refused with right now, in the same words. The partner
        comes only from your key; no parameter can name another one.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          description: |
            Could not answer right now: the key could not be checked (`i=13`), or usage data
            is temporarily unavailable (`i=20`) — billing is off on this node, or its snapshot
            has never loaded. Repeat after `Retry-After`.
          headers:
            Retry-After:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageList'

components:
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: The API key issued to you, in the `Authorization` header.

  responses:
    BadRequest:
      description: Invalid request parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MessageList'
    Unauthorized:
      description: |
        No key was sent, or `i=12` the key has expired (sent with
        `WWW-Authenticate`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MessageList'
    PaymentRequired:
      description: |
        Your account cannot pay for this request: `i=16` the current period's
        subscription fee is not paid, `i=17` the request package is spent and
        your plan sells no overage, `i=18` the package is spent and your
        balance is too. The message text says which and links the payment
        page. A 402 is never cleared by retrying: top up (`16`, `18`) or
        change plan (`17`), then send the request again — `GET /usage` shows
        the same verdict and text beforehand, and confirms once you have paid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MessageList'
    Forbidden:
      description: |
        Access denied: `i=10` key was not found — 403 rather than 401, because
        a key unknown to this product may be valid for another one; `i=11`
        access status = 0.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MessageList'
    ServiceUnavailable:
      description: |
        `i=13` identity service is unavailable. The service could not check
        the key right now; it does not mean the key is wrong.
        Repeat after `Retry-After`.
      headers:
        Retry-After:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MessageList'
    ServerError:
      description: Server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MessageList'

  schemas:
    ManufacturerListFull:
      type: object
      description: Full manufacturer list, including name aliases.
      required:
        - mf
        - al
      properties:
        mf:
          type: array
          description: Manufacturers.
          items:
            $ref: '#/components/schemas/ManufacturerListRow'
        al:
          type: array
          description: Manufacturer name aliases (alternative spellings mapped to a manufacturer index).
          items:
            $ref: '#/components/schemas/ManufacturerAliasRow'

    ManufacturerList:
      type: object
      description: Manufacturer list.
      required:
        - mf
      properties:
        mf:
          type: array
          items:
            $ref: '#/components/schemas/ManufacturerListRow'

    ManufacturerListRow:
      type: object
      required:
        - i
        - ds
        - da
        - dbi
      properties:
        i:
          type: integer
          description: Index (row id within this response).
          example: 193
        ds:
          type: string
          description: Standard description — brand name in upper case.
          example: TOYOTA
        da:
          type: string
          description: Adapted description — brand name in upper case, stripped of special characters.
          example: TOYOTA
        dbi:
          type: integer
          description: Database index in FAPI (the stable key used to address this manufacturer in other endpoints).
          example: 111
        oe:
          type: boolean
          description: >-
            Present and `true` when the brand is a vehicle manufacturer — of cars, trucks,
            buses, agricultural or construction machinery: its part numbers are original (OE)
            numbers, and a cross to one of them is the original, not an analog. Absent for
            parts brands, including a parts brand that shares its name with a vehicle make.

    ManufacturerAliasRow:
      type: object
      description: Alternative name for a manufacturer.
      required:
        - mfi
        - da
      properties:
        mfi:
          type: integer
          description: Manufacturer index this alias points to.
        da:
          type: string
          description: Adapted alias text (upper case, no special characters).

    PartRef:
      type: object
      description: One article — a brand's part number.
      required:
        - mfi
        - ds
        - n
        - ns
      properties:
        mfi:
          type: integer
          description: Database index of the brand (`dbi` of `/manufacturerList`).
        ds:
          type: string
          description: Brand name.
        n:
          type: string
          description: Part number as written.
        ns:
          type: string
          description: Standardised part number.
        d:
          type: string
          description: The part's name in the catalog, when it has one.
        oe:
          type: boolean
          description: Present and `true` when the brand is a vehicle manufacturer.

    PartLink:
      allOf:
        - $ref: '#/components/schemas/PartRef'
        - type: object
          required:
            - rp
            - rm
          properties:
            rp:
              type: integer
              description: Ratings for the link.
            rm:
              type: integer
              description: Ratings against the link.
            mfc:
              type: boolean
              description: Present and `true` when the manufacturer itself vouches for the link.

    PartCard:
      type: object
      description: The card of one article, or the candidates a number alone has to be narrowed from.
      required:
        - candidates
      properties:
        part:
          $ref: '#/components/schemas/PartRef'
        status:
          type: string
          enum: [current, replaced]
          description: Whether the part is still the current number or has been replaced.
        current:
          $ref: '#/components/schemas/PartRef'
        replacedBy:
          type: array
          items:
            $ref: '#/components/schemas/PartLink'
        replaces:
          type: array
          items:
            $ref: '#/components/schemas/PartLink'
        oe:
          type: array
          items:
            $ref: '#/components/schemas/PartLink'
        analogs:
          type: array
          items:
            $ref: '#/components/schemas/PartLink'
        candidates:
          type: array
          description: The articles the number names; one when the card is answered, several when a brand is needed, none when nothing is known.
          items:
            $ref: '#/components/schemas/PartRef'

    AnalogListResponse:
      type: object
      description: |
        Composite cross-reference response — manufacturers, products, analog
        links, and messages. `mfi` + `.` + `ns` identifies a part exactly;
        `mfai` + `.` + `nsa` identifies a cross exactly.
      required:
        - manufacturerList
        - productList
        - analogList
        - messageList
      properties:
        manufacturerList:
          $ref: '#/components/schemas/ManufacturerList'
        productList:
          $ref: '#/components/schemas/ProductList'
        analogList:
          $ref: '#/components/schemas/AnalogList'
        messageList:
          $ref: '#/components/schemas/MessageList'

    ProductList:
      type: object
      description: List of parts.
      required:
        - p
      properties:
        p:
          type: array
          items:
            $ref: '#/components/schemas/ProductListRow'

    ProductListRow:
      type: object
      required:
        - i
        - mfi
        - ns
        - n
        - d
        - sr
        - dbi
        - upd
      properties:
        i:
          type: integer
          description: Index (row id within this response).
        mfi:
          type: integer
          description: Manufacturer index — foreign key to ManufacturerListRow.i.
        ns:
          type: string
          description: Standardised number — article number with special characters removed.
        n:
          type: string
          description: Article number as printed on the part.
        d:
          type: string
          description: Part description.
        sr:
          type: integer
          description: Aggregate confidence rating from all sources — sum of positive and negative source ratings across cross-references involving this part.
        dbi:
          type: integer
          description: Database index in FAPI.
        upd:
          type: integer
          format: int64
          description: Last updated, Unix timestamp in milliseconds.

    BarcodeListResponse:
      type: object
      description: |
        The code as it was read, then the shape of `AnalogListResponse`: manufacturers and
        the parts the barcode identifies. `analogList` is always empty — ask `/analogList`
        for a part's cross-references.
      required:
        - barcode
        - manufacturerList
        - productList
        - analogList
        - messageList
      properties:
        barcode:
          $ref: '#/components/schemas/BarcodeRow'
        manufacturerList:
          $ref: '#/components/schemas/ManufacturerList'
        productList:
          type: object
          required:
            - p
          properties:
            p:
              type: array
              items:
                $ref: '#/components/schemas/BarcodeProductRow'
        analogList:
          $ref: '#/components/schemas/AnalogList'
        messageList:
          $ref: '#/components/schemas/MessageList'

    BarcodeRow:
      type: object
      description: A barcode, written the way its format writes it.
      required:
        - c
        - tp
        - gtin
      properties:
        c:
          type: string
          description: The digits, as the format writes them.
          example: "4019064140399"
        tp:
          type: string
          enum: [EAN-13, EAN-8, UPC-A, GTIN-14]
          description: |
            The format. It is a property of the number itself, not of how it was typed: a
            UPC-A typed as a 13-digit EAN is a UPC-A.
        gtin:
          type: string
          description: The 14-digit GTIN — one key for every format, the form to keep and compare.
          example: "04019064140399"

    ProductBarcodeListResponse:
      type: object
      description: The barcodes of a part, the most reliable first.
      required:
        - barcodeList
        - messageList
      properties:
        barcodeList:
          type: object
          required:
            - b
          properties:
            b:
              type: array
              items:
                $ref: '#/components/schemas/BarcodeRow'
        messageList:
          $ref: '#/components/schemas/MessageList'

    BarcodeProductRow:
      type: object
      description: |
        A part a barcode identifies. A part FAPI's catalog holds carries the fields of
        `ProductListRow`; a part only the barcode data knows carries its manufacturer and
        article number alone, and no `d`, `sr`, `dbi` or `upd`.
      required:
        - i
        - mfi
        - ns
        - n
      properties:
        i:
          type: integer
          description: Index (row id within this response).
        mfi:
          type: integer
          description: Manufacturer index — foreign key to ManufacturerListRow.i.
        ns:
          type: string
          description: Standardised number — article number with special characters removed.
        n:
          type: string
          description: Article number as printed on the part; the standardised one when no other is known.
        d:
          type: string
          description: Part description. Only for a part in FAPI's catalog.
        sr:
          type: integer
          description: As in `ProductListRow`. Only for a part in FAPI's catalog.
        dbi:
          type: integer
          description: Database index in FAPI. Only for a part in FAPI's catalog.
        upd:
          type: integer
          format: int64
          description: Last updated, Unix timestamp in milliseconds. Only for a part in FAPI's catalog.

    AnalogList:
      type: object
      description: Cross-reference links between parts.
      required:
        - a
      properties:
        a:
          type: array
          items:
            $ref: '#/components/schemas/AnalogListRow'

    AnalogListRow:
      type: object
      required:
        - i
        - _int
        - rm
        - rp
        - pi
        - mfi
        - ns
        - pai
        - mfai
        - nsa
      properties:
        i:
          type: integer
          description: Index (row id within this response).
        pri:
          type: integer
          description: Field present in API response; meaning not yet documented.
        si:
          type: integer
          description: Field present in API response; meaning not yet documented.
        di:
          type: integer
          description: Field present in API response; meaning not yet documented.
        _int:
          type: integer
          description: "Vote marker if you have voted or submitted this cross. Values: -1 = not set; 1 = cross is BROKEN; 0 = cross is VERIFIED."
        rm:
          type: integer
          description: Rating minus — count of negative ratings from sources (this cross marked as BROKEN).
        rp:
          type: integer
          description: Rating plus — count of positive ratings from sources (this cross marked as VERIFIED).
        pi:
          type: integer
          description: Reference to the source PART (foreign key to productList.i).
        mfi:
          type: integer
          description: Manufacturer index — reference to the source BRAND (foreign key to manufacturerList.i).
        ns:
          type: string
          description: Standardised number of the source part.
        pai:
          type: integer
          description: Reference to the CROSS PART (foreign key to productList.i).
        mfai:
          type: integer
          description: Manufacturer index of the cross — reference to the CROSS BRAND (foreign key to manufacturerList.i).
        nsa:
          type: string
          description: Standardised number of the cross part.
        rpl:
          type: boolean
          description: >-
            Present and `true` when the cross part supersedes the source part: the source
            number is discontinued and the cross number is its replacement, said by the
            manufacturer or by a catalogue. Absent otherwise.
        prev:
          type: boolean
          description: >-
            Present and `true` when the cross part is a former number of the source part
            (the mirror of `rpl`). Absent otherwise.
        mfc:
          type: boolean
          description: >-
            Present and `true` when the manufacturer itself vouches for this cross — one of
            the positive ratings is the manufacturer's own. Absent otherwise.

    ParameterListResponse:
      type: object
      description: Wrapper around the list of part attributes.
      required:
        - p
      properties:
        p:
          type: array
          items:
            $ref: '#/components/schemas/ParameterListRow'

    ParameterListRow:
      type: object
      required:
        - key
        - value
      properties:
        key:
          type: string
          example: "Weight, g"
        value:
          type: string
          example: "4210"

    CarListResponse:
      type: object
      description: Vehicle applicability — manufacturers, models, and modifications a part fits.
      required:
        - manufacturerList
        - modelList
        - modificationList
      properties:
        manufacturerList:
          $ref: '#/components/schemas/ManufacturerList'
        modelList:
          $ref: '#/components/schemas/ApplicabilityModelList'
        modificationList:
          $ref: '#/components/schemas/ApplicabilityModificationList'

    ApplicabilityModelList:
      type: object
      required:
        - m
      properties:
        m:
          type: array
          items:
            $ref: '#/components/schemas/ApplicabilityModelRow'

    ApplicabilityModelRow:
      type: object
      description: Vehicle model row as returned by productApplicabilityList (compact form).
      required:
        - i
        - mfi
        - d
      properties:
        i:
          type: integer
          description: Index (row id within this response).
        dbi:
          type: integer
          format: int64
          description: >-
            Catalog model id — pass it as `mi` to /catalogList/dt/modificationList to get the
            details (power, capacity, engine code) of this model's modifications.
        mfi:
          type: integer
          description: Manufacturer index — foreign key to ManufacturerListRow.i.
        d:
          type: string
          description: Model description.

    ApplicabilityModificationList:
      type: object
      required:
        - m
      properties:
        m:
          type: array
          items:
            $ref: '#/components/schemas/ApplicabilityModificationRow'

    ApplicabilityModificationRow:
      type: object
      description: Vehicle modification row as returned by productApplicabilityList (compact form).
      required:
        - i
        - mfi
        - mdi
        - d
        - cb
      properties:
        i:
          type: integer
          description: Index (row id within this response).
        dbi:
          type: integer
          format: int64
          description: >-
            Catalog modification id. Several modifications of one model can share a description
            and a production period; this id tells them apart. Its details are the
            /catalogList/dt/modificationList row with the same `dbi`, requested with `mi` = the
            `dbi` of the model this row's `mdi` points to.
        mfi:
          type: integer
          description: Manufacturer index — foreign key to ManufacturerListRow.i.
        mdi:
          type: integer
          description: Model index — foreign key to model row.
        d:
          type: string
          description: Modification description.
        cb:
          type: integer
          format: int64
          description: >-
            Construction begin, Unix timestamp in milliseconds: the first day of the month
            production began, at midnight Moscow time.
        ce:
          type: integer
          format: int64
          description: >-
            Construction end, Unix timestamp in milliseconds: the first day of the month
            production ended, at midnight Moscow time. Absent while still in production.

    ModelList:
      type: object
      required:
        - m
      properties:
        m:
          type: array
          items:
            $ref: '#/components/schemas/ModelListRow'

    ModelListRow:
      type: object
      description: Vehicle model row from the catalog endpoint.
      required:
        - i
        - dbi
        - mfi
        - d
        - fd
        - cb
        - ce
      properties:
        i:
          type: integer
          description: Index (row id within this response).
          example: 4846
        dbi:
          type: integer
          description: Database index in FAPI (stable key for this model).
          example: 4846
        mfi:
          type: integer
          description: Manufacturer index — foreign key to ManufacturerListRow.i.
          example: 111
        d:
          type: string
          description: Short description.
          example: "CAMRY sedan (_V3_)"
        fd:
          type: string
          description: Full description (typically brand + model).
          example: "TOYOTA CAMRY sedan (_V3_)"
        cb:
          type: integer
          format: int64
          description: Construction begin date, Unix timestamp in milliseconds.
          example: 996624000000
        ce:
          type: integer
          format: int64
          description: Construction end date, Unix timestamp in milliseconds.
          example: 1162339200000

    ModificationList:
      type: object
      required:
        - m
      properties:
        m:
          type: array
          items:
            $ref: '#/components/schemas/ModificationListRow'

    ModificationListRow:
      type: object
      description: Vehicle modification row from the catalog endpoint.
      required:
        - i
        - dbi
        - mdi
        - d
        - fd
        - cb
        - ce
        - engineType
        - engineCode
        - power
        - capacity
        - driveType
        - bodyType
        - p
      properties:
        p:
          type: object
          description: Parent reference (structure varies; not enforced by this schema).
          additionalProperties: true
        i:
          type: integer
          description: Index (row id within this response).
          example: 9
        dbi:
          type: integer
          description: Database index in FAPI (stable key for this modification).
          example: 124170
        mdi:
          type: integer
          description: Model index — foreign key to ModelListRow.i.
          example: 4846
        d:
          type: string
          description: Short description.
          example: "2.4 (ACV30)"
        fd:
          type: string
          description: Full description (brand + model + modification).
          example: "TOYOTA CAMRY sedan (_V3_) 2.4 (ACV30)"
        cb:
          type: integer
          format: int64
          description: Construction begin date, Unix timestamp in milliseconds.
          example: 999302400000
        ce:
          type: integer
          format: int64
          description: Construction end date, Unix timestamp in milliseconds.
          example: 1136073600000
        engineType:
          type: string
          description: Engine type.
          example: "Petrol engine"
        engineCode:
          type: string
          description: Engine code.
          example: "2AZ-FE"
        power:
          type: string
          description: Engine power.
          example: "117"
        capacity:
          type: string
          description: Engine displacement.
          example: "2.4 l"
        driveType:
          type: string
          description: Drive type.
          example: "Front-wheel drive"
        bodyType:
          type: string
          description: Body type.
          example: "sedan"

    TreeNode:
      type: object
      description: Node in the part-group tree for a vehicle modification.
      required:
        - i
        - d
        - mi
        - pi
        - searchtreeid
      properties:
        i:
          type: integer
          description: Node identifier.
        d:
          type: string
          description: Node description (part-group name).
        mi:
          type: integer
          description: Modification index this node belongs to.
        pi:
          type: integer
          description: Parent node identifier (0 for root nodes).
        searchtreeid:
          type: integer
          description: Identifier of the search tree this node is rooted in.

    CatalogProductRow:
      type: object
      description: Part row returned for a (node, modification) pair in the vehicle catalog.
      required:
        - mfi
        - mfd
        - ns
        - n
        - d
      properties:
        mfi:
          type: integer
          description: Manufacturer index — foreign key to ManufacturerListRow.i.
        mfd:
          type: string
          description: Manufacturer description (brand name).
        ns:
          type: string
          description: Standardised number — article number with special characters removed.
        n:
          type: string
          description: Article number as printed on the part.
        d:
          type: string
          description: Part description.

    OemRow:
      type: object
      description: |
        Original number row — the `CatalogProductRow` shape plus what only this
        route knows about a number: a fitment caveat and how many data
        suppliers stand behind it.
      required:
        - mfd
        - ns
        - n
        - d
      properties:
        mfi:
          type: integer
          description: Manufacturer index in FAPI. Absent when the brand is unknown to FAPI — the row is returned anyway.
          example: 11822
        mfd:
          type: string
          description: Brand the number is published under.
          example: TOYOTA
        ns:
          type: string
          description: Standardised number — stable; match on this one.
          example: "4420012750"
        n:
          type: string
          description: Number as the maker publishes it.
          example: "44200-12750"
        d:
          type: string
          description: Part description.
        fit:
          type: string
          description: |
            Present only when none of the links to this number is a direct
            replacement: `kitPart` — an element of a kit; `component` — one
            component, not the whole part; `fewerParts` / `moreParts` — the
            supply is smaller / larger than the original set; `needsFitting` —
            replaceable with fitting; `checkVehicle` — check the exact vehicle;
            `separateSupply` — replaceable, supplied separately. The list is
            closed and will not change without notice.
          enum:
            - kitPart
            - component
            - fewerParts
            - moreParts
            - needsFitting
            - checkVehicle
            - separateSupply
        sources:
          type: integer
          minimum: 1
          description: |
            How many independent data suppliers publish this number as an
            original of the vehicle's make — or of a platform relative of it,
            whichever publishes the number wider. The more, the better
            established the number: a second spelling or a rare variant of a
            part carries fewer than the number most catalogs know the part by.
            Rows of one brand come widest first. Absent when the source
            cannot say, which is not a zero.
          example: 63

    VinResponse:
      type: object
      additionalProperties: true
      description: |
        The vehicle a VIN decodes to, exactly as the VIN decoder describes it.
        The decoder owns this object: a field may be added without notice, so
        read the ones you need and ignore the rest. Optional fields are
        omitted when the decoder knows no value.

        `country` is an ISO 3166-1 alpha-2 code. `body_type`, `drive_type`,
        `transmission`, `fuel_type`, `engine_type` and `steering` are codes of
        the closed sets listed below, the same in every language: translate
        them for your screen, or pass `lang` and read `labels`. A value the
        decoder cannot reduce to a code is omitted, never passed through as
        text.
      required:
        - vin
        - country
        - manufacturer
        - model_year
        - confidence
      properties:
        vin:
          type: string
          example: WVWZZZ1KZ9W123456
        country:
          type: string
          pattern: '^([A-Z]{2})?$'
          description: |
            Country of manufacture by the VIN's first three characters, as an
            ISO 3166-1 alpha-2 code; an empty string when it is not known.
          example: DE
        manufacturer:
          type: string
          description: Manufacturer, by the VIN's first three characters.
        brand_name:
          type: string
          example: VW
        model_name:
          type: string
          description: |
            The model's name for the market of the car's country of
            manufacture, when the catalog names the model for that market;
            otherwise the name most markets share. The catalog may keep one
            model under several names, one per market, so this can differ from
            `dt_card.model.name`, the catalog's own name for every market.
            With `lang`: that same market's name in the language; where the
            catalog has none in it, in English; otherwise as without `lang`.
          example: GOLF VI (5K1)
        modification_name:
          type: string
          description: With `lang`, in that language by the same rule as `model_name`.
          example: 1.4 TSI
        model_year:
          type: integer
          description: Model year from the VIN's 10th character; 0 when it cannot be read.
          example: 2009
        production_start:
          type: string
          pattern: '^\d{4}-\d{2}$'
          description: First month the modification was produced, `YYYY-MM`.
          example: "2008-10"
        production_end:
          type: string
          pattern: '^\d{4}-\d{2}$'
          description: Last month the modification was produced, `YYYY-MM`; absent while it is still in production.
          example: "2012-11"
        body_type:
          type: string
          enum: [sedan, hatchback, wagon, coupe, hardtop, convertible, targa, suv, pickup, van, minivan, bus, chassis, motorcycle]
          example: hatchback
        doors:
          type: integer
          description: Number of doors.
          example: 5
        steering:
          type: string
          enum: [LHD, RHD]
          description: Left-hand or right-hand drive.
          example: LHD
        engine_code:
          type: string
          description: The engine code read for this VIN.
          example: CAXA
        engine_type:
          type: string
          enum: [petrol, diesel, electric, hybrid, full_hybrid, mild_hybrid, plugin_hybrid, range_extender, wankel]
          description: How the engine works.
          example: petrol
        fuel_type:
          type: string
          enum: [petrol, diesel, electric, hybrid, diesel_hybrid, lpg, cng, petrol_lpg, petrol_cng, hydrogen, ethanol, flexfuel]
          description: |
            `hybrid` — petrol and electric; `diesel_hybrid` — diesel and
            electric; `petrol_lpg`, `petrol_cng` — a factory bi-fuel car;
            `flexfuel` — petrol or ethanol.
          example: petrol
        drive_type:
          type: string
          enum: [FWD, RWD, AWD]
          example: FWD
        displacement_cc:
          type: integer
          example: 1390
        power_kw:
          type: integer
          example: 90
        power_hp:
          type: integer
          description: Power in metric horsepower.
          example: 122
        transmission:
          type: string
          enum: [manual, automatic, cvt, dct, amt]
          description: |
            `manual`; `automatic` — a torque-converter automatic; `cvt` —
            stepless; `dct` — dual-clutch; `amt` — a manual gearbox shifted by
            a robot.
          example: manual
        gearbox_code:
          type: string
          description: The maker's gearbox code, as read for this VIN.
          example: SGR
        gears:
          type: integer
          description: Number of forward gears.
          example: 6
        production_date:
          type: string
          format: date
          description: Date the vehicle was built.
        engine_number:
          type: string
          description: Serial number of the engine (not the engine code).
        body_color:
          type: string
          description: The maker's body paint code, as is.
        interior_color:
          type: string
          description: The maker's interior trim code, as is.
        dt_manufacturer_id:
          type: integer
          description: Catalog manufacturer id; absent when not matched.
          example: 121
        dt_model_id:
          type: integer
          description: Catalog model id; absent when not matched.
          example: 7873
        dt_type_id:
          type: integer
          description: |
            Catalog modification key; absent when not matched. Pass it to
            `/catalogList/dt/treeList` as `mi`, and to
            `/catalogList/dt/productList` and `/catalogList/dt/productListOEM`
            as `modi`.
          example: 29992
        dt_card:
          $ref: '#/components/schemas/VinCatalogCard'
        labels:
          type: object
          additionalProperties: true
          description: |
            Present only when the request named a `lang`: for each of the six
            coded fields the answer has, that code's name in the language. A
            code the catalog has no text for in the language is named in
            English; with none in English either, its key is absent. The
            wording of a label may be improved without notice — compare and
            filter by the codes, show the labels.
          properties:
            country:
              type: string
              example: Rusya
            body_type:
              type: string
              example: Sedan
            drive_type:
              type: string
              example: Önden tahrik
            transmission:
              type: string
              example: Mekanik şanzıman
            fuel_type:
              type: string
              example: Benzin
            engine_type:
              type: string
              example: Benzinli motor
        confidence:
          type: string
          enum: [exact, partial, brand_only, unknown]
          description: |
            How far the vehicle was identified: `exact` — down to the
            modification; `partial` — model; `brand_only` — make only;
            `unknown` — nothing. `exact` is the depth of the vehicle's
            identification, not of a part's: the catalog routes answer for
            the modification, with no side of installation, factory options
            or build date — see `/catalogList/dt/productListOEM`.

    VinCatalogCard:
      type: object
      description: |
        What the vehicle catalog says about the matched ids. A level is
        present only when its id was matched; a value the catalog leaves
        empty is omitted. Absent when nothing was matched, or when the
        catalog could not be read — the catalog ids alongside it may still be
        there. Its text is the catalog's own: `type.engine_type`,
        `type.drive_type` and `type.body_type` are the catalog's words in
        Russian, not the codes of the fields of the same names above.
      properties:
        manufacturer:
          type: object
          required: [id]
          properties:
            id:
              type: integer
              example: 121
            name:
              type: string
              example: VW
        model:
          type: object
          required: [id]
          properties:
            id:
              type: integer
              example: 7873
            manufacturer_id:
              type: integer
            name:
              type: string
              example: GOLF VI (5K1)
            from:
              type: integer
              description: Production start, YYYYMM.
              example: 200810
            to:
              type: integer
              description: Production end, YYYYMM.
              example: 201412
        type:
          type: object
          required: [id]
          properties:
            id:
              type: integer
              description: Modification key.
              example: 29992
            model_id:
              type: integer
            name:
              type: string
              example: 1.4 TSI
            from:
              type: integer
              description: Production start, YYYYMM.
            to:
              type: integer
              description: Production end, YYYYMM.
            kw:
              type: integer
              example: 90
            ps:
              type: integer
              example: 122
            lit:
              type: integer
              description: Displacement in litres × 100.
              example: 140
            engine_type:
              type: string
            drive_type:
              type: string
            body_type:
              type: string
            engine_code:
              type: string
              example: CAXA

    UsageVin:
      type: object
      description: |
        Your own prepaid balance for VIN decoding, as the VIN decoder reports it. Never
        charged, and answered even at zero. `balance_kopecks` and `lots` are present exactly
        when `st` is `ok`. Money is integer kopecks throughout. The whole object is absent
        when this host does not decode VINs.
      required:
        - st
      properties:
        st:
          type: string
          enum: [ok, no_access, unavailable]
          description: |
            `ok` — the balance follows; `no_access` — your key does not open VIN decoding;
            `unavailable` — the VIN decoder could not be read in time, ask again later.
          example: ok
        balance_kopecks:
          type: integer
          format: int64
          description: Total spendable balance, in kopecks — the sum of all live lots below.
          example: 155000
        lots:
          type: array
          description: Live credits behind the total, in the order they will be spent.
          items:
            $ref: '#/components/schemas/VinBalanceLot'

    VinBalanceLot:
      type: object
      required:
        - tariff
        - remaining_kopecks
        - expires_at
      properties:
        tariff:
          type: string
          description: The tariff this lot was credited under.
          example: pack2000
        remaining_kopecks:
          type: integer
          format: int64
          description: What is left of this lot, in kopecks.
          example: 150000
        expires_at:
          type: string
          format: date-time
          nullable: true
          description: When this lot stops counting; null when it never expires.

    UsageResponse:
      type: object
      required:
        - account
      properties:
        account:
          $ref: '#/components/schemas/UsageAccount'
        vin:
          $ref: '#/components/schemas/UsageVin'

    UsageAccount:
      type: object
      description: |
        Your own billing position at `ts`. Money is integer kopecks throughout; credits are
        whole numbers. Without a plan in force (no billing account yet, or one not started)
        only `ts`, `st` and `d` are present. With a plan, `ts st pl ps fee u pr b bp` are
        always present and `0` is a real value — a ceiling's absence is `inc` and `rem` being
        absent, never `0` standing in for "unlimited".
      required:
        - ts
        - st
      properties:
        ts:
          type: string
          format: date-time
          description: The snapshot's own moment — every other field here is at least this fresh.
          example: "2026-10-15T10:00:00+03:00"
        st:
          type: string
          enum: [unbilled, allowed, denied_unpaid, denied_quota, denied_balance]
          description: The gate's verdict right now, were a priced request made this instant.
          example: allowed
        ac:
          type: string
          enum: [top_up, change_plan]
          description: Present only when `st` is a denial — what would clear it.
          example: top_up
        d:
          type: string
          description: |
            Russian, for a partner to read. On a denial, the exact words the `402` itself
            would carry; with no plan in force, why nothing is charged. Absent otherwise.
          example: "пакет запросов исчерпан, а тариф не продаёт запросы сверх пакета; смените тариф: https://fapi.iisis.ru/pay/pay-type-list"
        ob:
          type: boolean
          description: |
            Present only while this node observes rather than enforces, alongside a plan:
            `true` means a denial above is announced and not yet applied — the request it
            describes is still served.
          example: true
        pl:
          type: string
          description: Plan code, present once a plan is in force.
          example: trial
        ps:
          type: string
          format: date-time
          description: Start of the current period (for a plan granted once, when it began).
          example: "2026-09-25T00:00:00+03:00"
        pe:
          type: string
          format: date-time
          description: |
            When the next period starts (exclusive). Absent for a plan granted once with no
            renewal (a trial).
          example: "2026-11-01T00:00:00+03:00"
        fee:
          type: integer
          format: int64
          description: Subscription fee per period, in kopecks; `0` = no fee.
          example: 50000
        fp:
          type: boolean
          description: |
            Present only when `fee` is more than `0`. `false` together with `st: allowed`
            means the fee is pending: covered by the balance and already served, posted to
            the ledger at the next settlement run rather than there already.
          example: true
        inc:
          type: integer
          format: int64
          description: The plan's package, in credits. Absent when the plan has no ceiling.
          example: 100
        u:
          type: integer
          format: int64
          description: Credits used in the current period, as the gate's own estimate.
          example: 70
        rem:
          type: integer
          format: int64
          description: Package credits left; present only alongside `inc`.
          example: 30
        pr:
          type: integer
          format: int64
          description: Price of one credit beyond the package, in kopecks; `0` = overage is not sold.
          example: 2
        b:
          type: integer
          format: int64
          description: Posted balance, in kopecks — the sum of the ledger.
          example: 100000
        bp:
          type: integer
          format: int64
          description: |
            Balance available to spend: `b` minus a pending fee and overage already spent but
            not yet posted. Never negative.
          example: 100000

    MessageList:
      type: object
      required:
        - m
      properties:
        m:
          type: array
          items:
            $ref: '#/components/schemas/MessageListRow'

    MessageListRow:
      type: object
      required:
        - i
        - l
        - d
      properties:
        i:
          type: integer
          description: Message index.
        l:
          type: integer
          description: Severity level.
        d:
          type: string
          description: Message text.
          example: "Message text"