# Guide API

The Guide API provides REST APIs for searching component and vulnerability data

# Using a token

To authenticate API requests, you'll need to create a Personal Access Token, tokens are used with Bearer authentication for programmatic access to the API. [Manage your tokens](https://guide.sonatype.com/settings/tokens) to get started.

## Bearer Authentication:

```bash
curl -H "Authorization: Bearer <your-token>"
  https://api.guide.sonatype.com/users/me
```

# Sonatype Guide API  ``` OAS 3.1 ```

REST API for searching component and security vulnerability data.

## Servers

https://api.guide.sonatype.com - API Server

## Authorize

### [Usage](https://guide.sonatype.com/api#/Usage)    Credit usage and billing period APIs

GET
[/usage](https://guide.sonatype.com/api#/Usage/getUsage)

Get usage information

GET
[/usage/ossi-history](https://guide.sonatype.com/api#/Usage/getOssiUsageHistory)

Get historical OSSI usage

GET
[/usage/cumulative](https://guide.sonatype.com/api#/Usage/getCumulativeUsage)

Get cumulative credit usage for a billing period

GET
[/usage/credit-periods](https://guide.sonatype.com/api#/Usage/getCreditPeriods)

Get credit periods

### [Vulnerabilities](https://guide.sonatype.com/api#/Vulnerabilities)    Vulnerability search and filtering API

GET
[/vulnerabilities/{id}](https://guide.sonatype.com/api#/Vulnerabilities/getVulnerabilityByRefId)

Get vulnerability by ID

GET
[/vulnerabilities/{id}/components](https://guide.sonatype.com/api#/Vulnerabilities/getVulnerabilityAffectedComponents)

Get affected components for a vulnerability

### [AGP Dashboard](https://guide.sonatype.com/api#/AGP%20Dashboard)    Connected repository status with search, filter & paging

GET
[/api/agp/dashboard](https://guide.sonatype.com/api#/AGP%20Dashboard/dashboard)

List connected repositories with status (search, filter & paging)

GET
[/api/agp/dashboard/onboarding-access](https://guide.sonatype.com/api#/AGP%20Dashboard/onboardingAccess)

Whether the caller may onboard repositories

GET
[/api/agp/dashboard/candidate-ids](https://guide.sonatype.com/api#/AGP%20Dashboard/candidateIds)

Ids of all onboarding-candidate repositories matching the name filter

### [Activity Log](https://guide.sonatype.com/api#/Activity%20Log)    Organization activity log APIs

GET
[/users/me/organization/activity-log](https://guide.sonatype.com/api#/Activity%20Log/getActivityLog)

Get organization activity log

### [AGP Bulk Onboarding](https://guide.sonatype.com/api#/AGP%20Bulk%20Onboarding)    Onboard multiple repositories in one operation

POST
[/api/agp/onboarding/bulk](https://guide.sonatype.com/api#/AGP%20Bulk%20Onboarding/start)

Start bulk onboarding for selected repositories

GET
[/api/agp/onboarding/bulk/{jobId}](https://guide.sonatype.com/api#/AGP%20Bulk%20Onboarding/progress)

Get bulk onboarding job progress

GET
[/api/agp/onboarding/bulk/org-activity](https://guide.sonatype.com/api#/AGP%20Bulk%20Onboarding/orgActivity)

Whether another org member currently has a bulk onboarding job in flight

GET
[/api/agp/onboarding/bulk/active](https://guide.sonatype.com/api#/AGP%20Bulk%20Onboarding/active)

Get the caller's currently-running bulk onboarding job, if any

### [AGP Governance](https://guide.sonatype.com/api#/AGP%20Governance)    AgentP feature governance: org-level Default Configuration is Owner-only; per-repo config and lifecycle actions are available to any org member

GET
[/api/agp/repos/{installationRepoId}/config](https://guide.sonatype.com/api#/AGP%20Governance/getRepoConfig)

Get a repo's AgentP config overrides + inherited Default Configuration + version (any org member)

PUT
[/api/agp/repos/{installationRepoId}/config](https://guide.sonatype.com/api#/AGP%20Governance/updateRepoConfig)

Set per-repo AgentP config overrides (any org member)

DELETE
[/api/agp/repos/{installationRepoId}/config](https://guide.sonatype.com/api#/AGP%20Governance/deleteRepoConfig)

Reset a repo to the Default Configuration by clearing its config overrides (any org member)

GET
[/api/agp/org/config](https://guide.sonatype.com/api#/AGP%20Governance/getOrgConfig)

Get the AgentP Default Configuration (read: any org member)

PUT
[/api/agp/org/config](https://guide.sonatype.com/api#/AGP%20Governance/updateOrgConfig)

Set the AgentP Default Configuration + developer-access flag (Owner-only)

POST
[/api/agp/repos/{installationRepoId}/resume](https://guide.sonatype.com/api#/AGP%20Governance/resume)

Resume AgentP for a repository (any org member)

POST
[/api/agp/repos/{installationRepoId}/removal-pr](https://guide.sonatype.com/api#/AGP%20Governance/openRemovalPr)

Open (and optionally merge) a PR removing the AgentP workflow file from a repository (any org member)

POST
[/api/agp/repos/{installationRepoId}/pause](https://guide.sonatype.com/api#/AGP%20Governance/pause)

Pause AgentP for a repository (any org member)

GET
[/api/agp/repos/{installationRepoId}/effective-config](https://guide.sonatype.com/api#/AGP%20Governance/getRepoEffectiveConfig)

Get the rendered effective agp.yml for a repo (defaults + org + overrides) (any org member)

GET
[/api/agp/org/effective-config](https://guide.sonatype.com/api#/AGP%20Governance/getOrgEffectiveConfig)

Get the rendered Default Configuration agp.yml (defaults + org) (Owner-only)

GET
[/api/agp/agentic-mode-access](https://guide.sonatype.com/api#/AGP%20Governance/agenticModeAccess)

Whether the caller's org is registered for AgentP agentic mode (org-scoped; gates the AI Fix toggle + AI agent config in the UI)

### [Current User Tokens](https://guide.sonatype.com/api#/Current%20User%20Tokens)    Personal Access Token management APIs

GET
[/users/me/tokens](https://guide.sonatype.com/api#/Current%20User%20Tokens/listTokens)

List all Personal Access Tokens

POST
[/users/me/tokens](https://guide.sonatype.com/api#/Current%20User%20Tokens/createToken)

Create a new Personal Access Token

POST
[/users/me/tokens/{tokenId}/rotate](https://guide.sonatype.com/api#/Current%20User%20Tokens/rotateToken)

Rotate a Personal Access Token

GET
[/users/me/tokens/{tokenId}](https://guide.sonatype.com/api#/Current%20User%20Tokens/getTokenById)

Get a Personal Access Token by ID

DELETE
[/users/me/tokens/{tokenId}](https://guide.sonatype.com/api#/Current%20User%20Tokens/revokeToken)

Revoke a Personal Access Token

### [Components](https://guide.sonatype.com/api#/Components)    Component search and filtering API

POST
[/components/latest-version](https://guide.sonatype.com/api#/Components/getLatestVersion)

Get latest version of a component

GET
[/components/vulnerabilities](https://guide.sonatype.com/api#/Components/getComponentVulnerabilitiesByPurlQueryParam)

Get vulnerabilities for a component by coordinates (query parameters)

GET
[/components/versions](https://guide.sonatype.com/api#/Components/getComponentVersionsByPurlQueryParam)

Get all component versions by coordinates (query parameters)

GET
[/components/detail](https://guide.sonatype.com/api#/Components/getComponentDetailByPurlQueryParam)

Get component detail by coordinates (query parameters)

GET
[/components/dependencies](https://guide.sonatype.com/api#/Components/getComponentDependenciesByPurlQueryParam)

Get dependencies for a component by coordinates (query parameters)

### [OSS Index Compatibility](https://guide.sonatype.com/api#/OSS%20Index%20Compatibility)    Legacy OSSI API providing backward compatibility. Allows existing OSSI users to continue using their OSSI API tokens without creating a new Sonatype Guide account. Authentication requires HTTP Basic Auth with OSSI username and API token.

POST
[/api/v3/component-report](https://guide.sonatype.com/api#/OSS%20Index%20Compatibility/getComponentReports)

Get component reports for multiple PURLs

POST
[/api/v3/authorized/component-report](https://guide.sonatype.com/api#/OSS%20Index%20Compatibility/getComponentReports_1)

Get component reports for multiple PURLs

GET
[/api/v3/version](https://guide.sonatype.com/api#/OSS%20Index%20Compatibility/getVersion)

Get API version

GET
[/api/v3/authorized/component-report/**](https://guide.sonatype.com/api#/OSS%20Index%20Compatibility/getComponentReport)

Get component report by PURL

GET
[/api/v3/component-report/**](https://guide.sonatype.com/api#/OSS%20Index%20Compatibility/getComponentReport_1)

Get component report by PURL

### [Billing](https://guide.sonatype.com/api#/Billing)    Billing and subscription management API

GET
[/billing](https://guide.sonatype.com/api#/Billing/getBilling)

Get billing information

GET
[/billing/plans](https://guide.sonatype.com/api#/Billing/getPlans)

Get all available plans

GET
[/billing/invoices](https://guide.sonatype.com/api#/Billing/getUserInvoiceHistory)

Get user invoice history

GET
[/billing/invoices/{invoiceId}/pdf](https://guide.sonatype.com/api#/Billing/getInvoicePdf)

Download invoice PDF

### [Current User Organization](https://guide.sonatype.com/api#/Current%20User%20Organization)    Current user organization management APIs

GET
[/users/me/organization](https://guide.sonatype.com/api#/Current%20User%20Organization/getCurrentUserOrganization)

Get current user's organization

PUT
[/users/me/organization](https://guide.sonatype.com/api#/Current%20User%20Organization/updateOrganization)

Update current user's organization

POST
[/users/me/organization/members/invite](https://guide.sonatype.com/api#/Current%20User%20Organization/inviteUsers)

Invite users to current user's organization

POST
[/users/me/organization/invitations/{invitationToken}/accept](https://guide.sonatype.com/api#/Current%20User%20Organization/acceptInvitation)

Accept organization invitation

GET
[/users/me/organization/onboarding-banner](https://guide.sonatype.com/api#/Current%20User%20Organization/getOnboardingBannerStatus)

Get onboarding banner status

DELETE
[/users/me/organization/onboarding-banner](https://guide.sonatype.com/api#/Current%20User%20Organization/dismissOnboardingBanner)

Dismiss onboarding banner

GET
[/users/me/organization/members](https://guide.sonatype.com/api#/Current%20User%20Organization/retrieveOrganizationMembersAsCsv)

Retrieve current user's organization members and invitees

DELETE
[/users/me/organization/members](https://guide.sonatype.com/api#/Current%20User%20Organization/bulkRemoveMembersOrInvitations)

Bulk remove members or invitations from organization

DELETE
[/users/me/organization/membership](https://guide.sonatype.com/api#/Current%20User%20Organization/leaveOrganization)

Leave organization

DELETE
[/users/me/organization/members/{email}](https://guide.sonatype.com/api#/Current%20User%20Organization/removeMemberOrInvitation)

Remove member or invitation from organization

### [Recommendations](https://guide.sonatype.com/api#/Recommendations)    Version upgrade recommendation API

POST
[/recommendations](https://guide.sonatype.com/api#/Recommendations/getRecommendations)

Get version upgrade recommendations

Retrieves version upgrade recommendations for a component specified by PURL. Analyzes security vulnerabilities, stability metrics, and policy compliance to suggest optimal upgrade paths. Only policy-compliant versions are returned. If policy evaluation fails, the response is BLOCKED_BY_POLICY (fail-closed).

#### Parameters

No parameters

#### Request body

application/json

- Example Value
- Schema

RecommendationRequest

Collapse all **object**

Request body containing the component PURL

- purl

**string**

- extension

**string**

- classifier

**string**

#### Responses

| Code | Description | Links |
| --- | --- | --- |
| 200 | Success. Returns fromVersion and toVersions array (empty if component is already optimal or all candidates violate policy)<br>Media type<br>*/ *<br>Controls `Accept` header.<br>- Example Value<br>- Schema<br>RecommendationResponse<br>Collapse all **object**<br>- outcome<br>  <br>  <br>Expand all **string**<br>  <br>- fromVersion<br>  <br>  <br>Expand all **object**<br>  <br>- toVersions<br>  <br>  <br>Expand all **array<object>** | _No links_ |
| 400 | Invalid request - malformed PURL or missing required parameters<br>Media type<br>*/ *<br>- Example Value<br>- Schema<br>RecommendationResponse<br>Collapse all **object**<br>- outcome<br>  <br>  <br>Expand all **string**<br>  <br>- fromVersion<br>  <br>  <br>Expand all **object**<br>  <br>- toVersions<br>  <br>  <br>Expand all **array<object>** | _No links_ |
| 404 | Component not found or no recommendations available<br>Media type<br>*/ *<br>- Example Value<br>- Schema<br>RecommendationResponse<br>Collapse all **object**<br>- outcome<br>  <br>  <br>Expand all **string**<br>  <br>- fromVersion<br>  <br>  <br>Expand all **object**<br>  <br>- toVersions<br>  <br>  <br>Expand all **array<object>** | _No links_ |