Clojars REST API

{
  "openapi": "3.0.3",
  "info": {
    "title": "Clojars REST API",
    "description": "A RESTful API for searching and retrieving Clojure artifact metadata, user profiles, group memberships, and release feeds from the Clojars community repository. Read endpoints are public; write/deploy operations require a deploy token.",
    "version": "1.0.0",
    "contact": {
      "name": "Clojars Team",
      "email": "[email protected]",
      "url": "https://github.com/clojars"
    },
    "license": {
      "name": "Eclipse Public License",
      "url": "https://github.com/clojars/clojars-web/blob/main/COPYING"
    },
    "termsOfService": "https://clojars.org/"
  },
  "servers": [
    {
      "url": "https://clojars.org",
      "description": "Clojars production server"
    }
  ],
  "externalDocs": {
    "description": "Clojars API Wiki",
    "url": "https://github.com/clojars/clojars-web/wiki/Data"
  },
  "tags": [
    {
      "name": "Users",
      "description": "Operations related to Clojars user profiles and group memberships"
    },
    {
      "name": "Groups",
      "description": "Operations related to Clojars artifact groups"
    },
    {
      "name": "Artifacts",
      "description": "Operations related to Clojars artifacts and releases"
    },
    {
      "name": "Search",
      "description": "Search operations across the Clojars artifact index"
    },
    {
      "name": "Feeds",
      "description": "Release feed and bulk data operations"
    }
  ],
  "paths": {
    "/api/users/{username}": {
      "get": {
        "operationId": "getUser",
        "summary": "Get User",
        "description": "Returns the list of groups the specified user belongs to.",
        "tags": ["Users"],
        "parameters": [
          {
            "name": "username",
            "in": "path",
            "required": true,
            "description": "The Clojars username to look up.",
            "schema": {
              "type": "string",
              "example": "ato"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "User profile with group memberships.",
            "headers": {
              "Content-Type": {
                "schema": {
                  "type": "string"
                },
                "description": "application/json, application/edn, application/yaml, or application/transit+json depending on Accept header"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                },
                "example": {
                  "user": "ato",
                  "groups": ["net.cgrand", "org.clojure"]
                }
              }
            }
          },
          "404": {
            "description": "User not found."
          }
        }
      }
    },
    "/api/groups/{group_name}": {
      "get": {
        "operationId": "getGroupArtifacts",
        "summary": "Get Group Artifacts",
        "description": "Returns all artifacts belonging to the specified group.",
        "tags": ["Groups"],
        "parameters": [
          {
            "name": "group_name",
            "in": "path",
            "required": true,
            "description": "The group identifier (e.g. org.clojure).",
            "schema": {
              "type": "string",
              "example": "org.clojure"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of artifacts in the group.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ArtifactSummary"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Group not found."
          }
        }
      }
    },
    "/api/artifacts/{artifact_name}": {
      "get": {
        "operationId": "getArtifact",
        "summary": "Get Artifact",
        "description": "Returns metadata for a specific artifact, including latest version, downloads, dependencies, and licenses.",
        "tags": ["Artifacts"],
        "parameters": [
          {
            "name": "artifact_name",
            "in": "path",
            "required": true,
            "description": "The artifact name (without group prefix).",
            "schema": {
              "type": "string",
              "example": "clojure"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Artifact metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Artifact"
                }
              }
            }
          },
          "404": {
            "description": "Artifact not found."
          }
        }
      }
    },
    "/api/artifacts/{group_name}/{artifact_name}": {
      "get": {
        "operationId": "getArtifactByGroup",
        "summary": "Get Artifact by Group",
        "description": "Returns metadata for a specific artifact within a group namespace.",
        "tags": ["Artifacts"],
        "parameters": [
          {
            "name": "group_name",
            "in": "path",
            "required": true,
            "description": "The group identifier.",
            "schema": {
              "type": "string",
              "example": "org.clojure"
            }
          },
          {
            "name": "artifact_name",
            "in": "path",
            "required": true,
            "description": "The artifact name within the group.",
            "schema": {
              "type": "string",
              "example": "clojure"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Artifact metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Artifact"
                }
              }
            }
          },
          "404": {
            "description": "Artifact not found."
          }
        }
      }
    },
    "/api/release-feed": {
      "get": {
        "operationId": "getReleaseFeed",
        "summary": "Get Release Feed",
        "description": "Returns a paginated feed of releases after a given timestamp. Returns up to 500 releases per page. Paginate using the next_from timestamp from the response.",
        "tags": ["Feeds"],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "ISO 8601 timestamp to start the feed from (e.g. 2024-01-01T00:00:00Z).",
            "schema": {
              "type": "string",
              "format": "date-time",
              "example": "2024-01-01T00:00:00Z"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of releases.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReleaseFeed"
                }
              }
            }
          }
        }
      }
    },
    "/search": {
      "get": {
        "operationId": "searchArtifacts",
        "summary": "Search Artifacts",
        "description": "Searches artifacts by query string. Supports JSON and XML response formats via the format parameter.",
        "tags": ["Search"],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "The search query string.",
            "schema": {
              "type": "string",
              "example": "ring"
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "description": "Response format. Defaults to JSON.",
            "schema": {
              "type": "string",
              "enum": ["json", "xml"],
              "default": "json"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Search results.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResults"
                }
              },
              "application/xml": {
                "schema": {
                  "type": "object",
                  "description": "XML-formatted search results."
                }
              }
            }
          }
        }
      }
    },
    "/all-poms.txt": {
      "get": {
        "operationId": "getAllPoms",
        "summary": "All POMs List",
        "description": "Returns a plain-text list of all POM file paths available in the Clojars repository. Updated hourly.",
        "tags": ["Feeds"],
        "responses": {
          "200": {
            "description": "Plain-text list of POM file paths, one per line.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "example": "net/cgrand/parsley/0.9.3/parsley-0.9.3.pom\norg/clojure/clojure/1.11.1/clojure-1.11.1.pom"
                }
              }
            }
          }
        }
      }
    },
    "/all-jars.clj": {
      "get": {
        "operationId": "getAllJars",
        "summary": "All JARs List",
        "description": "Returns a Leiningen-syntax list of all JAR artifact versions available in the Clojars repository. Updated hourly.",
        "tags": ["Feeds"],
        "responses": {
          "200": {
            "description": "Leiningen-syntax list of all JAR artifact versions.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "example": "[net.cgrand/parsley \"0.9.3\"]\n[org.clojure/clojure \"1.11.1\"]"
                }
              }
            }
          }
        }
      }
    },
    "/stats/all.edn": {
      "get": {
        "operationId": "getDownloadStatistics",
        "summary": "Download Statistics",
        "description": "Returns daily or cumulative download statistics per artifact in EDN format. Statistics are recalculated once daily at 07:00 UTC.",
        "tags": ["Feeds"],
        "responses": {
          "200": {
            "description": "Download statistics in EDN format.",
            "content": {
              "application/edn": {
                "schema": {
                  "type": "string",
                  "description": "EDN-formatted download statistics map keyed by artifact coordinates."
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "description": "A Clojars user profile.",
        "properties": {
          "user": {
            "type": "string",
            "description": "The username.",
            "example": "ato"
          },
          "groups": {
            "type": "array",
            "description": "List of group identifiers the user belongs to.",
            "items": {
              "type": "string"
            },
            "example": ["net.cgrand", "org.clojure"]
          }
        }
      },
      "ArtifactSummary": {
        "type": "object",
        "description": "A summary of a Clojars artifact.",
        "properties": {
          "jar_name": {
            "type": "string",
            "description": "The artifact (JAR) name.",
            "example": "clojure"
          },
          "group_name": {
            "type": "string",
            "description": "The group identifier.",
            "example": "org.clojure"
          },
          "version": {
            "type": "string",
            "description": "The latest released version.",
            "example": "1.11.1"
          },
          "description": {
            "type": "string",
            "description": "A short description of the artifact.",
            "example": "The Clojure programming language"
          }
        }
      },
      "Artifact": {
        "type": "object",
        "description": "Full metadata for a Clojars artifact.",
        "properties": {
          "jar_name": {
            "type": "string",
            "description": "The artifact (JAR) name.",
            "example": "clojure"
          },
          "group_name": {
            "type": "string",
            "description": "The group identifier.",
            "example": "org.clojure"
          },
          "version": {
            "type": "string",
            "description": "The latest released version.",
            "example": "1.11.1"
          },
          "description": {
            "type": "string",
            "description": "A short description of the artifact.",
            "example": "The Clojure programming language"
          },
          "homepage": {
            "type": "string",
            "format": "uri",
            "description": "The project homepage URL.",
            "example": "https://clojure.org"
          },
          "licenses": {
            "type": "array",
            "description": "List of licenses for the artifact.",
            "items": {
              "$ref": "#/components/schemas/License"
            }
          },
          "downloads": {
            "type": "integer",
            "description": "Total number of downloads.",
            "example": 1234567
          },
          "recent_versions": {
            "type": "array",
            "description": "List of recent versions.",
            "items": {
              "$ref": "#/components/schemas/ArtifactVersion"
            }
          },
          "dependencies": {
            "type": "array",
            "description": "List of declared dependencies.",
            "items": {
              "$ref": "#/components/schemas/Dependency"
            }
          }
        }
      },
      "ArtifactVersion": {
        "type": "object",
        "description": "A version entry for an artifact.",
        "properties": {
          "version": {
            "type": "string",
            "description": "The version string.",
            "example": "1.11.1"
          },
          "downloads": {
            "type": "integer",
            "description": "Number of downloads for this version.",
            "example": 45000
          }
        }
      },
      "Dependency": {
        "type": "object",
        "description": "A dependency declared by an artifact.",
        "properties": {
          "group_name": {
            "type": "string",
            "description": "The dependency group.",
            "example": "org.clojure"
          },
          "jar_name": {
            "type": "string",
            "description": "The dependency artifact name.",
            "example": "spec.alpha"
          },
          "version": {
            "type": "string",
            "description": "The required version.",
            "example": "0.2.194"
          },
          "scope": {
            "type": "string",
            "description": "The Maven dependency scope.",
            "example": "compile"
          }
        }
      },
      "License": {
        "type": "object",
        "description": "A software license.",
        "properties": {
          "name": {
            "type": "string",
            "description": "The license name.",
            "example": "Eclipse Public License 1.0"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "URL to the license text.",
            "example": "https://opensource.org/licenses/eclipse-1.0.php"
          }
        }
      },
      "ReleaseFeed": {
        "type": "object",
        "description": "Paginated feed of recent releases.",
        "properties": {
          "releases": {
            "type": "array",
            "description": "List of release entries.",
            "items": {
              "$ref": "#/components/schemas/Release"
            }
          },
          "next_from": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp to use as the 'from' parameter for the next page.",
            "example": "2024-02-01T12:00:00Z"
          }
        }
      },
      "Release": {
        "type": "object",
        "description": "A single artifact release entry.",
        "properties": {
          "group_name": {
            "type": "string",
            "description": "The group identifier.",
            "example": "ring"
          },
          "jar_name": {
            "type": "string",
            "description": "The artifact name.",
            "example": "ring-core"
          },
          "version": {
            "type": "string",
            "description": "The released version.",
            "example": "1.11.0"
          },
          "created": {
            "type": "string",
            "format": "date-time",
            "description": "When this version was deployed.",
            "example": "2024-01-15T09:23:00Z"
          },
          "description": {
            "type": "string",
            "description": "A short description of the artifact.",
            "example": "Core Ring library"
          }
        }
      },
      "SearchResults": {
        "type": "object",
        "description": "Search results from the Clojars artifact index.",
        "properties": {
          "results": {
            "type": "array",
            "description": "List of matching artifacts.",
            "items": {
              "$ref": "#/components/schemas/ArtifactSummary"
            }
          },
          "count": {
            "type": "integer",
            "description": "Total number of results found.",
            "example": 42
          }
        }
      }
    },
    "securitySchemes": {
      "BasicAuth": {
        "type": "http",
        "scheme": "basic",
        "description": "HTTP Basic authentication using your Clojars username and a deploy token (not your password). Deploy tokens can be created at https://clojars.org/tokens. Required only for write/deploy operations."
      }
    }
  }
}