# CircleCI API V3

> Reference documentation for CircleCI's V3 API: every endpoint, its parameters,
> request body and response statuses. Each file below is the canonical
> specification for one entity, and the same source the OpenAPI description is
> generated from.

## Start here

- [Index](https://circleci.com/docs/api/v3/index.md): every operation in one file, with the conventions in full.
- [Conventions](https://circleci.com/docs/api/v3/conventions.md): auth, ids, envelope, paging, errors, rate limits, deprecation.
- [OpenAPI](https://circleci.com/fullopenapi.yaml): the machine-readable description (YAML).

## Entities

- [Analysis Charges](https://circleci.com/docs/api/v3/analysis-charges.md): Credit spend aggregated by job, workflow or pipeline.
- [Analysis Jobs](https://circleci.com/docs/api/v3/analysis-jobs.md): Aggregated job analytics across time.
- [Analysis Tests](https://circleci.com/docs/api/v3/analysis-tests.md): Aggregated test analytics across time.
- [Analysis Usage](https://circleci.com/docs/api/v3/analysis-usage.md): Resource consumption aggregated by job, workflow or pipeline.
- [Catalog](https://circleci.com/docs/api/v3/catalog.md): Marketplace catalog of available products and add-ons.
- [Configs](https://circleci.com/docs/api/v3/configs.md): Configuration compilation and validation.
- [Context Restrictions](https://circleci.com/docs/api/v3/context-restrictions.md): Restrictions that limit which projects, groups, or expressions may use a context.
- [Contexts](https://circleci.com/docs/api/v3/contexts.md): Secret contexts that provide environment variables to jobs at runtime.
- [Deploy Components](https://circleci.com/docs/api/v3/deploy-components.md): Release tracker components representing deployable units.
- [Deploy Config Suggestions](https://circleci.com/docs/api/v3/deploy-config-suggestions.md): Async requests to validate a CircleCI config and generate a suggested deploy config.
- [Deploy Deployments](https://circleci.com/docs/api/v3/deploy-deployments.md): A deployment is one attempt to move a deploy component to a target version in an environment. Read in the scope of an organization via filter[org_id].
- [Deploy Diff Summaries](https://circleci.com/docs/api/v3/deploy-diff-summaries.md): Async requests to generate a human-readable summary of a code diff.
- [Deploy Environments](https://circleci.com/docs/api/v3/deploy-environments.md): Release tracker environments for deployment management.
- [Deploy Settings](https://circleci.com/docs/api/v3/deploy-settings.md): Per-project deploy configuration — the pipeline definitions run to deploy and to roll back. A singleton per project rather than an independently addressable resource.
- [Jobs](https://circleci.com/docs/api/v3/jobs.md): Individual units of work within a workflow. Each job runs in its own execution environment and produces artifacts, test results, and logs.
- [Metric Counts](https://circleci.com/docs/api/v3/metric-counts.md): Time-bucketed count metrics (test result counts and test flake counts) over a time window.
- [Metric Distributions](https://circleci.com/docs/api/v3/metric-distributions.md): Time-bucketed distribution metrics (e.g. test result duration percentiles) over a time window.
- [Namespaces](https://circleci.com/docs/api/v3/namespaces.md): Scoping containers that group orbs under an organization. An orb's full name is namespace/orb-name.
- [Notification Channel Configs](https://circleci.com/docs/api/v3/notification-channel-configs.md): Per-user and per-project notification channel configuration — the email address or Slack channel a notification is delivered to.
- [Notification Integrations](https://circleci.com/docs/api/v3/notification-integrations.md): Currently Slack workspace integrations for an organization. Manage the connection used to deliver CircleCI notifications.
- [Notification Links](https://circleci.com/docs/api/v3/notification-links.md): Links between a CircleCI user and an external identity on a third-party connection (e.g. a Slack user). Used to deliver notifications, enable interactivity, and tag authors on that identity. Keyed by user, connection type, and external scope; not UUID-addressable.
- [Notification Preferences](https://circleci.com/docs/api/v3/notification-preferences.md): Per-user and per-project notification preference matrix. Read the matrix or bulk-toggle entries; scoped via filter[scope]=user|project.
- [Orb Categories](https://circleci.com/docs/api/v3/orb-categories.md): Taxonomy labels for organizing and discovering orbs in the registry.
- [Orb Packages](https://circleci.com/docs/api/v3/orb-packages.md): Reusable configuration packages published to the orb registry. Each orb belongs to a namespace and has one or more versioned releases.
- [Orb Versions](https://circleci.com/docs/api/v3/orb-versions.md): Individual published releases of an orb, identified by semantic version. Each version contains the orb's source configuration.
- [Orgs](https://circleci.com/docs/api/v3/orgs.md): Organizations are the top-level account entity. All projects, pipelines, and billing belong to an org.
- [Pipelines](https://circleci.com/docs/api/v3/pipelines.md): Pipeline definitions describe how to build, test, and deploy a project.
- [Projects](https://circleci.com/docs/api/v3/projects.md): Projects represent a source code repository connected to CircleCI. A project typically contains pipelines, environment variables, and settings.
- [Provider Branches](https://circleci.com/docs/api/v3/provider-branches.md): VCS provider branches available to a project.
- [Provider Connections](https://circleci.com/docs/api/v3/provider-connections.md): Connections between an organization and a VCS provider. Setup returns where to send the user; nothing is connected until they finish at the provider.
- [Provider Repositories](https://circleci.com/docs/api/v3/provider-repositories.md): Repositories an organization's provider installation can reach, as the calling user sees them. Scoped via filter[org_id] and filter[provider]; cursor-paged.
- [Runner Agents](https://circleci.com/docs/api/v3/runner-agents.md): Self-hosted runner agents connected to a resource class. Read-only, scoped via filter[resource_class].
- [Runner Resource Classes](https://circleci.com/docs/api/v3/runner-resource-classes.md): Self-hosted runner resource classes — the pool identifier agents register against and jobs request work from.
- [Runner Tokens](https://circleci.com/docs/api/v3/runner-tokens.md): Authentication tokens for self-hosted runners.
- [Runs](https://circleci.com/docs/api/v3/runs.md): Runs record each trigger firing and group the workflows they produce. A run carries VCS context, parameter overrides, and pre-workflow errors.
- [Sidecar Commands](https://circleci.com/docs/api/v3/sidecar-commands.md): Commands sent to a sidecar instance for execution.
- [Sidecar Instances](https://circleci.com/docs/api/v3/sidecar-instances.md): Lightweight microVM environments that mirror a project's stack for inner-loop validation.
- [Sidecar Snapshots](https://circleci.com/docs/api/v3/sidecar-snapshots.md): Point-in-time snapshots of a sidecar instance's filesystem and state.
- [Signing Certificates](https://circleci.com/docs/api/v3/signing-certificates.md): Apple code-signing certificates used to sign iOS builds.
- [Signing Configs](https://circleci.com/docs/api/v3/signing-configs.md): iOS signing configurations pairing a certificate with provisioning profiles.
- [Tool Releases](https://circleci.com/docs/api/v3/tool-releases.md): Released versions of the tools CircleCI distributes, such as circleci-cli and chunk-cli. Requires filter[tool], whose values are the tools' GitHub repository names, and returns that tool's latest release.
- [Triggers](https://circleci.com/docs/api/v3/triggers.md): A trigger defines what causes a pipeline to run: a VCS event, a custom webhook, or a cron schedule.
- [Usage](https://circleci.com/docs/api/v3/usage.md): Usage and billing data exports.
- [Users](https://circleci.com/docs/api/v3/users.md): Authenticated identities (human or machine). Use ?filter[user_id]=me to resolve the authenticated identity.
- [Workflows](https://circleci.com/docs/api/v3/workflows.md): Workflows organise jobs into a dependency graph. A run may produce multiple workflows that execute in parallel or sequence.