# Atlassian Compass

> Atlassian Compass is a developer experience platform (internal developer platform) that catalogs
> software components, tracks their health with scorecards and metrics, maps dependencies between
> them, and ingests build, deployment, incident and vulnerability events from a team's toolchain.
> It is sold as a hosted Atlassian Cloud product on a per-user subscription.

IMPORTANT LIFECYCLE NOTICE: On 13 April 2026 Atlassian announced that Compass is being phased out
and that its scorecard and catalog capabilities will move to the DX Engineering Intelligence
Platform (DX Fabric). Atlassian states there is no immediate change to access and has not published
a sunset date. See https://www.atlassian.com/blog/announcements/the-next-chapter-for-compass

Generated by API Evangelist from this provider's public surface and this repository's artifacts.
Not published by Atlassian. Source of truth is https://developer.atlassian.com/cloud/compass/

## Interfaces

Compass exposes three non-identical surfaces. They are not projections of each other and none is a
superset:

- Atlassian platform GraphQL API — https://api.atlassian.com/graphql — the full Compass catalog:
  components, component types, relationships, scorecards, custom fields, metric definitions, event
  sources, teams, campaigns. 44 query fields and 84 mutations under the `compass` root field.
  Docs: https://developer.atlassian.com/cloud/compass/graphql/
- Compass REST API v1 — https://your-domain.atlassian.net/gateway/api — an ingestion and attachment
  surface only: 11 operations covering metrics, events, package dependencies, Forge-app attachments,
  API spec upload, incoming webhooks and entitlement evaluation. It cannot create or read a
  component. Contract: https://developer.atlassian.com/cloud/compass/swagger.v3.json
  Docs: https://developer.atlassian.com/cloud/compass/rest/
- Atlassian Rovo MCP Server — https://mcp.atlassian.com/v2/mcp — the official remote MCP server.
  Atlassian lists Compass among its supported products under the read_compass and write_compass
  permission groups (OAuth 2.1 only; API-token authentication is not supported for Compass).
  Compass components are reached through the Teamwork Graph tools.

## Authentication

- REST: HTTP Basic with an Atlassian account email and an API token from
  https://id.atlassian.com/manage/api-tokens. Authorization is the authenticating user's own access.
- GraphQL / OAuth 2.0 (3LO): authorize at https://auth.atlassian.com/authorize, token at
  https://auth.atlassian.com/oauth/token. Scopes observed in the contract:
  read:component:compass, write:component:compass, write:event:compass, write:metric:compass.
- MCP: OAuth 2.1 with dynamic client registration at https://mcp.atlassian.com/v1/register.
- Discovery: https://auth.atlassian.com/.well-known/openid-configuration and
  https://mcp.atlassian.com/.well-known/oauth-protected-resource/v2/mcp are both served anonymously.

## Rate limits

The published contract states the metrics and events endpoints are limited to 100 requests per user
per minute and return HTTP 429 on exhaustion. Atlassian does not publish rate-limit response headers
for Compass.

## Errors

REST errors return {"errors":[{"type":"...","message":"..."}]}. GraphQL query errors arrive in
QueryError objects and mutation errors in the mutation payload, both carrying extensions.statusCode
and extensions.errorType. Atlassian publishes a registry of roughly 75 stable errorType codes at
https://developer.atlassian.com/cloud/compass/error-handling/error-types/

## Key operations (REST, from the published OpenAPI)

- insertMetricValue — POST /compass/v1/metrics
- createCompassEvent — POST /compass/v1/events
- uploadLockFile — PUT /compass/v1/package_dependencies/lock_file
- deleteLockFile — DELETE /compass/v1/package_dependencies/lock_file/{componentId}/{sourceId}
- uploadAPISpec — PUT /compass/v1/component/{componentId}/api_specs
- deleteAPISpec — DELETE /compass/v1/component/{componentId}/api_specs
- uploadAttachment / getAttachment / deleteAttachment —
  /compass/v1/component/{componentId}/app/{forgeAppId}/attachment/{key}
- handleWebhookInvocation — POST /compass/v1/webhooks/{webhookId}
- evaluateEntitlements — POST /compass/v1/entitlements

## Docs

- Developer portal: https://developer.atlassian.com/cloud/compass/
- Getting started: https://developer.atlassian.com/cloud/compass/integrations/get-started-integrating-with-Compass/
- REST reference: https://developer.atlassian.com/cloud/compass/rest/
- GraphQL reference: https://developer.atlassian.com/cloud/compass/graphql/
- GraphQL API toolkit: https://developer.atlassian.com/cloud/compass/integrations/graphql-api-toolkit/
- Error guide: https://developer.atlassian.com/cloud/compass/error-handling/error-types/
- Changelog: https://developer.atlassian.com/cloud/compass/changelog/
- Config as code: https://developer.atlassian.com/cloud/compass/config-as-code/what-is-config-as-code/
- Example apps: https://github.com/atlassian-labs/compass-examples

## Client libraries

Atlassian publishes no Compass-branded SDK. Integrators install Forge platform packages:
@atlassian/forge-graphql (the GraphQL API toolkit, which the Compass docs say provides API methods
only for Compass), @atlassian/forge-graphql-types, and @forge/cli.

## Commercial

- Pricing: https://www.atlassian.com/software/compass/pricing — Free ($0, up to 3 full users),
  Standard ($7.67/user/month), Premium ($23.96/user/month), Enterprise.
- Terms: https://www.atlassian.com/legal/cloud-terms-of-service
- Privacy: https://www.atlassian.com/legal/privacy-policy
- Status: https://status.atlassian.com/
- Security contact: https://www.atlassian.com/.well-known/security.txt