{"id":12963,"library":"circleci-api","title":"CircleCI API Client","description":"The `circleci-api` library provides a client for interacting with the CircleCI API, designed for use in both Node.js and browser environments. Written entirely in TypeScript, it offers comprehensive type definitions and auto-completion for API responses, significantly reducing the need to consult external documentation. The current stable version is 4.1.4. While the project has seen bug fix releases in 2020-2021, its major version updates are less frequent, with v4.0.0 released in 2019. A key differentiator is its robust TypeScript support, providing static analysis benefits that many alternative plain JavaScript wrappers lack. However, it's important to note that this library currently supports only CircleCI API v1 and does not yet integrate with the newer CircleCI API v2, which is a known limitation the maintainers plan to address in the future.","status":"maintenance","version":"4.1.4","language":"javascript","source_language":"en","source_url":"https://github.com/worldturtlemedia/circleci-api","tags":["javascript","circleci","ci","api","typescript"],"install":[{"cmd":"npm install circleci-api","lang":"bash","label":"npm"},{"cmd":"yarn add circleci-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add circleci-api","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"HTTP client for making API requests.","package":"axios","optional":false}],"imports":[{"note":"Primarily designed for ES Modules and TypeScript. CommonJS usage is less idiomatic and might lack full type benefits.","wrong":"const CircleCI = require('circleci-api').CircleCI;","symbol":"CircleCI","correct":"import { CircleCI } from 'circleci-api';"},{"note":"GitType is an enum for specifying the VCS type (e.g., GITHUB, BITBUCKET). Import directly by name.","wrong":"import { GitType as Type } from 'circleci-api';","symbol":"GitType","correct":"import { GitType } from 'circleci-api';"},{"note":"This interface defines the configuration object for the CircleCI client. Ensure you import the specific type name.","wrong":"import { Options } from 'circleci-api';","symbol":"CircleCIOptions","correct":"import { CircleCIOptions } from 'circleci-api';"}],"quickstart":{"code":"import { CircleCI, GitType, CircleCIOptions, Artifact } from 'circleci-api';\n\n// Set your CircleCI API token securely via environment variables\nconst circleciToken = process.env.CIRCLECI_TOKEN ?? '';\n\nif (!circleciToken) {\n  console.error('CIRCLECI_TOKEN environment variable is not set.');\n  process.exit(1);\n}\n\nconst options: CircleCIOptions = {\n  token: circleciToken,\n  vcs: {\n    type: GitType.GITHUB,\n    owner: 'worldturtlemedia',\n    repo: 'circleci-api'\n  },\n  options: {\n    branch: 'master',\n    filter: 'successful'\n  }\n};\n\nconst api = new CircleCI(options);\n\nasync function getLatestSuccessfulArtifacts(): Promise<Artifact[]> {\n  try {\n    console.log('Fetching latest successful artifacts...');\n    const result: Artifact[] = await api.latestArtifacts();\n    console.log(`Found ${result.length} artifacts on branch '${options.options?.branch}'`);\n    return result;\n  } catch (error: any) {\n    console.error('Failed to fetch artifacts:', error.message);\n    if (error.response && error.response.data) {\n      console.error('API Error details:', error.response.data);\n    }\n    return [];\n  }\n}\n\ngetLatestSuccessfulArtifacts();","lang":"typescript","description":"This quickstart initializes the CircleCI client and fetches the latest successful build artifacts for a specified repository and branch, demonstrating basic setup and API interaction."},"warnings":[{"fix":"Review the MIGRATING.md documentation (https://github.com/worldturtlemedia/circleci-api/blob/master/MIGRATING.md) to adjust function call signatures for updated parameter orders.","message":"Version 4.0.0 introduced breaking changes, specifically reordering parameters for several standalone functions. Developers migrating from v3.x should consult the MIGRATING.md file for details to avoid runtime errors.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Be aware that only CircleCI API v1 functionality is available. For CircleCI API v2 interactions, consider alternative clients or direct HTTP requests until this library is updated.","message":"This library currently supports only CircleCI API v1. It does not integrate with or support the newer CircleCI API v2. Attempting to use v2 specific endpoints or features will not work.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"If encountering type errors or missing properties, consider casting the response to `any` as a temporary workaround and/or contribute a pull request with improved type definitions.","message":"While comprehensive, the TypeScript type definitions may have occasional inaccuracies or missing properties for specific API response payloads. The maintainers welcome contributions to improve type accuracy.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you are using `circleci-api@4.1.2` or newer. If the problem persists, check your `tsconfig.json` for proper `typeRoots` configuration or node module resolution.","cause":"Incorrect path to the typings file, specifically prior to version 4.1.2.","error":"Cannot find module 'circleci-api/typings' or its corresponding type declarations."},{"fix":"Upgrade `circleci-api` to the latest version (v3.3.1 fixed a specific path issue). Ensure `axios` is correctly installed as a direct dependency or peer dependency if required by your bundler configuration.","cause":"Issues with module resolution or bundling tools (like Webpack/Rollup) not correctly locating `axios`, especially in older versions or specific build configurations.","error":"Error: Cannot find module 'axios' (or similar bundling errors related to axios)"},{"fix":"Double-check your `CIRCLECI_TOKEN` environment variable for correctness. Verify the `vcs.owner`, `vcs.repo`, and `options.branch` match an existing CircleCI project and branch with builds. Inspect the error response for more specific details.","cause":"The API request failed due to invalid credentials, incorrect project/branch details, insufficient permissions, or a server-side issue.","error":"API Error: No build (or other 4xx/5xx status codes)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}