Ballerina Packages API

openapi: 3.1.0
info:
  title: Ballerina Packages API
  description: The public read API of Ballerina Central — the package registry for the Ballerina programming
    language, operated by WSO2. The surface documented here was established by calling every operation
    anonymously on 2026-09-04 and by reading WSO2's own first-party clients of this API (ballerina-platform/skills
    mcp/src/central-client.js and ballerina-platform/ballerina-library connector-doc-generator/modules/central/central.bal),
    which name the same paths. Every path, parameter, response shape and error envelope below was observed
    on a live call; nothing is inferred from marketing copy.
  version: '2.0'
  contact:
    name: WSO2 / Ballerina
    url: https://ballerina.io
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
x-provenance:
  method: probed
  probed: '2026-09-04'
  probe_transcript:
  - url: https://api.central.ballerina.io/2.0/registry/packages?org=ballerina&limit=2&readme=false
    status: 200
  - url: https://api.central.ballerina.io/2.0/registry/search-packages?q=http&limit=2
    status: 200
  - url: https://api.central.ballerina.io/2.0/registry/packages/ballerina/http
    status: 200
  - url: https://api.central.ballerina.io/2.0/registry/packages/ballerina/nosuchpkg
    status: 404
  - url: https://api.central.ballerina.io/2.0/registry/connectors?q=salesforce&limit=1
    status: 200
  - url: https://api.central.ballerina.io/2.0/registry/triggers?q=github&limit=1
    status: 200
  - url: https://api.central.ballerina.io/2.0/docs/ballerina/random/1.7.0
    status: 200
  - url: https://api.central.ballerina.io/2.0/docs/ballerina/random/9.9.9
    status: 404
  first_party_sources:
  - https://github.com/ballerina-platform/skills/blob/main/mcp/src/central-client.js
  - https://github.com/ballerina-platform/ballerina-library/blob/main/connector-doc-generator/modules/central/central.bal
  supersedes: An earlier scaffold in this repo described /2.0/packages, /2.0/connectors and /2.0/organizations/{org}.
    Every one of those paths returns HTTP 404 on the live host; they were replaced by the probed surface
    below.
servers:
- url: https://api.central.ballerina.io
  description: Ballerina Central API (public, unauthenticated for read operations)
tags:
- name: Packages
  description: Search and resolve Ballerina packages published to Ballerina Central.
paths:
  /2.0/registry/packages:
    get:
      operationId: searchPackages
      summary: Search or list packages
      description: List packages in Ballerina Central, optionally filtered by a free-text query or by
        owning organization. Paginated with offset/limit; the response echoes count/offset/limit.
      tags:
      - Packages
      parameters:
      - name: q
        in: query
        required: false
        description: Free-text query matched against package name, summary and keywords.
        schema:
          type: string
      - name: org
        in: query
        required: false
        description: Restrict results to packages owned by this organization (e.g. `ballerina`, `ballerinax`).
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum packages to return. Observed accepted up to 1000 (WSO2's own MCP client sends
          limit=1000).
        schema:
          type: integer
          minimum: 1
      - name: offset
        in: query
        required: false
        description: Zero-based pagination offset.
        schema:
          type: integer
          minimum: 0
          default: 0
      - name: readme
        in: query
        required: false
        description: When `false`, the large `readme` field is omitted from each package.
        schema:
          type: boolean
      - name: sort
        in: query
        required: false
        description: Accepted by the server but no sort field could be established from the public surface
          — `relevance`, `pullCount,DESC` and `createdDate,DESC` each returned HTTP 400 `invalid/unsupported
          sort field` when probed on 2026-09-04. Documented here because the parameter demonstrably exists,
          not because a working value is known.
        schema:
          type: string
      responses:
        '200':
          description: A page of packages.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackageSearchResponse'
        '400':
          description: Invalid query parameter (bad cast, or unsupported sort field).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
  /2.0/registry/search-packages:
    get:
      operationId: fullTextSearchPackages
      summary: Full-text package search
      description: Full-text search over published packages. Returns the same package page as `/2.0/registry/packages`
        plus `suggestions` and a `highlighting` map keyed by package id.
      tags:
      - Packages
      parameters:
      - name: q
        in: query
        required: true
        description: Free-text search query.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
      responses:
        '200':
          description: A page of matching packages with search metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackageFullTextSearchResponse'
        '400':
          description: Invalid query parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
  /2.0/registry/packages/{orgName}/{packageName}:
    get:
      operationId: listPackageVersions
      summary: List the published versions of a package
      description: Returns the versions published for `orgName/packageName`, newest first, as a JSON array
        of version strings. This is the endpoint WSO2's own tooling calls to resolve "latest".
      tags:
      - Packages
      parameters:
      - name: orgName
        in: path
        required: true
        description: Owning organization, e.g. `ballerina` or `ballerinax`.
        schema:
          type: string
      - name: packageName
        in: path
        required: true
        description: Package name, e.g. `http`.
        schema:
          type: string
      responses:
        '200':
          description: Version strings, newest first.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
              examples:
                ballerinaHttp:
                  summary: ballerina/http (truncated)
                  value:
                  - 2.17.0
                  - 2.16.7
                  - 2.16.6
        '404':
          description: No such package.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundMessage'
              examples:
                missing:
                  value:
                    message: 'package not found: ballerina/nosuchpkg:*_any'
components:
  schemas:
    BadRequestError:
      description: Two 400 envelopes were observed. A query-parameter cast failure returns the timestamp/status/reason/message/path/method
        shape; a search validation failure returns a bare `message`.
      oneOf:
      - type: object
        properties:
          timestamp:
            type: string
            format: date-time
          status:
            type: integer
          reason:
            type: string
          message:
            type: string
          path:
            type: string
          method:
            type: string
      - type: object
        properties:
          message:
            type: string
    Module:
      type: object
      description: A module inside a published package.
      properties:
        packageURL:
          type: string
        apiDocURL:
          type: string
          description: Rendered API docs URL on lib.ballerina.io.
        name:
          type: string
        summary:
          type: string
        readme:
          type: string
    NotFoundMessage:
      type: object
      description: The 404 envelope returned by registry and docs lookups.
      properties:
        message:
          type: string
    Package:
      type: object
      description: A package published to Ballerina Central.
      properties:
        id:
          type: integer
          description: Registry-assigned numeric package id.
        organization:
          type: string
          description: Owning organization
          e.g. `ballerina`.: null
        name:
          type: string
        version:
          type: string
        platform:
          type: string
          description: Target platform of the published artifact, e.g. `java21` or `any`.
        languageSpecificationVersion:
          type: string
          description: Ballerina language specification the package was built against, e.g. `2024R1`.
        isDeprecated:
          type: boolean
          description: True when the maintainer has deprecated this package version.
        deprecateMessage:
          type: string
          description: Maintainer-supplied deprecation notice; empty when not deprecated.
        URL:
          type: string
          description: Central-relative path to the package page, e.g. `/ballerina/http/2.17.0`.
        balaVersion:
          type: string
          description: Version of the BALA archive format used.
        balaURL:
          type: string
          description: Download URL for the BALA archive.
        digest:
          type: string
          description: Content digest of the published archive.
        summary:
          type: string
        readme:
          type: string
          description: Full README markdown; omitted when `readme=false`.
        template:
          type: boolean
          description: True when the package is a project template.
        licenses:
          type: array
          items:
            type: string
        authors:
          type: array
          items:
            type: string
        sourceCodeLocation:
          type: string
        keywords:
          type: array
          items:
            type: string
        ballerinaVersion:
          type: string
        icon:
          type: string
        ownerUUID:
          type: string
        createdDate:
          type: integer
          description: Publication time
          epoch milliseconds.: null
        pullCount:
          type: integer
          description: Cumulative pulls of this package.
        visibility:
          type: string
          description: '`public` for everything reachable anonymously.'
        modules:
          type: array
          items:
            $ref: '#/components/schemas/Module'
        balToolId:
          type: string
          description: Set when the package ships a `bal` CLI tool.
        graalvmCompatible:
          type: string
          description: 'GraalVM native-image compatibility as declared/verified: e.g. `Yes`, `No`, `Unknown`.'
    PackageFullTextSearchResponse:
      allOf:
      - $ref: '#/components/schemas/PackageSearchResponse'
      - type: object
        properties:
          suggestions:
            type: array
            items:
              type: string
          highlighting:
            type: object
            description: Map of package id to the matched fragments per field.
            additionalProperties:
              type: object
              additionalProperties:
                type: array
                items:
                  type: string
    PackageSearchResponse:
      type: object
      properties:
        packages:
          type: array
          items:
            $ref: '#/components/schemas/Package'
        count:
          type: integer
          description: Total matches available
          not the page size.: null
        offset:
          type: integer
        limit:
          type: integer