A RESTful API for searching and retrieving Clojure artifact metadata, user profiles, group memberships, and release feeds from the Clojars community repository.
{
"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": "clojars@googlegroups.com",
"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."
}
}
}
}