Update a Completion

Endpoint

POST /api/v2/projects/{project_id}/completions/{completion_id}

Description

Updates an existing completion record by appending new messages and/or evaluation results. This endpoint allows you to incrementally build upon a completion session by adding conversation messages or attaching evaluation metrics.

Path Parameters

Parameter	Type	Required	Description
`completion_id`	UUID	Yes	The unique identifier of the completion to update

Request Body

The request body must be a JSON object conforming to RecordUpdatePayloadV2:

Field	Type	Required	Description
`new_messages`	Array	Conditional*	Array of message objects to append to the completion
`eval_results`	Array/Object	Conditional*	Evaluation results to attach to the completion

*At least one of new_messages or eval_results must be provided.

Responses

Success (200 OK)

{
  "completion_id": "550e8400-e29b-41d4-a716-446655440000"
}

Error Responses

404 Not Found - Completion not found or not accessible

{
  "error": "Completion not found",
  "completion_id": "550e8400-e29b-41d4-a716-446655440000"
}

400 Bad Request - Invalid request payload

{
  "error": "Must provide at least one of new_messages or eval_results"
}

400 Bad Request - JSON decode error

{
  "error": "Invalid JSON format",
  "details": "..."
}

Example Request

Adding New Messages

curl -X POST https://app.freeplay.ai/completions/550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "new_messages": [
      {
        "role": "user",
        "content": "What is the capital of France?"
      },
      {
        "role": "assistant",
        "content": "The capital of France is Paris."
      }
    ]
  }'

Adding Evaluation Results

curl -X POST https://app.freeplay.ai/completions/550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "eval_results": {
      "accuracy": 0.95,
      "relevance": 0.88,
      "completeness": 0.92
    }
  }'

Adding Both Messages and Evaluation Results

curl -X POST https://app.freeplay.ai/completions/550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "new_messages": [
      {
        "role": "user",
        "content": "Explain quantum computing"
      },
      {
        "role": "assistant",
        "content": "Quantum computing uses quantum bits..."
      }
    ],
    "eval_results": {
      "coherence": 0.91,
      "technical_accuracy": 0.87
    }
  }'

Example Response

{
  "completion_id": "550e8400-e29b-41d4-a716-446655440000"
}

Notes

The completion must exist and be associated with the authenticated account
The completion must belong to the current project context
Messages are appended to the existing completion (not replaced)
The endpoint performs incremental updates only