{
  "openapi": "3.0.3",
  "info": {
    "title": "Hex.pm API",
    "description": "REST API for the Hex.pm package registry, providing endpoints to search and retrieve package metadata, manage releases, handle authentication, manage API keys, and administer organizations and package ownership. The API supports JSON and Erlang media types.",
    "version": "1.0.0",
    "contact": {
      "name": "Hex Support",
      "email": "support@hex.pm",
      "url": "https://hex.pm/docs"
    },
    "termsOfService": "https://hex.pm/policies/terms",
    "license": {
      "name": "Hex.pm Terms of Service",
      "url": "https://hex.pm/policies/terms"
    }
  },
  "externalDocs": {
    "description": "Hex.pm API Documentation",
    "url": "https://hex.pm/docs/api"
  },
  "servers": [
    {
      "url": "https://hex.pm/api",
      "description": "Hex.pm Production API"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "API token authentication. Pass the token directly: `Authorization: token`. For OAuth2 Bearer tokens use: `Authorization: Bearer token`."
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "OAuth2 Bearer token obtained via Device Authorization Grant (RFC 8628)."
      },
      "BasicAuth": {
        "type": "http",
        "scheme": "basic",
        "description": "Deprecated. Basic authentication with username and password. Only allowed on specific endpoints for generating API tokens."
      }
    },
    "headers": {
      "X-RateLimit-Limit": {
        "description": "The maximum number of requests permitted per minute.",
        "schema": { "type": "integer" }
      },
      "X-RateLimit-Remaining": {
        "description": "The remaining number of requests allowed until reset.",
        "schema": { "type": "integer" }
      },
      "X-RateLimit-Reset": {
        "description": "The time at which the rate limit window resets in UNIX epoch.",
        "schema": { "type": "integer" }
      }
    },
    "parameters": {
      "page": {
        "name": "page",
        "in": "query",
        "description": "Page number for paginated results. Starts at 1.",
        "schema": { "type": "integer", "minimum": 1, "default": 1 }
      },
      "username_or_email": {
        "name": "username_or_email",
        "in": "path",
        "required": true,
        "schema": { "type": "string" },
        "description": "Username or email address of the user."
      },
      "package_name": {
        "name": "name",
        "in": "path",
        "required": true,
        "schema": { "type": "string" },
        "description": "Package name."
      },
      "release_version": {
        "name": "version",
        "in": "path",
        "required": true,
        "schema": { "type": "string" },
        "description": "Release version (e.g. 1.0.0)."
      },
      "key_name": {
        "name": "name",
        "in": "path",
        "required": true,
        "schema": { "type": "string" },
        "description": "Name of the API key."
      },
      "org_name": {
        "name": "name",
        "in": "path",
        "required": true,
        "schema": { "type": "string" },
        "description": "Organization name."
      },
      "username": {
        "name": "username",
        "in": "path",
        "required": true,
        "schema": { "type": "string" },
        "description": "Username."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "status": { "type": "integer" },
          "message": { "type": "string" },
          "errors": {
            "type": "object",
            "additionalProperties": { "type": "string" }
          }
        },
        "required": ["status", "message"]
      },
      "User": {
        "type": "object",
        "properties": {
          "username": { "type": "string", "description": "Unique username." },
          "email": { "type": "string", "format": "email", "description": "Email address." },
          "inserted_at": { "type": "string", "format": "date-time", "description": "Account creation timestamp." },
          "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp." },
          "url": { "type": "string", "format": "uri", "description": "API URL for this user." },
          "handles": {
            "type": "object",
            "description": "Social handles.",
            "properties": {
              "github": { "type": "string" },
              "twitter": { "type": "string" }
            }
          }
        }
      },
      "UserCreate": {
        "type": "object",
        "required": ["username", "email", "password"],
        "properties": {
          "username": { "type": "string", "description": "Username (3-32 alphanumeric characters)." },
          "email": { "type": "string", "format": "email", "description": "Email address." },
          "password": { "type": "string", "format": "password", "description": "Password." }
        }
      },
      "AuditLog": {
        "type": "object",
        "properties": {
          "action": { "type": "string", "description": "Action that was performed." },
          "actor": { "type": "string", "description": "Actor who performed the action." },
          "params": { "type": "object", "description": "Additional parameters of the action." },
          "inserted_at": { "type": "string", "format": "date-time" }
        }
      },
      "Package": {
        "type": "object",
        "properties": {
          "name": { "type": "string", "description": "Package name." },
          "html_url": { "type": "string", "format": "uri", "description": "URL to package page on hex.pm." },
          "docs_html_url": { "type": "string", "format": "uri", "description": "URL to package documentation." },
          "meta": {
            "type": "object",
            "description": "Package metadata.",
            "properties": {
              "description": { "type": "string" },
              "licenses": { "type": "array", "items": { "type": "string" } },
              "links": { "type": "object", "additionalProperties": { "type": "string" } },
              "maintainers": { "type": "array", "items": { "type": "string" } }
            }
          },
          "releases": {
            "type": "array",
            "description": "List of releases.",
            "items": { "$ref": "#/components/schemas/ReleaseSummary" }
          },
          "owners": {
            "type": "array",
            "description": "Package owners.",
            "items": { "$ref": "#/components/schemas/Owner" }
          },
          "inserted_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" },
          "url": { "type": "string", "format": "uri" },
          "downloads": {
            "type": "object",
            "description": "Download counts.",
            "properties": {
              "all": { "type": "integer" },
              "recent": { "type": "integer" }
            }
          }
        }
      },
      "ReleaseSummary": {
        "type": "object",
        "properties": {
          "version": { "type": "string", "description": "Release version." },
          "url": { "type": "string", "format": "uri" },
          "inserted_at": { "type": "string", "format": "date-time" }
        }
      },
      "Release": {
        "type": "object",
        "properties": {
          "version": { "type": "string", "description": "Release version." },
          "checksum": { "type": "string", "description": "SHA-256 checksum of the release tarball." },
          "has_docs": { "type": "boolean", "description": "Whether documentation is published." },
          "url": { "type": "string", "format": "uri" },
          "package_url": { "type": "string", "format": "uri" },
          "docs_html_url": { "type": "string", "format": "uri" },
          "html_url": { "type": "string", "format": "uri" },
          "downloads": { "type": "integer" },
          "meta": {
            "type": "object",
            "properties": {
              "app": { "type": "string" },
              "build_tools": { "type": "array", "items": { "type": "string" } },
              "elixir": { "type": "string" }
            }
          },
          "retirement": {
            "type": "object",
            "nullable": true,
            "properties": {
              "reason": { "type": "string", "enum": ["other", "invalid", "security", "deprecated", "renamed"] },
              "message": { "type": "string" }
            }
          },
          "requirements": {
            "type": "object",
            "description": "Package dependencies.",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "requirement": { "type": "string" },
                "optional": { "type": "boolean" },
                "app": { "type": "string" },
                "repository": { "type": "string" }
              }
            }
          },
          "inserted_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" }
        }
      },
      "Owner": {
        "type": "object",
        "properties": {
          "username": { "type": "string" },
          "email": { "type": "string", "format": "email" },
          "url": { "type": "string", "format": "uri" }
        }
      },
      "ApiKey": {
        "type": "object",
        "properties": {
          "name": { "type": "string", "description": "API key name." },
          "permissions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "domain": { "type": "string" },
                "resource": { "type": "string" }
              }
            }
          },
          "authing_key": { "type": "boolean", "description": "Whether the current request is authenticated with this key." },
          "secret": { "type": "string", "description": "The actual secret key (only returned on creation)." },
          "inserted_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" },
          "url": { "type": "string", "format": "uri" }
        }
      },
      "ApiKeyCreate": {
        "type": "object",
        "required": ["name", "permissions"],
        "properties": {
          "name": { "type": "string", "description": "Unique name for the API key." },
          "permissions": {
            "type": "array",
            "description": "List of permissions for the key.",
            "items": {
              "type": "object",
              "required": ["domain"],
              "properties": {
                "domain": { "type": "string", "description": "Permission domain (e.g., api, repositories, docs)." },
                "resource": { "type": "string", "description": "Resource the permission applies to (use * for all)." }
              }
            }
          }
        }
      },
      "Organization": {
        "type": "object",
        "properties": {
          "name": { "type": "string", "description": "Organization name." },
          "billing_email": { "type": "string", "format": "email" },
          "seats": { "type": "integer", "description": "Number of seats." },
          "inserted_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" },
          "url": { "type": "string", "format": "uri" }
        }
      },
      "OrganizationMember": {
        "type": "object",
        "properties": {
          "username": { "type": "string" },
          "role": { "type": "string", "enum": ["admin", "write", "read"] },
          "url": { "type": "string", "format": "uri" }
        }
      },
      "Repository": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "public_key": { "type": "string", "description": "Repository's public key for signature verification." },
          "url": { "type": "string", "format": "uri" },
          "inserted_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" }
        }
      },
      "DeviceAuthorizationRequest": {
        "type": "object",
        "required": ["client_id"],
        "properties": {
          "client_id": { "type": "string" },
          "scope": { "type": "string" },
          "offline_access": { "type": "boolean" },
          "name": { "type": "string", "description": "Name of the client to display." }
        }
      },
      "DeviceAuthorizationResponse": {
        "type": "object",
        "properties": {
          "device_code": { "type": "string" },
          "user_code": { "type": "string" },
          "verification_uri": { "type": "string", "format": "uri" },
          "verification_uri_complete": { "type": "string", "format": "uri" },
          "expires_in": { "type": "integer" },
          "interval": { "type": "integer" }
        }
      },
      "TokenRequest": {
        "type": "object",
        "required": ["grant_type", "client_id", "device_code"],
        "properties": {
          "grant_type": { "type": "string", "example": "urn:ietf:params:oauth:grant-type:device_code" },
          "client_id": { "type": "string" },
          "device_code": { "type": "string" }
        }
      },
      "TokenResponse": {
        "type": "object",
        "properties": {
          "access_token": { "type": "string" },
          "token_type": { "type": "string" },
          "expires_in": { "type": "integer" },
          "refresh_token": { "type": "string" },
          "scope": { "type": "string" }
        }
      },
      "RetireRelease": {
        "type": "object",
        "required": ["reason"],
        "properties": {
          "reason": {
            "type": "string",
            "enum": ["other", "invalid", "security", "deprecated", "renamed"],
            "description": "Reason for retiring the release."
          },
          "message": { "type": "string", "description": "Optional message explaining retirement." }
        }
      },
      "ShortUrl": {
        "type": "object",
        "required": ["url"],
        "properties": {
          "url": { "type": "string", "format": "uri", "description": "The long URL to shorten." }
        }
      },
      "ApiIndex": {
        "type": "object",
        "properties": {
          "packages_url": { "type": "string", "format": "uri" },
          "package_url": { "type": "string" },
          "package_release_url": { "type": "string" },
          "package_owners_url": { "type": "string" },
          "keys_url": { "type": "string", "format": "uri" },
          "key_url": { "type": "string" },
          "documentation_url": { "type": "string", "format": "uri" }
        }
      }
    }
  },
  "paths": {
    "/": {
      "get": {
        "operationId": "getApiIndex",
        "summary": "Get API Index",
        "description": "Returns available API endpoints and documentation URL.",
        "tags": ["Index"],
        "security": [],
        "responses": {
          "200": {
            "description": "API index with URL templates for all resources.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiIndex" }
              }
            }
          }
        }
      }
    },
    "/users": {
      "post": {
        "operationId": "createUser",
        "summary": "Create a User",
        "description": "Register a new user account.",
        "tags": ["Users"],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/UserCreate" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "User created successfully.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/User" }
              }
            }
          },
          "422": {
            "description": "Validation error.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/users/{username_or_email}": {
      "get": {
        "operationId": "getUser",
        "summary": "Fetch a User",
        "description": "Returns information about a specific user.",
        "tags": ["Users"],
        "security": [],
        "parameters": [
          { "$ref": "#/components/parameters/username_or_email" }
        ],
        "responses": {
          "200": {
            "description": "User details.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/User" }
              }
            }
          },
          "404": {
            "description": "User not found.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/users/me": {
      "get": {
        "operationId": "getCurrentUser",
        "summary": "Fetch currently authenticated user",
        "description": "Returns information about the currently authenticated user.",
        "tags": ["Users"],
        "responses": {
          "200": {
            "description": "Currently authenticated user details.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/User" }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/users/me/audit-logs": {
      "get": {
        "operationId": "getUserAuditLogs",
        "summary": "Fetch User Audit Logs",
        "description": "Returns audit logs for the currently authenticated user.",
        "tags": ["Users"],
        "parameters": [
          { "$ref": "#/components/parameters/page" }
        ],
        "responses": {
          "200": {
            "description": "List of audit log entries.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/AuditLog" }
                }
              }
            }
          }
        }
      }
    },
    "/users/{username_or_email}/reset": {
      "post": {
        "operationId": "resetUserPassword",
        "summary": "Reset User password",
        "description": "Sends a password reset email to the user.",
        "tags": ["Users"],
        "security": [],
        "parameters": [
          { "$ref": "#/components/parameters/username_or_email" }
        ],
        "responses": {
          "204": {
            "description": "Password reset email sent."
          },
          "404": {
            "description": "User not found.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/repos": {
      "get": {
        "operationId": "listRepositories",
        "summary": "List all Repositories",
        "description": "Returns a list of all available Hex repositories.",
        "tags": ["Repositories"],
        "security": [],
        "parameters": [
          { "$ref": "#/components/parameters/page" }
        ],
        "responses": {
          "200": {
            "description": "List of repositories.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Repository" }
                }
              }
            }
          }
        }
      }
    },
    "/repos/{name}": {
      "get": {
        "operationId": "getRepository",
        "summary": "Fetch a Repository",
        "description": "Returns information about a specific repository.",
        "tags": ["Repositories"],
        "security": [],
        "parameters": [
          { "$ref": "#/components/parameters/org_name" }
        ],
        "responses": {
          "200": {
            "description": "Repository details.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Repository" }
              }
            }
          },
          "404": {
            "description": "Repository not found.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/orgs": {
      "get": {
        "operationId": "listOrganizations",
        "summary": "List all Organizations",
        "description": "Returns a list of all organizations the authenticated user is a member of.",
        "tags": ["Organizations"],
        "parameters": [
          { "$ref": "#/components/parameters/page" }
        ],
        "responses": {
          "200": {
            "description": "List of organizations.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Organization" }
                }
              }
            }
          }
        }
      }
    },
    "/orgs/{name}": {
      "get": {
        "operationId": "getOrganization",
        "summary": "Fetch an Organization",
        "description": "Returns information about a specific organization.",
        "tags": ["Organizations"],
        "parameters": [
          { "$ref": "#/components/parameters/org_name" }
        ],
        "responses": {
          "200": {
            "description": "Organization details.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Organization" }
              }
            }
          },
          "404": {
            "description": "Organization not found.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "updateOrganization",
        "summary": "Update an Organization",
        "description": "Updates organization settings such as billing email.",
        "tags": ["Organizations"],
        "parameters": [
          { "$ref": "#/components/parameters/org_name" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "billing_email": { "type": "string", "format": "email" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Organization updated.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Organization" }
              }
            }
          }
        }
      }
    },
    "/orgs/{name}/audit-logs": {
      "get": {
        "operationId": "getOrganizationAuditLogs",
        "summary": "Fetch Organization Audit Logs",
        "description": "Returns audit logs for a specific organization.",
        "tags": ["Organizations"],
        "parameters": [
          { "$ref": "#/components/parameters/org_name" },
          { "$ref": "#/components/parameters/page" }
        ],
        "responses": {
          "200": {
            "description": "List of audit log entries.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/AuditLog" }
                }
              }
            }
          }
        }
      }
    },
    "/orgs/{name}/members": {
      "get": {
        "operationId": "listOrganizationMembers",
        "summary": "List Organization Members",
        "description": "Returns all members of an organization.",
        "tags": ["Organizations"],
        "parameters": [
          { "$ref": "#/components/parameters/org_name" },
          { "$ref": "#/components/parameters/page" }
        ],
        "responses": {
          "200": {
            "description": "List of organization members.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/OrganizationMember" }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "addOrganizationMember",
        "summary": "Add Organization Member",
        "description": "Adds a user to an organization.",
        "tags": ["Organizations"],
        "parameters": [
          { "$ref": "#/components/parameters/org_name" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["username", "role"],
                "properties": {
                  "username": { "type": "string" },
                  "role": { "type": "string", "enum": ["admin", "write", "read"] }
                }
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Member added successfully."
          },
          "422": {
            "description": "Validation error.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/orgs/{name}/members/{username}": {
      "get": {
        "operationId": "getOrganizationMember",
        "summary": "Get Organization Member",
        "description": "Returns information about a specific organization member.",
        "tags": ["Organizations"],
        "parameters": [
          { "$ref": "#/components/parameters/org_name" },
          { "$ref": "#/components/parameters/username" }
        ],
        "responses": {
          "200": {
            "description": "Organization member details.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/OrganizationMember" }
              }
            }
          },
          "404": {
            "description": "Member not found.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "updateOrganizationMember",
        "summary": "Update Organization Member",
        "description": "Updates the role of an organization member.",
        "tags": ["Organizations"],
        "parameters": [
          { "$ref": "#/components/parameters/org_name" },
          { "$ref": "#/components/parameters/username" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["role"],
                "properties": {
                  "role": { "type": "string", "enum": ["admin", "write", "read"] }
                }
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Member updated."
          }
        }
      },
      "delete": {
        "operationId": "removeOrganizationMember",
        "summary": "Remove Organization Member",
        "description": "Removes a user from an organization.",
        "tags": ["Organizations"],
        "parameters": [
          { "$ref": "#/components/parameters/org_name" },
          { "$ref": "#/components/parameters/username" }
        ],
        "responses": {
          "204": {
            "description": "Member removed."
          },
          "404": {
            "description": "Member not found.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/packages": {
      "get": {
        "operationId": "listPackages",
        "summary": "List all Packages",
        "description": "Returns a paginated list of packages. Supports search and sorting.",
        "tags": ["Packages"],
        "security": [],
        "parameters": [
          {
            "name": "sort",
            "in": "query",
            "description": "Sort order. Options: name, downloads, inserted_at, updated_at, recent_downloads.",
            "schema": {
              "type": "string",
              "enum": ["name", "downloads", "inserted_at", "updated_at", "recent_downloads"]
            }
          },
          {
            "name": "search",
            "in": "query",
            "description": "Search string. Supports field search: name:nerves*, description:framework, extra:type,nerves.",
            "schema": { "type": "string" }
          },
          { "$ref": "#/components/parameters/page" }
        ],
        "responses": {
          "200": {
            "description": "List of packages.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Package" }
                }
              }
            },
            "headers": {
              "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" },
              "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" },
              "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }
            }
          }
        }
      }
    },
    "/packages/{name}": {
      "get": {
        "operationId": "getPackage",
        "summary": "Fetch a Package",
        "description": "Returns information about a specific package including all releases and owners.",
        "tags": ["Packages"],
        "security": [],
        "parameters": [
          { "$ref": "#/components/parameters/package_name" }
        ],
        "responses": {
          "200": {
            "description": "Package details.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Package" }
              }
            }
          },
          "404": {
            "description": "Package not found.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/packages/{name}/audit-logs": {
      "get": {
        "operationId": "getPackageAuditLogs",
        "summary": "Fetch Package Audit Logs",
        "description": "Returns audit logs for a specific package.",
        "tags": ["Packages"],
        "parameters": [
          { "$ref": "#/components/parameters/package_name" },
          { "$ref": "#/components/parameters/page" }
        ],
        "responses": {
          "200": {
            "description": "List of audit log entries.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/AuditLog" }
                }
              }
            }
          }
        }
      }
    },
    "/packages/{name}/releases/{version}": {
      "get": {
        "operationId": "getRelease",
        "summary": "Fetch a Release",
        "description": "Returns detailed information about a specific release of a package.",
        "tags": ["Releases"],
        "security": [],
        "parameters": [
          { "$ref": "#/components/parameters/package_name" },
          { "$ref": "#/components/parameters/release_version" }
        ],
        "responses": {
          "200": {
            "description": "Release details.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Release" }
              }
            }
          },
          "404": {
            "description": "Release not found.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "revertRelease",
        "summary": "Revert a Release",
        "description": "Removes a release. Only possible within one hour of publishing and if no other packages depend on it.",
        "tags": ["Releases"],
        "parameters": [
          { "$ref": "#/components/parameters/package_name" },
          { "$ref": "#/components/parameters/release_version" }
        ],
        "responses": {
          "204": {
            "description": "Release reverted successfully."
          },
          "403": {
            "description": "Not authorized or time window expired.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "404": {
            "description": "Release not found.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/publish": {
      "post": {
        "operationId": "publishRelease",
        "summary": "Publish a Release",
        "description": "Publishes a new release for a package. The body must be a valid Hex package tarball.",
        "tags": ["Releases"],
        "requestBody": {
          "required": true,
          "content": {
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary",
                "description": "Hex package tarball."
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Release published.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Release" }
              }
            }
          },
          "400": {
            "description": "Invalid tarball.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "422": {
            "description": "Validation error.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/packages/{name}/releases/{version}/retire": {
      "post": {
        "operationId": "retireRelease",
        "summary": "Mark Release as Retired",
        "description": "Marks a release as retired with a reason and optional message.",
        "tags": ["Releases"],
        "parameters": [
          { "$ref": "#/components/parameters/package_name" },
          { "$ref": "#/components/parameters/release_version" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/RetireRelease" }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Release marked as retired."
          },
          "404": {
            "description": "Release not found.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "unretireRelease",
        "summary": "Unmark Release as Retired",
        "description": "Removes the retired status from a release.",
        "tags": ["Releases"],
        "parameters": [
          { "$ref": "#/components/parameters/package_name" },
          { "$ref": "#/components/parameters/release_version" }
        ],
        "responses": {
          "204": {
            "description": "Release retirement removed."
          },
          "404": {
            "description": "Release not found.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/packages/{name}/releases/{version}/docs": {
      "get": {
        "operationId": "getPackageDocs",
        "summary": "Get Package Documentation",
        "description": "Returns documentation for a specific release.",
        "tags": ["Documentation"],
        "security": [],
        "parameters": [
          { "$ref": "#/components/parameters/package_name" },
          { "$ref": "#/components/parameters/release_version" }
        ],
        "responses": {
          "200": {
            "description": "Documentation tarball.",
            "content": {
              "application/octet-stream": {
                "schema": { "type": "string", "format": "binary" }
              }
            }
          },
          "404": {
            "description": "Documentation not found.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "publishPackageDocs",
        "summary": "Publish Package Documentation",
        "description": "Publishes documentation for a release. Body must be a gzipped tarball.",
        "tags": ["Documentation"],
        "parameters": [
          { "$ref": "#/components/parameters/package_name" },
          { "$ref": "#/components/parameters/release_version" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/octet-stream": {
              "schema": { "type": "string", "format": "binary" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Documentation published."
          },
          "422": {
            "description": "Invalid documentation.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "removePackageDocs",
        "summary": "Remove Package Documentation",
        "description": "Removes documentation for a specific release.",
        "tags": ["Documentation"],
        "parameters": [
          { "$ref": "#/components/parameters/package_name" },
          { "$ref": "#/components/parameters/release_version" }
        ],
        "responses": {
          "204": {
            "description": "Documentation removed."
          },
          "404": {
            "description": "Documentation not found.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/packages/{name}/owners": {
      "get": {
        "operationId": "listPackageOwners",
        "summary": "Fetch Package Owners",
        "description": "Returns all owners of a package.",
        "tags": ["Package Owners"],
        "security": [],
        "parameters": [
          { "$ref": "#/components/parameters/package_name" }
        ],
        "responses": {
          "200": {
            "description": "List of package owners.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Owner" }
                }
              }
            }
          },
          "404": {
            "description": "Package not found.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/packages/{name}/owners/{username}": {
      "get": {
        "operationId": "getPackageOwner",
        "summary": "Fetch a Package Owner",
        "description": "Returns information about a specific owner of a package.",
        "tags": ["Package Owners"],
        "parameters": [
          { "$ref": "#/components/parameters/package_name" },
          { "$ref": "#/components/parameters/username" }
        ],
        "responses": {
          "200": {
            "description": "Package owner details.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Owner" }
              }
            }
          },
          "404": {
            "description": "Owner not found.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "addPackageOwner",
        "summary": "Add a Package Owner",
        "description": "Adds a user as an owner of a package.",
        "tags": ["Package Owners"],
        "parameters": [
          { "$ref": "#/components/parameters/package_name" },
          { "$ref": "#/components/parameters/username" }
        ],
        "responses": {
          "204": {
            "description": "Owner added."
          },
          "403": {
            "description": "Not authorized.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "404": {
            "description": "Package or user not found.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "removePackageOwner",
        "summary": "Remove a Package Owner",
        "description": "Removes a user as an owner of a package.",
        "tags": ["Package Owners"],
        "parameters": [
          { "$ref": "#/components/parameters/package_name" },
          { "$ref": "#/components/parameters/username" }
        ],
        "responses": {
          "204": {
            "description": "Owner removed."
          },
          "403": {
            "description": "Not authorized.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "404": {
            "description": "Package or user not found.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/keys": {
      "get": {
        "operationId": "listApiKeys",
        "summary": "List all API Keys",
        "description": "Returns all API keys for the authenticated user.",
        "tags": ["API Keys"],
        "responses": {
          "200": {
            "description": "List of API keys.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/ApiKey" }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createApiKey",
        "summary": "Create an API Key",
        "description": "Creates a new API key. The secret is only returned on creation.",
        "tags": ["API Keys"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ApiKeyCreate" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "API key created. The secret field is only returned here.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiKey" }
              }
            }
          },
          "422": {
            "description": "Validation error.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "removeAllApiKeys",
        "summary": "Remove all API Keys",
        "description": "Removes all API keys for the authenticated user. Requires Basic authentication.",
        "tags": ["API Keys"],
        "security": [{ "BasicAuth": [] }],
        "responses": {
          "204": {
            "description": "All API keys removed."
          }
        }
      }
    },
    "/keys/{name}": {
      "get": {
        "operationId": "getApiKey",
        "summary": "Fetch an API Key",
        "description": "Returns information about a specific API key.",
        "tags": ["API Keys"],
        "parameters": [
          { "$ref": "#/components/parameters/key_name" }
        ],
        "responses": {
          "200": {
            "description": "API key details.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiKey" }
              }
            }
          },
          "404": {
            "description": "Key not found.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "removeApiKey",
        "summary": "Remove an API Key",
        "description": "Removes a specific API key.",
        "tags": ["API Keys"],
        "parameters": [
          { "$ref": "#/components/parameters/key_name" }
        ],
        "responses": {
          "200": {
            "description": "API key removed.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiKey" }
              }
            }
          },
          "404": {
            "description": "Key not found.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/orgs/{name}/keys": {
      "get": {
        "operationId": "listOrganizationApiKeys",
        "summary": "List Organization API Keys",
        "description": "Returns all API keys for an organization.",
        "tags": ["API Keys", "Organizations"],
        "parameters": [
          { "$ref": "#/components/parameters/org_name" }
        ],
        "responses": {
          "200": {
            "description": "List of organization API keys.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/ApiKey" }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createOrganizationApiKey",
        "summary": "Create Organization API Key",
        "description": "Creates a new API key for an organization.",
        "tags": ["API Keys", "Organizations"],
        "parameters": [
          { "$ref": "#/components/parameters/org_name" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ApiKeyCreate" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Organization API key created.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiKey" }
              }
            }
          },
          "422": {
            "description": "Validation error.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/short_url": {
      "post": {
        "operationId": "createShortUrl",
        "summary": "Create Short URL",
        "description": "Creates a short URL for a given long URL.",
        "tags": ["Utilities"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ShortUrl" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Short URL created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "short_url": { "type": "string", "format": "uri" },
                    "url": { "type": "string", "format": "uri" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/auth": {
      "get": {
        "operationId": "verifyAuthentication",
        "summary": "Verify Authentication",
        "description": "Verifies that the current authentication credentials are valid.",
        "tags": ["Authentication"],
        "responses": {
          "200": {
            "description": "Authentication is valid.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "authed_as": { "type": "string", "description": "The username authenticated as." }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/oauth/device_authorization": {
      "post": {
        "operationId": "initiateDeviceAuthorization",
        "summary": "Initiate Device Authorization",
        "description": "Initiates the OAuth2 Device Authorization Grant flow (RFC 8628). Returns a device code and user code for the client to display.",
        "tags": ["OAuth"],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/DeviceAuthorizationRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Device authorization response.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/DeviceAuthorizationResponse" }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/oauth/token": {
      "post": {
        "operationId": "requestToken",
        "summary": "Request Token",
        "description": "Exchanges a device code for an OAuth2 access token after user has authorized the device.",
        "tags": ["OAuth"],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/TokenRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Token response.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/TokenResponse" }
              }
            }
          },
          "400": {
            "description": "Authorization pending or invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": { "type": "string" },
                    "error_description": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/oauth/revoke": {
      "post": {
        "operationId": "revokeToken",
        "summary": "Revoke Token",
        "description": "Revokes an OAuth2 access token.",
        "tags": ["OAuth"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["token"],
                "properties": {
                  "token": { "type": "string", "description": "The token to revoke." }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Token revoked."
          }
        }
      }
    },
    "/oauth/revoke_by_hash": {
      "post": {
        "operationId": "revokeTokenByHash",
        "summary": "Revoke Token by Hash",
        "description": "Revokes an OAuth2 token using its hash value.",
        "tags": ["OAuth"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["token_hash"],
                "properties": {
                  "token_hash": { "type": "string", "description": "The SHA-256 hash of the token to revoke." }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Token revoked."
          }
        }
      }
    }
  },
  "tags": [
    { "name": "Index", "description": "API index and discovery." },
    { "name": "Users", "description": "User account management." },
    { "name": "Repositories", "description": "Hex repository management." },
    { "name": "Organizations", "description": "Organization and member management." },
    { "name": "Packages", "description": "Package search and metadata." },
    { "name": "Releases", "description": "Package release publishing and management." },
    { "name": "Documentation", "description": "HexDocs package documentation." },
    { "name": "Package Owners", "description": "Package ownership management." },
    { "name": "API Keys", "description": "API key creation and management." },
    { "name": "Authentication", "description": "Authentication verification." },
    { "name": "OAuth", "description": "OAuth2 Device Authorization Grant flow." },
    { "name": "Utilities", "description": "Utility endpoints." }
  ]
}