> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiinsurance.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Invoke the rating engine or supply external rating results via API

<Note>
  **Planned** — Rating endpoints are being added to the v1 API. See the [Roadmap](/api-v1-reference/roadmap) for overall API direction.
</Note>

The Rating API lets you compute premium and rating results for a quote or endorsement. Two approaches serve different use cases, and they can be used together.

## Hosted Rating

Invoke the AI Insurance-configured rating engine for a quote or endorsement. The system runs the configured rater (per company), computes results, and writes them to the rating response fields.

### Planned Endpoints

| Method | Endpoint                                     | Description                                         |
| ------ | -------------------------------------------- | --------------------------------------------------- |
| POST   | `/v1/quotes/{quoteId}/rate`                  | Invoke the configured rating engine for a quote     |
| POST   | `/v1/policies/{policyId}/rating/endorsement` | Rate an endorsement (a set of deltas) for a policy  |
| POST   | `/v1/rating/rate`                            | General rating — feed in a segment and get it rated |

### How It Works

1. Call the appropriate rating endpoint for your use case
2. The system invokes the rating engine configured for your company
3. Rating results are written to the `policyRatingResponse` and `exposureRatingResponse` fields
4. The response returns the computed rating results

### When to Use

* You use AI Insurance's built-in rating engine
* You want the system to compute premium based on your configured rating logic
* You want a single API call to rate and store results

## External Rating (Bring Your Own Engine)

If you compute rating externally, no new endpoint is needed. Write your rating results directly to the quote or endorsement using the existing update endpoints.

### How It Works

1. Compute rating results in your own system
2. Call `PUT /v1/quotes/{quoteId}` (or the endorsement update endpoint) with `policyRatingResponse` and `exposureRatingResponse` fields populated
3. The system treats these as regular field data — no special handling required

### When to Use

* You have a proprietary rating engine
* Rating is computed outside AI Insurance
* You need full control over the rating calculation

## Both Approaches Work Together

The API doesn't require rating results to come from any specific source. Whether you use hosted rating, external rating, or a combination, the downstream workflow is the same: once rating fields are populated on a quote or endorsement, it can proceed through the workflow.

## Permissions

| Operation                 | Permission             |
| ------------------------- | ---------------------- |
| Rate a quote (hosted)     | `company.quote:rate`   |
| Update a quote (external) | `company.quote:update` |

## Related Resources

* [Quotes API](/api-v1-reference/quotes/overview) — create and manage quotes
* [Policy API](/api-v1-reference/policies/overview) — bind rated quotes into policies
* [Roadmap](/api-v1-reference/roadmap) — overall API direction