canonical: https://jentic.com/apis/crucible.local/crucible

# Crucible

Crucible is Atlassian's on-premise code review product, used by teams that hold their source control inside the firewall. The REST API exposes 79 endpoints across project listing, repository browsing, and the full code-review lifecycle including creating reviews, attaching changesets, files, and patches, posting general or line-anchored comments, and closing reviews. Authentication runs through the `/rest-service/auth-v1/login` endpoint, which establishes a session for subsequent calls.

## For AI agents

List projects, browse repositories, create code reviews, post review comments, and manage Crucible review lifecycles on a local Crucible instance.

## Scope

Does not handle the underlying source-control system, build pipelines, or Jira issue tracking - use for Crucible code reviews and repository browsing only.

## Capabilities

- List projects and repositories on the Crucible instance
- Browse repository content, change history, and individual revisions
- Create code reviews and attach changesets, files, or patches to a review
- Post general or line-anchored comments on a review and reply within threads
- Filter and search reviews with details, including by repository or saved filter
- Close reviews and run review actions through the /actions endpoint

## Use cases

### Automated Review Creation from CI

Open a Crucible review automatically when a CI build attaches the relevant changeset by calling POST `/rest-service/reviews-v1` to create the review and POST `/rest-service/reviews-v1/{id}/addChangeset` to attach the changes. Engineering teams using Crucible alongside an on-prem build pipeline use this so every release branch produces a review record without a developer creating it by hand. POST `/rest-service/reviews-v1/{id}/close` finishes it once approvals land.

Example prompt: Create a Crucible review titled 'Release 2.4 hotfix' and attach changeset CR-1234 to it via /addChangeset

### Review Comment Aggregation

Pull every review's comments into a reporting database by listing reviews via `/rest-service/reviews-v1/filter`, then calling `/rest-service/reviews-v1/{id}/comments` per review. Engineering management teams use this to surface review velocity, blockers, and outstanding comment threads without depending on the Crucible UI.

Example prompt: List reviews matching the 'open' filter and pull every comment from each via `/reviews-v1/{id}/comments`

### Repository Browsing and History

Surface repository content and change history outside Crucible's UI by calling `/rest-service/repositories-v1/browse/{repository}/{path}`, `/content/{repository}/{revision}/{path}`, and `/history/{repository}/{revision}/{path}.` This is useful when integrating Crucible's view of the source tree into another tool or chat surface.

Example prompt: Browse the contents of repository core at path src/main/java and list the files at HEAD

### AI Agent Review Triage

An AI agent triages a backlog of open Crucible reviews through Jentic. The agent searches for the crucible_filter_reviews operation, executes against the user's vaulted Crucible session credentials, and produces a ranked list of reviews most in need of attention based on age, comment count, and reviewer load. Jentic isolates the session credential so the agent never sees the raw login.

Example prompt: Use the Jentic SDK to log in to Crucible, list open reviews, and rank them by oldest unanswered comment

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/rest-service/auth-v1/login` | Establish a Crucible session |
| POST | `/rest-service/reviews-v1` | Create a new code review |
| POST | `/rest-service/reviews-v1/{id}/addChangeset` | Attach a changeset to a review |
| POST | `/rest-service/reviews-v1/{id}/addFile` | Attach a file to a review |
| POST | `/rest-service/reviews-v1/{id}/comments` | Post a comment on a review |
| POST | `/rest-service/reviews-v1/{id}/close` | Close a review |
| GET | `/rest-service/reviews-v1/filter` | Filter reviews by criteria |

## Key resources

- **Authentication** — Establish a Crucible session via GET or POST `/rest-service/auth-v1/login`
- **Projects** — List projects and retrieve project details via `/rest-service/projects-v1` endpoints
- **Repositories** — Browse content, changes, history, and revisions via `/rest-service/repositories-v1` endpoints
- **Reviews** — Create, filter, search, retrieve, comment on, and close reviews via `/rest-service/reviews-v1` endpoints, including /addChangeset, /addFile, /addPatch, /comments, /actions, and /close

## Why Jentic

- **Setup:** Wiring Crucible by hand means running its `/rest-service/auth-v1/login` exchange, holding the session for reuse, and posting review, changeset, and comment payloads yourself. Through Jentic you install once, import Crucible from the API Directory, store the username and password once, and your agent calls it.
- **Permission scoping:** Crucible puts the review id in the URL path (`/rest-service/reviews-v1/{id}/...`), so a rule can pin your agent to one review: it can add changesets, files, and comments to that review and nothing else. You choose the operations it may call, so closing a review is not included unless you add it.
- **Credential handling:** Your Crucible username and password are stored once, encrypted, by your own Jentic One instance and injected at execution time, including the login exchange. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a Crucible review' or 'list open reviews', and Jentic returns the matching Crucible operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **crowd.dev API** — crowd.dev tracks community contributions while Crucible handles internal code review on the same codebase
- **Cronitor API** — Cronitor monitors scheduled jobs that may sync Crucible review data to a reporting warehouse
- **Cron-job.org API** — cron-job.org schedules recurring HTTP calls that can drive Crucible review-list polling

## FAQ

### What authentication does the Crucible API use?

Crucible uses session-based authentication. Clients call POST `/rest-service/auth-v1/login` with username and password and reuse the resulting session cookie on subsequent requests. Through Jentic the username and password are held encrypted in the vault and Jentic handles the login exchange so the agent never sees the credentials.

### Can I create a code review through the API?

Yes. POST `/rest-service/reviews-v1` creates a review, and follow-up calls to `/rest-service/reviews-v1/{id}/addChangeset`, /addFile, or /addPatch attach the actual code under review. POST `/rest-service/reviews-v1/{id}/close` ends the review once it is approved.

### How do I filter reviews by repository or status?

GET `/rest-service/reviews-v1/filter` accepts filter parameters and returns matching reviews; `/filter/{filter}` returns the reviews under a saved filter, and `/search/{repository}` narrows by repository. The /details variants return enriched review payloads.

### How do I create a review through Jentic?

Search Jentic for 'create a Crucible review', load the operation schema for POST `/rest-service/reviews-v1`, and execute with the project key, title, and reviewer list. Jentic handles the login session so the agent doesn't need to manage cookies.

### How many endpoints does the Crucible API expose?

Seventy-nine endpoints across authentication, projects, repository browsing, reviews, review actions and comments, and review search and filter operations.

### Can I post a comment on a specific line of a review?

Yes. POST `/rest-service/reviews-v1/{id}/comments` creates a comment, and the `/comments/versioned` endpoint exposes file-and-line-anchored comments so an agent can attach feedback to specific code lines.

### Can I limit what my agent is allowed to do with the Crucible API?

Yes. Because your Jentic One instance is self-hosted, your own rules decide which Crucible operations the agent may call and which credentials it may use. Since Crucible puts the review id in the URL path (`/rest-service/reviews-v1/{id}/...`), you can pin the agent to a single review so it can add changesets, files, and comments to that review and nothing else. Closing a review via `/rest-service/reviews-v1/{id}/close` is not included unless you explicitly allow it.