Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.selftune.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Proposals API lets you list, retrieve, and apply improvement proposals generated by cloud improve runs. Proposals represent suggested changes to a skill’s content, backed by eval evidence. All endpoints require a Bearer token in the Authorization header.

​
List proposals

GET /api/v1/proposals
Returns all proposals for the authenticated account. Response: 
{
  "proposals": [
    {
      "id": "prop_abc123",
      "skill_name": "my-skill",
      "proposal_type": "wording_change",
      "status": "pending",
      "confidence": 0.87,
      "created_at": "2026-04-16T10:00:00Z"
    }
  ]
}

​
Get proposal detail

GET /api/v1/proposals/:id
Returns the full proposal including eval summary, proposed change, and verifier breakdown. Response: 
{
  "proposal": {
    "id": "prop_abc123",
    "skill_name": "my-skill",
    "proposal_type": "wording_change",
    "status": "pending",
    "current_value": "...",
    "proposed_value": "...",
    "reason": "Trigger overlap with adjacent skill caused 14% misroute rate.",
    "confidence": 0.87,
    "candidate_count": 4,
    "applied_at": null,
    "cloud_candidate_id": "cand_xyz789",
    "created_at": "2026-04-16T10:00:00Z"
  }
}

​
Apply a proposal

POST /api/v1/proposals/:id/apply
Applies a pending or approved proposal to a target stage. Currently the only supported target is draft. Request body: 
{
  "candidate_id": "cand_xyz789",
  "target": "draft"
}
FieldTypeDescription
candidate_idstringID of the cloud candidate to apply. Found in the proposal’s cloud_candidate_id field.
targetstringApply destination. Must be "draft".
Response: 
{
  "success": true,
  "applied_at": "2026-04-16T12:34:56Z"
}
Error response: 
{
  "error": "Proposal already applied"
}
Status codes:
CodeMeaning
200Proposal applied successfully
400Invalid request body or unsupported target
404Proposal not found
409Proposal already applied or rejected
401Missing or invalid token
Applying a proposal writes the change to draft only. Proposals with applied or rejected status cannot be re-applied.

​
Example

curl -X POST https://api.selftune.dev/api/v1/proposals/prop_abc123/apply \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "candidate_id": "cand_xyz789",
    "target": "draft"
  }'