Create Refine with AI iteration

curl --request POST \
  --url 'https://api-prod.usefini.com/v2/fix-review/interactions/0b8626b0-4cc8-4a3d-8fc2-f18ad1a4a1a8/events/f61a9a11-2c3b-4704-8f57-7078854d87cf/sessions/iterations/public' \
  --header 'Authorization: Bearer fini_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "feedbackNote": "The answer should explain the cancellation deadline before linking to Billing Settings."
  }'

import requests

interaction_id = "0b8626b0-4cc8-4a3d-8fc2-f18ad1a4a1a8"
event_id = "f61a9a11-2c3b-4704-8f57-7078854d87cf"
response = requests.post(
    f"https://api-prod.usefini.com/v2/fix-review/interactions/{interaction_id}/events/{event_id}/sessions/iterations/public",
    headers={"Authorization": "Bearer fini_your_api_key"},
    json={
        "feedbackNote": "The answer should explain the cancellation deadline before linking to Billing Settings."
    },
)
job = response.json()

const interactionId = "0b8626b0-4cc8-4a3d-8fc2-f18ad1a4a1a8";
const eventId = "f61a9a11-2c3b-4704-8f57-7078854d87cf";

const response = await fetch(
  `https://api-prod.usefini.com/v2/fix-review/interactions/${interactionId}/events/${eventId}/sessions/iterations/public`,
  {
    method: "POST",
    headers: {
      Authorization: "Bearer fini_your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      feedbackNote:
        "The answer should explain the cancellation deadline before linking to Billing Settings.",
    }),
  }
);
const job = await response.json();

{
  "sessionId": "91d2d432-b408-4496-920d-24ad6a1b9e87",
  "iterationId": "55ce8421-3da6-49f7-af02-b0f23458437d",
  "backgroundJobId": "641482a8-a952-42d2-bceb-67ca06b79e92"
}

{
  "statusCode": 400,
  "message": "A fix iteration is already running for this response",
  "error": "Bad Request"
}

{
  "statusCode": 403,
  "message": "API key does not have the required scope for this operation",
  "error": "Forbidden"
}

POST

fix-review

interactions

{id}

events

{eventId}

sessions

iterations

public

curl --request POST \
  --url 'https://api-prod.usefini.com/v2/fix-review/interactions/0b8626b0-4cc8-4a3d-8fc2-f18ad1a4a1a8/events/f61a9a11-2c3b-4704-8f57-7078854d87cf/sessions/iterations/public' \
  --header 'Authorization: Bearer fini_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "feedbackNote": "The answer should explain the cancellation deadline before linking to Billing Settings."
  }'

import requests

interaction_id = "0b8626b0-4cc8-4a3d-8fc2-f18ad1a4a1a8"
event_id = "f61a9a11-2c3b-4704-8f57-7078854d87cf"
response = requests.post(
    f"https://api-prod.usefini.com/v2/fix-review/interactions/{interaction_id}/events/{event_id}/sessions/iterations/public",
    headers={"Authorization": "Bearer fini_your_api_key"},
    json={
        "feedbackNote": "The answer should explain the cancellation deadline before linking to Billing Settings."
    },
)
job = response.json()

const interactionId = "0b8626b0-4cc8-4a3d-8fc2-f18ad1a4a1a8";
const eventId = "f61a9a11-2c3b-4704-8f57-7078854d87cf";

const response = await fetch(
  `https://api-prod.usefini.com/v2/fix-review/interactions/${interactionId}/events/${eventId}/sessions/iterations/public`,
  {
    method: "POST",
    headers: {
      Authorization: "Bearer fini_your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      feedbackNote:
        "The answer should explain the cancellation deadline before linking to Billing Settings.",
    }),
  }
);
const job = await response.json();

{
  "sessionId": "91d2d432-b408-4496-920d-24ad6a1b9e87",
  "iterationId": "55ce8421-3da6-49f7-af02-b0f23458437d",
  "backgroundJobId": "641482a8-a952-42d2-bceb-67ca06b79e92"
}

{
  "statusCode": 400,
  "message": "A fix iteration is already running for this response",
  "error": "Bad Request"
}

{
  "statusCode": 403,
  "message": "API key does not have the required scope for this operation",
  "error": "Forbidden"
}

Starts a Refine with AI iteration for one Fini response. Fini creates or reuses the response’s active review session, queues asynchronous analysis and replay, and immediately returns identifiers you can use to poll the session.

This endpoint needs write scope. Creating an iteration generates recommendations and a replay, but does not publish or apply the suggested changes.

Use this endpoint when you already know the conversation ID and Fini response event ID to review. Use List conversations or Get conversation to discover event IDs before queueing a review.

Headers

string

required

Bearer token containing your Fini workspace API key. Format: Bearer fini_... The key needs write scope.

string

required

Send application/json.

Path parameters

string

required

Conversation ID containing the response to review.

string

required

ID of the Fini response to review. The event must belong to the conversation and have a linked user event so Fini can replay it.

Body parameters

string

required

Description of what was wrong with the response or how it should improve. Must be non-empty and at most 2,000 characters.

Request example

curl --request POST \
  --url 'https://api-prod.usefini.com/v2/fix-review/interactions/0b8626b0-4cc8-4a3d-8fc2-f18ad1a4a1a8/events/f61a9a11-2c3b-4704-8f57-7078854d87cf/sessions/iterations/public' \
  --header 'Authorization: Bearer fini_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "feedbackNote": "The answer should explain the cancellation deadline before linking to Billing Settings."
  }'

import requests

interaction_id = "0b8626b0-4cc8-4a3d-8fc2-f18ad1a4a1a8"
event_id = "f61a9a11-2c3b-4704-8f57-7078854d87cf"
response = requests.post(
    f"https://api-prod.usefini.com/v2/fix-review/interactions/{interaction_id}/events/{event_id}/sessions/iterations/public",
    headers={"Authorization": "Bearer fini_your_api_key"},
    json={
        "feedbackNote": "The answer should explain the cancellation deadline before linking to Billing Settings."
    },
)
job = response.json()

const interactionId = "0b8626b0-4cc8-4a3d-8fc2-f18ad1a4a1a8";
const eventId = "f61a9a11-2c3b-4704-8f57-7078854d87cf";

const response = await fetch(
  `https://api-prod.usefini.com/v2/fix-review/interactions/${interactionId}/events/${eventId}/sessions/iterations/public`,
  {
    method: "POST",
    headers: {
      Authorization: "Bearer fini_your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      feedbackNote:
        "The answer should explain the cancellation deadline before linking to Billing Settings.",
    }),
  }
);
const job = await response.json();

Response

string

Active Refine with AI session ID. A later iteration for the same response can reuse this session while it remains active.

string

ID of the newly queued iteration.

string

ID of the background job processing the iteration.

{
  "sessionId": "91d2d432-b408-4496-920d-24ad6a1b9e87",
  "iterationId": "55ce8421-3da6-49f7-af02-b0f23458437d",
  "backgroundJobId": "641482a8-a952-42d2-bceb-67ca06b79e92"
}

{
  "statusCode": 400,
  "message": "A fix iteration is already running for this response",
  "error": "Bad Request"
}

{
  "statusCode": 403,
  "message": "API key does not have the required scope for this operation",
  "error": "Forbidden"
}

Polling the result

The response only confirms that processing was queued. Poll Get Refine with AI session with the returned sessionId, or call Get active Refine with AI session for the selected response. An iteration progresses through queued, generating_changes, and replaying. A terminal result is ready, no_change, or failed. Older ready iterations can become superseded, and applied iterations use published. When the session returns a ready latestIteration, use oldAnswerSnapshot and newAnswerSnapshot to compare the original response with the replayed response. Use changes to find the proposed prompt, knowledge, or rule drafts. The create response does not contain those results because the work runs asynchronously. For the dashboard workflow and review model, see Refine with AI.

Errors

400 Bad Request

The feedback is empty or longer than 2,000 characters, an iteration is already in progress, the event does not belong to the conversation, the event is not Fini-authored, or it has no linked user event for replay.

401 Unauthorized

The API key is missing, malformed, revoked, or invalid.

403 Forbidden

The API key does not include the write scope required for this route.

404 Not Found

The conversation or target event does not exist in the workspace.

500 Internal Server Error

Fini could not create or queue the Refine with AI iteration.

⌘I

​Headers

​Path parameters

​Body parameters

​Request example

​Response

​Polling the result

​Errors

Headers

Path parameters

Body parameters

Request example

Response

Polling the result

Errors