openapi: 3.1.0
info:
  title: crates.io Sparse Index API
  description: >
    The crates.io sparse index serves per-crate metadata files over HTTP
    rather than requiring a clone of the legacy crates.io-index Git
    repository. Cargo uses the sparse protocol by default since Rust 1.70
    (June 2023). The index also publishes a config.json document at the root
    and supports HTTP cache validation via ETag and Last-Modified.
  version: v1
  contact:
    name: crates.io Team
    email: help@crates.io
    url: https://crates.io
  license:
    name: Cargo Documentation (MIT/Apache-2.0)
    url: https://doc.rust-lang.org/cargo/reference/registry-index.html

servers:
  - url: https://index.crates.io
    description: crates.io Sparse Index (sparse+https://index.crates.io/)

tags:
  - name: Index
    description: Per-crate index metadata files served over HTTP
  - name: Config
    description: Registry configuration document

paths:
  /config.json:
    get:
      summary: Get Registry Configuration
      description: >
        Returns the registry configuration document. Must be the first request
        a sparse-index client makes; controls download URL templates,
        publishing endpoint, and authentication requirements.
      operationId: getRegistryConfig
      tags:
        - Config
      responses:
        '200':
          description: The registry configuration document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistryConfig'
              example:
                dl: https://crates.io/api/v1/crates
                api: https://crates.io
                auth-required: false
  /1/{crate}:
    get:
      summary: Get Index For One-Character Crate
      description: Returns the newline-delimited JSON index entries for a single-character crate name (e.g. /1/a).
      operationId: getIndexOneChar
      tags:
        - Index
      parameters:
        - name: crate
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 1
      responses:
        '200':
          description: Newline-delimited JSON index entries.
          content:
            text/plain:
              schema:
                type: string
        '304':
          description: Not modified (ETag/If-None-Match match).
        '404':
          description: Crate not found.
  /2/{crate}:
    get:
      summary: Get Index For Two-Character Crate
      description: Returns the newline-delimited JSON index entries for a two-character crate name (e.g. /2/io).
      operationId: getIndexTwoChar
      tags:
        - Index
      parameters:
        - name: crate
          in: path
          required: true
          schema:
            type: string
            minLength: 2
            maxLength: 2
      responses:
        '200':
          description: Newline-delimited JSON index entries.
          content:
            text/plain:
              schema:
                type: string
        '304':
          description: Not modified.
        '404':
          description: Crate not found.
  /3/{first}/{crate}:
    get:
      summary: Get Index For Three-Character Crate
      description: Returns the newline-delimited JSON index entries for a three-character crate name. Path uses the first character as a directory (e.g. /3/r/rng).
      operationId: getIndexThreeChar
      tags:
        - Index
      parameters:
        - name: first
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 1
        - name: crate
          in: path
          required: true
          schema:
            type: string
            minLength: 3
            maxLength: 3
      responses:
        '200':
          description: Newline-delimited JSON index entries.
          content:
            text/plain:
              schema:
                type: string
        '304':
          description: Not modified.
        '404':
          description: Crate not found.
  /{first_two}/{second_two}/{crate}:
    get:
      summary: Get Index For Four-Plus-Character Crate
      description: >
        Returns the newline-delimited JSON index entries for a crate with four
        or more characters. Path uses the first two characters as the first
        directory and characters three and four as the second directory
        (e.g. /se/rd/serde for "serde", /to/ki/tokio for "tokio").
      operationId: getIndexLong
      tags:
        - Index
      parameters:
        - name: first_two
          in: path
          required: true
          schema:
            type: string
            minLength: 2
            maxLength: 2
        - name: second_two
          in: path
          required: true
          schema:
            type: string
            minLength: 2
            maxLength: 2
        - name: crate
          in: path
          required: true
          schema:
            type: string
            minLength: 4
      responses:
        '200':
          description: Newline-delimited JSON index entries.
          content:
            text/plain:
              schema:
                type: string
              example: |
                {"name":"serde","vers":"1.0.0","deps":[],"cksum":"...","features":{},"yanked":false,"v":2}
                {"name":"serde","vers":"1.0.1","deps":[],"cksum":"...","features":{},"yanked":false,"v":2}
        '304':
          description: Not modified.
        '404':
          description: Crate not found.

components:
  schemas:
    RegistryConfig:
      type: object
      required:
        - dl
      properties:
        dl:
          type: string
          description: Download URL template for .crate files. Supports {crate}, {version}, {prefix}, {lowerprefix}, and {sha256-checksum} markers.
        api:
          type: string
          description: Base URL of the Web API used for publishing, yanking, owners, and search.
        auth-required:
          type: boolean
          description: Whether all index and download operations require an Authorization header.
    IndexEntry:
      type: object
      required:
        - name
        - vers
        - deps
        - cksum
        - features
        - yanked
      properties:
        name:
          type: string
        vers:
          type: string
        deps:
          type: array
          items:
            $ref: '#/components/schemas/IndexDep'
        cksum:
          type: string
          description: SHA-256 of the .crate file.
        features:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
        features2:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
        yanked:
          type: boolean
        links:
          type: string
          nullable: true
        v:
          type: integer
          description: Index format version (1 or 2).
        rust_version:
          type: string
          nullable: true
    IndexDep:
      type: object
      required:
        - name
        - req
      properties:
        name:
          type: string
        req:
          type: string
          description: Semver requirement string.
        features:
          type: array
          items:
            type: string
        optional:
          type: boolean
        default_features:
          type: boolean
        target:
          type: string
          nullable: true
        kind:
          type: string
          enum:
            - normal
            - build
            - dev
        registry:
          type: string
          nullable: true
        package:
          type: string
          nullable: true