All

Playbook Management

Methods for reviewing, searching, retrieving, adding, and deleting user playbooks and agent playbooks.

Playbook Management

`search_user_playbooks`

Search for user playbooks using semantic/text search and advanced filtering. On authenticated requests, served results are synchronously recorded as evidence before a successful response returns. If recording fails, the search fails; empty results create no evidence batch.

response = client.search_user_playbooks(
    query="user satisfaction",
    user_id="user_123",
    request_id="request_123",
    session_id="session_123",
    agent_version="v2.1.0",
    source="api",
    tags=["support"],
    top_k=10
)

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/search_user_playbooks" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "query": "user satisfaction",
  "user_id": "user_123",
  "request_id": "request_123",
  "session_id": "session_123",
  "agent_version": "v2.1.0",
  "source": "api",
  "tags": ["support"],
  "top_k": 10
}
JSON

Prop

Type

`review_user_playbooks`

Re-run the evidence-grounded reviewer over the newest current user playbooks created in an inclusive time window. top_k is applied in newest-first order. For each selected playbook, the server loads the full interaction window recorded by its finalized playbook-extraction run, adds any extra cited interactions retained through consolidation, and restores request grouping. Historical review is therefore not limited by the playbook's smaller cited-evidence subset, the current extraction window size, or the current source filter. Only cited IDs are presented as candidate evidence; the remaining generation-window interactions provide chronology without becoming additional evidence.

The default report mode runs inline and returns decisions without changing storage, while simulating the same newest-first context transitions as apply mode. Because each selected playbook receives a fresh model review, the server automatically gives this endpoint its extended synchronous timeout. A playbook is reported as skip when its finalized generation-window provenance, validated evidence metadata, or a required interaction/request is unavailable, or when its ownership provenance does not match the requesting user; the run then continues. The automatic reviewer that runs immediately after generation separately uses that generation's configured extraction window.

Set report_only=False to apply the decisions. Apply mode is accepted and run in the background — the response returns immediately with a run_id and an empty results list, because a run makes one model call and one write per selected playbook. The run reviews newest-first and commits each completed decision before reviewing the next playbook: accepted rows stay current, rejected rows are archived, and an edit inserts the replacement as current while superseding its incumbent. A later failure stops the run but leaves earlier decisions committed. Applied edits are recorded on the replacement's lineage under the returned run_id.

from datetime import UTC, datetime

response = client.review_user_playbooks(
    start_time=datetime(2026, 7, 1, tzinfo=UTC),
    end_time=datetime(2026, 7, 28, tzinfo=UTC),
    top_k=50,
    report_only=True,
)

for result in response.results:
    print(result.user_playbook_id, result.decision, result.reason)

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/review_user_playbooks" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "start_time": "2026-07-01T00:00:00Z",
  "end_time": "2026-07-28T23:59:59Z",
  "top_k": 50,
  "report_only": true
}
JSON

Prop

Type

See ReviewUserPlaybooksResponse for result fields and decision details.

`search_agent_playbooks`

Search for agent playbooks using semantic/text search and advanced filtering. The optional source filter matches provenance: an agent playbook is included when at least one linked source user playbook has that exact source.

response = client.search_agent_playbooks(
    query="concise responses",
    user_id="user_123",
    agent_version="v2.1.0",
    source="api",
    tags=["tone"],
    playbook_status_filter="approved"
)

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/search_agent_playbooks" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "query": "concise responses",
  "user_id": "user_123",
  "agent_version": "v2.1.0",
  "source": "api",
  "tags": ["tone"],
  "playbook_status_filter": "approved"
}
JSON

Prop

Type

`get_user_playbooks`

Retrieve user playbook rows containing agent guidance, including entries extracted from interactions and rows created by supported manual or playbook-optimizer workflows.

response = client.get_user_playbooks(
    limit=100,
    tags=["support"]
)

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/get_user_playbooks" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "limit": 100,
  "tags": ["support"]
}
JSON

Prop

Type

`add_user_playbook`

Add user playbook entries directly to storage.

response = client.add_user_playbook(
    user_playbooks=[
        {
            "agent_version": "v2.1.0",
            "request_id": "req_123",
            "content": "User expressed satisfaction with response"
        }
    ]
)

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/add_user_playbook" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "user_playbooks": [
    {
      "agent_version": "v2.1.0",
      "request_id": "req_123",
      "content": "User expressed satisfaction with response"
    }
  ]
}
JSON

Prop

Type

At least one of content or trigger must be provided.

`add_agent_playbooks`

Add agent playbook entries directly to storage.

response = client.add_agent_playbooks(
    agent_playbooks=[
        {
            "agent_version": "v2.1.0",
            "content": "Agent should provide more concise responses",
            "playbook_status": "approved",
            "playbook_metadata": "{}"
        }
    ]
)

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/add_agent_playbook" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "agent_playbooks": [
    {
      "agent_version": "v2.1.0",
      "content": "Agent should provide more concise responses",
      "playbook_status": "approved",
      "playbook_metadata": "{}"
    }
  ]
}
JSON

Prop

Type

`get_agent_playbooks`

Retrieve agent playbook entries.

response = client.get_agent_playbooks(
    limit=10,
    tags=["tone"]
)

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/get_agent_playbooks" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "limit": 10,
  "tags": ["tone"]
}
JSON

Prop

Type

Update Methods

`update_user_playbook`

Update editable fields of a user playbook in place. Pass only the fields you want to change.

response = client.update_user_playbook(
    user_playbook_id=42,
    content="Refined playbook content",
)

curl -X PUT "${REFLEXIO_URL:-https://www.reflexio.ai}/api/update_user_playbook" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "user_playbook_id": 42,
  "content": "Refined playbook content"
}
JSON

Prop

Type

Returns: UpdateUserPlaybookResponse with success and message.

`update_agent_playbook`

Update editable fields of an agent playbook in place. Pass only the fields you want to change.

response = client.update_agent_playbook(
    agent_playbook_id=17,
    content="Updated guidance"
)

curl -X PUT "${REFLEXIO_URL:-https://www.reflexio.ai}/api/update_agent_playbook" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "agent_playbook_id": 17,
  "content": "Updated guidance"
}
JSON

Prop

Type

Returns: UpdateAgentPlaybookResponse with success and message.

`update_agent_playbook_status`

Dedicated endpoint for the approval workflow (approve / pending / reject). Use this instead of update_agent_playbook when the only change is the playbook_status — the server enforces tighter validation and writes a smaller change log.

from reflexio import PlaybookStatus

response = client.update_agent_playbook_status(
    agent_playbook_id=17,
    playbook_status=PlaybookStatus.APPROVED,
)

curl -X PUT "${REFLEXIO_URL:-https://www.reflexio.ai}/api/update_agent_playbook_status" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "agent_playbook_id": 17,
  "playbook_status": "approved"
}
JSON

Prop

Type

Returns: UpdatePlaybookStatusResponse with success and message.

`delete_agent_playbook`

Delete an agent playbook by ID.

response = client.delete_agent_playbook(
    agent_playbook_id=123,
    wait_for_response=True
)

curl -X DELETE "${REFLEXIO_URL:-https://www.reflexio.ai}/api/delete_agent_playbook" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "agent_playbook_id": 123
}
JSON

`delete_user_playbook`

Delete a user playbook by ID.

response = client.delete_user_playbook(
    user_playbook_id=456,
    wait_for_response=True
)

curl -X DELETE "${REFLEXIO_URL:-https://www.reflexio.ai}/api/delete_user_playbook" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "user_playbook_id": 456
}
JSON

Bulk Delete Operations