# Seren Full API Reference

> Generated from `/openapi.json`. Use the OpenAPI document as the source of truth for complete JSON Schema definitions.

OpenAPI version: `3.1.0`
API version: `0.1.0`
Operations: 616
Component schemas: 1236

Schema browser: `/schemas`
Machine-readable schema index: `/schemas/index.json`
Stable operation pages: `/api/operations/{operation_id}`

## Access

### GET /publishers/seren-storage/buckets/{bucket_slug}/agent-grants

Operation ID: `seren_storage_list_bucket_agent_grants`
Operation page: `/api/operations/seren_storage_list_bucket_agent_grants`

Parameters:
- `bucket_slug` (path, required): string - Storage bucket slug

Responses:
- `200` Employee bucket grants retrieved (application/json: SerenStorageDataResponse_Vec_ObjectStorageBucketAgentGrant)
- `403` Organization management permission required (application/json: SerenStorageErrorBody)

### DELETE /publishers/seren-storage/buckets/{bucket_slug}/agent-grants/{agent_identity_id}

Operation ID: `seren_storage_delete_bucket_agent_grant`
Operation page: `/api/operations/seren_storage_delete_bucket_agent_grant`

Parameters:
- `bucket_slug` (path, required): string - Storage bucket slug
- `agent_identity_id` (path, required): string / uuid - Employee identity ID

Responses:
- `204` Employee bucket grant revoked
- `403` Organization management permission required (application/json: SerenStorageErrorBody)

### PUT /publishers/seren-storage/buckets/{bucket_slug}/agent-grants/{agent_identity_id}

Operation ID: `seren_storage_put_bucket_agent_grant`
Operation page: `/api/operations/seren_storage_put_bucket_agent_grant`

Parameters:
- `bucket_slug` (path, required): string - Storage bucket slug
- `agent_identity_id` (path, required): string / uuid - Employee identity ID

Request body (required):
- `application/json`: SerenStoragePutObjectStorageBucketAgentGrantRequest

Responses:
- `200` Employee bucket grant stored (application/json: SerenStorageDataResponse_ObjectStorageBucketAgentGrant)
- `403` Organization management permission required (application/json: SerenStorageErrorBody)

## Account

### PUT /publishers/seren-passwords/account

Operation ID: `account_setup`
Operation page: `/api/operations/account_setup`
Set up the caller's account in the org vault database.

The first call creates the user's identity, seeds the account_secrets row,
and provisions the default Personal vault in one transaction. If the
account is already initialized, the endpoint returns the existing setup
state and does not overwrite any key material.

Request body (required):
- `application/json`: AccountSetupRequest

Responses:
- `200` Account setup state (application/json: DataResponseAccountSetup)
- `400` Malformed setup body
- `403` Agents may not set up user accounts
- `409` Partial existing state; refusing to overwrite
- `422` Request body failed validation

### POST /publishers/seren-passwords/account/recovery/complete

Operation ID: `account_recovery_complete`
Operation page: `/api/operations/account_recovery_complete`
Complete account recovery: replace account_secrets with a freshly wrapped
blob and rotate the recovery key.

Verifies the recovery proof signature over the open challenge plus the
new KEM public key, and rejects completions that reuse the existing
recovery_key_wrap or recovery_kdf_params (so a leaked recovery sheet must
also be retired).

Request body (required):
- `application/json`: RecoveryCompleteRequest

Responses:
- `200` Updated account secrets (application/json: DataResponseAccountSecretsRecord)
- `400` Recovery blob attempted to rotate identity keys, or recovery key was not rotated
- `401` Invalid recovery proof
- `403` Agents may not complete account recovery
- `404` No active identity or matching recovery request
- `409` Recovery request was consumed or expired during verification
- `422` Request body failed validation

### POST /publishers/seren-passwords/account/recovery/initiate

Operation ID: `account_recovery_initiate`
Operation page: `/api/operations/account_recovery_initiate`
Open an account recovery request and receive a random challenge.

The client signs the challenge plus the new KEM public key in
`/account/recovery/complete` to prove possession of the existing account
signing key (recovered using the recovery key).

Responses:
- `200` Recovery challenge issued (application/json: DataResponseRecoveryInitiate)
- `401` Caller is not authenticated
- `403` Agents may not initiate account recovery
- `404` No active identity for this user

### GET /publishers/seren-passwords/account/secrets

Operation ID: `account_get_secrets`
Operation page: `/api/operations/account_get_secrets`
Fetch the caller's opaque account_secrets blob.

Returns the wrapped account, KEM, signing, and recovery keys; the server
stores them only as ciphertext. A 404 here means the user has not yet
set up an account in this org's vault database - the client should call
`PUT /account` to do that.

Responses:
- `200` Account secrets blob (application/json: DataResponseAccountSecretsRecord)
- `401` Caller is not authenticated
- `404` Account not initialized in this org yet

### PUT /publishers/seren-passwords/account/secrets

Operation ID: `account_update_secrets`
Operation page: `/api/operations/account_update_secrets`
Rotate the caller's wrapped account secrets.

Requires an existing account and an Ed25519 update proof produced by the
current account signing key. First-time setup belongs on `PUT /account`;
this endpoint never creates identities or vault memberships.

Request body (required):
- `application/json`: AccountSecretsUpdateRequest

Responses:
- `200` Updated account secrets blob (application/json: DataResponseAccountSecretsRecord)
- `400` Malformed body or timestamp outside the freshness window
- `401` Invalid account-secrets update proof
- `403` Agents may not update account secrets
- `404` Account is not initialized in this org
- `409` Partial existing state, or a stale/replayed update proof
- `422` Request body failed validation

## agent

### PATCH /auth/agent

Operation ID: `agent_update`
Operation page: `/api/operations/agent_update`
Update an agent's profile (e.g. set a real email address).

When the email is changed, `email_verified` is set to `false` and a
verification email with a clickable link is sent. The user verifies
by clicking the link  no separate API call is needed.
A verified email is required before making Stripe deposits.

Request body (required):
- `application/json`: AgentUpdateRequest

Responses:
- `200` Agent updated
- `400` Invalid email
- `401` Unauthorized

### POST /auth/agent

Operation ID: `agent_register`
Operation page: `/api/operations/agent_register`
Register a new AI agent account.

This endpoint allows AI agents to self-register using the user's real email
address and receive an API key immediately. Registration:
- Requires a user-controlled email address up front
- Automatically creates a personal organization
- Returns an API key named "agent" for immediate use
- Sends an email verification link immediately after signup

**Important:** Save the `api_key` immediately - it is only shown once!

Request body (required):
- `application/json`: AgentRegisterRequest

Responses:
- `201` Agent registered successfully (application/json: DataResponse_AgentRegisterResponse)
- `400` Invalid request (validation error)
- `500` Internal server error

## Agent Analytics

### GET /organizations/{organization_id}/publishers/{publisher_id}/analytics/revenue

Operation ID: `get_revenue_metrics`
Operation page: `/api/operations/get_revenue_metrics`
Get revenue metrics with period-over-period comparison.

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `publisher_id` (path, required): string / uuid - Publisher ID
- `days` (query): integer / int32 - Number of days to analyze (default: 30)

Responses:
- `200` Revenue metrics (application/json: DataResponse_RevenueMetrics)
- `401` Unauthorized
- `404` Publisher not found

### GET /organizations/{organization_id}/publishers/{publisher_id}/analytics/revenue-by-day

Operation ID: `get_revenue_by_day`
Operation page: `/api/operations/get_revenue_by_day`
Get daily revenue breakdown.

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `publisher_id` (path, required): string / uuid - Publisher ID
- `days` (query): integer / int32 - Number of days to analyze (default: 30)

Responses:
- `200` Daily revenue breakdown (application/json: DataResponse_Vec_RevenueByDay)
- `401` Unauthorized
- `404` Publisher not found

### GET /organizations/{organization_id}/publishers/{publisher_id}/analytics/top-agents

Operation ID: `get_top_agents`
Operation page: `/api/operations/get_top_agents`
Get top agents by spending.

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `publisher_id` (path, required): string / uuid - Publisher ID
- `limit` (query): integer / int32 - Number of agents to return (default: 10)

Responses:
- `200` Top agents by spending (application/json: DataResponse_Vec_TopAgent)
- `401` Unauthorized
- `404` Publisher not found

## Agent Catalog

### GET /organizations/{organization_id}/catalog

Operation ID: `list_catalog_entries`
Operation page: `/api/operations/list_catalog_entries`
List catalog entries for an organization.

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID
- `namespace` (query): string - Filter by namespace
- `kind` (query): AgentCatalogEntryKind - Filter by entry kind
- `name` (query): string - Filter by entry name
- `tag` (query): string - Filter by mutable tag pointer
- `include_deprecated` (query): boolean - Include deprecated entries

Responses:
- `200` Catalog entries for the organization (application/json: DataResponse_AgentCatalogListResponse)
- `401` Unauthorized

### POST /organizations/{organization_id}/catalog

Operation ID: `create_catalog_entry`
Operation page: `/api/operations/create_catalog_entry`
Create a new catalog entry.

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID

Request body (required):
- `application/json`: AgentCatalogEntryCreateRequest

Responses:
- `201` Catalog entry created (application/json: DataResponse_AgentCatalogEntry)
- `400` Invalid request
- `401` Unauthorized
- `409` Entry with the same identity already exists

### DELETE /organizations/{organization_id}/catalog/{entry_id}

Operation ID: `delete_catalog_entry`
Operation page: `/api/operations/delete_catalog_entry`
Delete a catalog entry.

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID
- `entry_id` (path, required): string / uuid - Catalog entry ID

Responses:
- `204` Catalog entry deleted
- `401` Unauthorized
- `404` Catalog entry not found

### GET /organizations/{organization_id}/catalog/{entry_id}

Operation ID: `get_catalog_entry`
Operation page: `/api/operations/get_catalog_entry`
Fetch a single catalog entry by its UUID.

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID
- `entry_id` (path, required): string / uuid - Catalog entry ID

Responses:
- `200` Catalog entry (application/json: DataResponse_AgentCatalogEntry)
- `401` Unauthorized
- `404` Catalog entry not found

### PATCH /organizations/{organization_id}/catalog/{entry_id}

Operation ID: `update_catalog_entry`
Operation page: `/api/operations/update_catalog_entry`
Apply a partial update to a catalog entry. Identity (namespace/name/version)
is immutable; only mutable fields change.

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID
- `entry_id` (path, required): string / uuid - Catalog entry ID

Request body (required):
- `application/json`: AgentCatalogEntryUpdateRequest

Responses:
- `200` Catalog entry updated (application/json: DataResponse_AgentCatalogEntry)
- `400` Invalid request
- `401` Unauthorized
- `404` Catalog entry not found
- `409` Tag pointer collision

### GET /organizations/{organization_id}/catalog/{namespace}/{name}/by-tag/{tag}

Operation ID: `resolve_catalog_tag`
Operation page: `/api/operations/resolve_catalog_tag`
Resolve a mutable tag pointer to the concrete catalog entry it points at.
Tags like `stable` or `latest` are mutable; this endpoint returns whichever
version the tag currently names. Returns 404 when no entry within
`(namespace, name)` carries the tag.

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID
- `namespace` (path, required): string - Catalog namespace
- `name` (path, required): string - Catalog entry name
- `tag` (path, required): string - Mutable tag pointer to resolve

Responses:
- `200` Catalog entry the tag points at (application/json: DataResponse_AgentCatalogEntry)
- `401` Unauthorized
- `404` No entry carries the named tag

### POST /organizations/{organization_id}/catalog/{namespace}/{name}/promote

Operation ID: `promote_catalog_tag`
Operation page: `/api/operations/promote_catalog_tag`
Atomically promote a mutable tag pointer from one immutable version
to another within `(namespace, name)`. Distinct from a generic PATCH so
the action surfaces as a promotion in audit history rather than a
generic edit.

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID
- `namespace` (path, required): string - Catalog namespace
- `name` (path, required): string - Catalog entry name

Request body (required):
- `application/json`: AgentCatalogTagPromotionRequest

Responses:
- `200` Tag promoted; response is the post-promotion entry (application/json: DataResponse_AgentCatalogEntry)
- `400` Invalid request (from_version == to_version, malformed tokens)
- `401` Unauthorized
- `404` Destination version not found
- `409` from_version no longer holds the tag; refresh and retry

## Agent Tasks

### GET /organizations/{organization_id}/agents/tasks

Operation ID: `list_tasks`
Operation page: `/api/operations/list_tasks`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID
- `limit` (query): integer / int64
- `offset` (query): integer / int64

Responses:
- `200` Tasks retrieved (application/json: DataResponse_Vec_AgentTask)
- `403` Not authorized

### GET /organizations/{organization_id}/agents/tasks/{task_id}

Operation ID: `get_task`
Operation page: `/api/operations/get_task`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID
- `task_id` (path, required): string / uuid - Task ID

Responses:
- `200` Task retrieved (application/json: DataResponse_AgentTask)
- `404` Task not found

### POST /organizations/{organization_id}/agents/tasks/{task_id}/cancel

Operation ID: `cancel_task`
Operation page: `/api/operations/cancel_task`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID
- `task_id` (path, required): string / uuid - Task ID

Responses:
- `200` Task canceled (application/json: DataResponse_AgentTask)
- `400` Already terminal
- `404` Not found

### GET /organizations/{organization_id}/agents/tasks/{task_id}/events

Operation ID: `list_task_events`
Operation page: `/api/operations/list_task_events`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID
- `task_id` (path, required): string / uuid - Task ID

Responses:
- `200` Events retrieved (application/json: DataResponse_Vec_AgentTaskEvent)
- `404` Not found

### POST /organizations/{organization_id}/agents/tasks/{task_id}/resume

Operation ID: `submit_task_input`
Operation page: `/api/operations/submit_task_input`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID
- `task_id` (path, required): string / uuid - Task ID

Request body (required):
- `application/json`: SubmitTaskInputRequest

Responses:
- `202` Task input accepted (application/json: DataResponse_AgentTask)
- `400` Task is not awaiting input or cannot be resumed
- `403` Not authorized
- `404` Task not found

### GET /organizations/{organization_id}/agents/tasks/{task_id}/stream

Operation ID: `stream_task`
Operation page: `/api/operations/stream_task`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID
- `task_id` (path, required): string / uuid - Task ID

Responses:
- `200` SSE event stream

## agent-wallet

### GET /wallet/balance

Operation ID: `get_wallet_balance`
Operation page: `/api/operations/get_wallet_balance`
Get wallet balance (funded + promotional)

Responses:
- `200` Wallet balance retrieved (application/json: DataResponse_WalletBalanceResponse)
- `401` Unauthorized

### POST /wallet/bonus/payment-method

Operation ID: `claim_payment_method_bonus`
Operation page: `/api/operations/claim_payment_method_bonus`
Claim payment method bonus (if not already claimed)

Responses:
- `200` Payment method bonus claimed (application/json: DataResponse_BonusClaimResponse)
- `401` Unauthorized
- `409` Bonus already claimed

### POST /wallet/bonus/signup

Operation ID: `claim_signup_bonus`
Operation page: `/api/operations/claim_signup_bonus`
Claim signup bonus (if not already claimed)

Responses:
- `200` Signup bonus claimed (application/json: DataResponse_BonusClaimResponse)
- `401` Unauthorized
- `409` Bonus already claimed

### POST /wallet/daily/claim

Operation ID: `claim_daily`
Operation page: `/api/operations/claim_daily`
Claim daily free credits

Responses:
- `200` Daily credits claimed (application/json: DataResponse_DailyClaimResponse)
- `400` Not eligible for daily claim
- `401` Unauthorized

### GET /wallet/daily/eligibility

Operation ID: `check_daily_eligibility`
Operation page: `/api/operations/check_daily_eligibility`
Check if user can claim daily credits

Responses:
- `200` Eligibility checked (application/json: DataResponse_DailyClaimEligibilityResponse)
- `401` Unauthorized

### POST /wallet/deposit

Operation ID: `create_deposit`
Operation page: `/api/operations/create_deposit`
Deposit funds via Stripe

Request body (required):
- `application/json`: DepositRequest

Responses:
- `200` Deposit initiated (application/json: DataResponse_DepositResponse)
- `400` Invalid request
- `401` Unauthorized
- `403` Verified email required

### POST /wallet/deposit/crypto

Operation ID: `onchain_deposit`
Operation page: `/api/operations/onchain_deposit`
Deposit configured asset via on-chain payment flow

Allows agents to deposit the configured asset directly on-chain to their prepaid balance.
Follows the 402 payment protocol:
1. First request (no payment header) returns 402 with payment requirements
2. Second request (with payment header) settles on-chain and credits balance

Request body (required):
- `application/json`: OnchainDepositRequest

Responses:
- `200` Deposit successful (application/json: OnchainDepositResponse)
- `400` Invalid request
- `402` Payment required (application/json: PaymentRequiredResponseWithInfo)
- `404` Publisher not found
- `500` Internal server error

### POST /wallet/recover

Operation ID: `wallet_recover`
Operation page: `/api/operations/wallet_recover`
Recover an agent account using a recovery code.

This endpoint allows agents who have lost their API key to recover their account
using the recovery code they saved when setting up wallet recovery.

**What this does:**
- Verifies the recovery code
- Revokes all existing API keys (for security)
- Issues a new API key
- Rotates the recovery code (old code is invalidated)

**Important:** Save both the new API key AND the new recovery code - they're only shown once!

Request body (required):
- `application/json`: WalletRecoverRequest

Responses:
- `200` Account recovered successfully (application/json: DataResponse_WalletRecoverResponse)
- `400` Invalid request
- `401` Invalid recovery code
- `500` Internal server error

### POST /wallet/recovery

Operation ID: `set_recovery`
Operation page: `/api/operations/set_recovery`
Set up account recovery (recovery code and/or email).

- If you don't have a `recovery_code` yet, this endpoint generates one and returns it **once**.
- If you already have a `recovery_code`, it will not be shown again.
- You can optionally set/update a recovery `email` for human account recovery.

Use the recovery code with `POST /wallet/recover` to rotate access after losing your API key.

Request body (required):
- `application/json`: SetRecoveryRequest

Responses:
- `200` Recovery set up (application/json: DataResponse_RecoveryResponse)
- `401` Unauthorized

### GET /wallet/referral

Operation ID: `get_referral_info`
Operation page: `/api/operations/get_referral_info`
Get user's referral info and code

Responses:
- `200` Referral info retrieved (application/json: DataResponse_ReferralInfoResponse)
- `401` Unauthorized

### POST /wallet/referral/apply

Operation ID: `apply_referral_code`
Operation page: `/api/operations/apply_referral_code`
Apply a referral code to the current user

Request body (required):
- `application/json`: ApplyReferralRequest

Responses:
- `200` Referral code applied
- `400` Invalid referral code
- `401` Unauthorized
- `409` Already has a referrer

### GET /wallet/settlements/{receipt_id}

Operation ID: `get_settlement_receipt`
Operation page: `/api/operations/get_settlement_receipt`
Get the settlement state for a priced publisher operation.

Parameters:
- `receipt_id` (path, required): string / uuid - Settlement receipt ID

Responses:
- `200` Settlement receipt retrieved (application/json: DataResponse_SettlementReceiptResponse)
- `401` Unauthorized
- `404` Settlement receipt not found

### GET /wallet/transactions

Operation ID: `get_transactions`
Operation page: `/api/operations/get_transactions`
Get transaction history including credits and debits

Parameters:
- `limit` (query): integer / int64 - Maximum number of transactions to return (default 50, max 100)
- `offset` (query): integer / int64 - Offset for pagination
- `cursor` (query): string | null - Opaque cursor from the previous page. When present, offset is ignored.
- `include_usage` (query): boolean - Include raw usage/micropayment debits (default false). When false, usage debits are aggregated by day and publisher.
- `exact_total` (query): boolean - Compute an exact total row count. Defaults to false because exact counts can require scanning large wallet histories.
- `start_date` (query): string | null - Filter: only transactions on or after this date (YYYY-MM-DD, interpreted as UTC midnight)
- `end_date` (query): string | null - Filter: only transactions strictly before this date (YYYY-MM-DD, interpreted as UTC midnight). To include a full day, set end_date to the day *after* the last day you want.

Responses:
- `200` Transaction history retrieved (application/json: DataResponse_WalletTransactionHistoryResponse)
- `401` Unauthorized

### GET /wallet/transactions/export

Operation ID: `export_transactions`
Operation page: `/api/operations/export_transactions`
Export transactions as a CSV file for a date range

Parameters:
- `start_date` (query): string | null - Start date (YYYY-MM-DD, inclusive, UTC midnight)
- `end_date` (query): string | null - End date (YYYY-MM-DD, exclusive, UTC midnight)

Responses:
- `200` CSV file download (text/csv: unspecified)
- `401` Unauthorized

### GET /wallet/transactions/summary

Operation ID: `get_transaction_summary`
Operation page: `/api/operations/get_transaction_summary`
Get summary statistics for transactions in a date range

Parameters:
- `start_date` (query): string | null - Start date (YYYY-MM-DD, inclusive, UTC midnight)
- `end_date` (query): string | null - End date (YYYY-MM-DD, exclusive, UTC midnight)

Responses:
- `200` Transaction summary retrieved (application/json: DataResponse_TransactionSummaryResponse)
- `401` Unauthorized

### GET /wallet/transfers

Operation ID: `list_wallet_transfers`
Operation page: `/api/operations/list_wallet_transfers`
List SerenBucks wallet transfers.

Parameters:
- `direction` (query): null | WalletTransferDirection
- `status` (query): string | null
- `cursor` (query): string | null
- `limit` (query): integer | null / int64

Responses:
- `200` Transfers retrieved (application/json: DataResponse_WalletTransferListResponse)
- `401` Unauthorized

### POST /wallet/transfers

Operation ID: `execute_wallet_transfer`
Operation page: `/api/operations/execute_wallet_transfer`
Execute a SerenBucks wallet transfer.

Parameters:
- `Idempotency-Key` (header, required): string - Unique key for safely retrying transfer execution

Request body (required):
- `application/json`: WalletTransferRequest

Responses:
- `200` Transfer executed (application/json: DataResponse_WalletTransferExecuteResponse)
- `400` Invalid request
- `401` Unauthorized
- `409` Idempotency conflict

### POST /wallet/transfers/invite/claim

Operation ID: `claim_wallet_transfer`
Operation page: `/api/operations/claim_wallet_transfer`
Claim a pending SerenBucks transfer invite.

Request body (required):
- `application/json`: WalletTransferClaimRequest

Responses:
- `200` Pending transfer claimed (application/json: DataResponse_WalletTransferClaimResponse)
- `400` Invalid request
- `401` Unauthorized
- `403` Verified email required or email mismatch
- `404` Invite not found

### POST /wallet/transfers/pending/{pending_transfer_id}/recall

Operation ID: `recall_wallet_transfer`
Operation page: `/api/operations/recall_wallet_transfer`
Recall a pending SerenBucks transfer.

Parameters:
- `pending_transfer_id` (path, required): string / uuid - Pending transfer ID

Responses:
- `200` Pending transfer recalled (application/json: DataResponse_WalletTransferRecallResponse)
- `401` Unauthorized
- `403` Forbidden
- `404` Pending transfer not found

### POST /wallet/transfers/preview

Operation ID: `preview_wallet_transfer`
Operation page: `/api/operations/preview_wallet_transfer`
Preview a SerenBucks wallet transfer.

Request body (required):
- `application/json`: WalletTransferRequest

Responses:
- `200` Transfer preview retrieved (application/json: DataResponse_WalletTransferPreviewResponse)
- `400` Invalid request
- `401` Unauthorized

## Approvals

### GET /publishers/seren-passwords/approvals

Operation ID: `approval_list_pending`
Operation page: `/api/operations/approval_list_pending`
List pending approval requests visible to the caller.

Responses:
- `200` Pending approvals (application/json: DataResponseApprovalRecordList)
- `401` Caller is not authenticated
- `404` Caller has no active account identity

### POST /publishers/seren-passwords/approvals

Operation ID: `approval_create`
Operation page: `/api/operations/approval_create`
Open an approval request for an item or vault target.

Request body (required):
- `application/json`: CreateApprovalRequest

Responses:
- `200` Created approval (application/json: DataResponseApprovalRecord)
- `401` Caller is not authenticated
- `403` Caller does not have visibility into the target vault
- `404` Target item or vault not found
- `422` Request body failed validation

### GET /publishers/seren-passwords/approvals/{approval_id}

Operation ID: `approval_get`
Operation page: `/api/operations/approval_get`
Fetch one approval by id. The one-shot wrapped key is scrubbed unless the
caller is the requester.

Parameters:
- `approval_id` (path, required): string / uuid - Approval id

Responses:
- `200` Approval record (application/json: DataResponseApprovalRecord)
- `401` Caller is not authenticated
- `404` Approval not found

### POST /publishers/seren-passwords/approvals/{approval_id}/approve

Operation ID: `approval_approve`
Operation page: `/api/operations/approval_approve`
Approve a pending approval request and supply the one-shot wrapped key.

Parameters:
- `approval_id` (path, required): string / uuid - Approval id

Request body (required):
- `application/json`: ApprovalDecisionRequest

Responses:
- `200` Approved (application/json: DataResponseApprovalRecord)
- `401` Caller is not authenticated
- `403` Caller is not an admin of the target vault
- `404` Approval or target not found
- `409` Approval is no longer pending
- `422` Request body failed validation

### GET /publishers/seren-passwords/approvals/{approval_id}/approve-context

Operation ID: `approval_approve_context`
Operation page: `/api/operations/approval_approve_context`

Parameters:
- `approval_id` (path, required): string / uuid - Approval id

Responses:
- `200` Material needed to construct the one_shot_wrapped_key (application/json: DataResponseApproveContext)
- `401` Caller is not authenticated
- `403` Caller is not an admin of the target vault
- `404` Approval, target, or requester identity not found

### POST /publishers/seren-passwords/approvals/{approval_id}/deny

Operation ID: `approval_deny`
Operation page: `/api/operations/approval_deny`
Deny a pending approval request.

Parameters:
- `approval_id` (path, required): string / uuid - Approval id

Responses:
- `200` Denied (application/json: DataResponseApprovalRecord)
- `401` Caller is not authenticated
- `403` Caller is not an admin of the target vault
- `404` Approval or target not found
- `409` Approval is no longer pending

### GET /publishers/seren-passwords/approvals/{approval_id}/wait

Operation ID: `approval_wait`
Operation page: `/api/operations/approval_wait`
Stream approval state changes over SSE until the request decides or the
server-side wait window elapses. Only the requester may wait.

Parameters:
- `approval_id` (path, required): string / uuid - Approval id

Responses:
- `200` Server-sent events stream (text/event-stream: unspecified)
- `401` Caller is not authenticated
- `403` Only the requester may wait on this approval
- `404` Approval not found

## attachments

### DELETE /publishers/seren-notes/attachments/{attachment_id}

Operation ID: `delete_attachment`
Operation page: `/api/operations/delete_attachment`
Delete an attachment

Parameters:
- `attachment_id` (path, required): string / uuid - Attachment ID

Responses:
- `204` Attachment deleted
- `401` Unauthorized
- `404` Attachment not found

### GET /publishers/seren-notes/attachments/{attachment_id}

Operation ID: `get_attachment`
Operation page: `/api/operations/get_attachment`
Get attachment metadata

Parameters:
- `attachment_id` (path, required): string / uuid - Attachment ID

Responses:
- `200` Attachment metadata (application/json: DataResponse_Attachment)
- `401` Unauthorized
- `404` Attachment not found

### PATCH /publishers/seren-notes/attachments/{attachment_id}

Operation ID: `update_attachment`
Operation page: `/api/operations/update_attachment`
Update attachment metadata

Parameters:
- `attachment_id` (path, required): string / uuid - Attachment ID

Request body (required):
- `application/json`: UpdateAttachmentRequest

Responses:
- `200` Attachment updated (application/json: DataResponse_Attachment)
- `401` Unauthorized
- `404` Attachment not found

### GET /publishers/seren-notes/attachments/{attachment_id}/data

Operation ID: `download_attachment`
Operation page: `/api/operations/download_attachment`
Download attachment data

Parameters:
- `attachment_id` (path, required): string / uuid - Attachment ID

Responses:
- `200` Attachment binary data
- `304` Not modified (ETag match)
- `401` Unauthorized
- `404` Attachment not found

### GET /publishers/seren-notes/attachments/{attachment_id}/thumbnail

Operation ID: `download_thumbnail`
Operation page: `/api/operations/download_thumbnail`
Download attachment thumbnail (generated on-demand)

Parameters:
- `attachment_id` (path, required): string / uuid - Attachment ID
- `width` (query): integer | null / int32 - Maximum width in pixels (default: 200, max: 800)
- `height` (query): integer | null / int32 - Maximum height in pixels (default: 200, max: 800)

Responses:
- `200` Thumbnail image (JPEG)
- `304` Not modified (ETag match)
- `400` Not an image attachment
- `401` Unauthorized
- `404` Attachment not found

### GET /publishers/seren-notes/notes/{note_id}/attachments

Operation ID: `list_attachments`
Operation page: `/api/operations/list_attachments`
List attachments for a note

Parameters:
- `note_id` (path, required): string / uuid - Note ID

Responses:
- `200` List of attachments (application/json: DataResponse_Vec_Attachment)
- `401` Unauthorized

### POST /publishers/seren-notes/notes/{note_id}/attachments

Operation ID: `upload_attachment`
Operation page: `/api/operations/upload_attachment`
Upload an attachment (binary body with headers)

Parameters:
- `note_id` (path, required): string / uuid - Note ID
- `X-Filename` (header, required): string - Original filename
- `Content-Type` (header, required): string - MIME type
- `X-Alt-Text` (header): string | null - Alt text for accessibility

Request body (required):
- `application/octet-stream`: array<integer / int32>

Responses:
- `201` Attachment created (application/json: DataResponse_Attachment)
- `400` Invalid request or file too large
- `401` Unauthorized
- `404` Note not found

### POST /publishers/seren-notes/notes/{note_id}/attachments/import

Operation ID: `import_attachment_from_url`
Operation page: `/api/operations/import_attachment_from_url`
Import an image from an external URL and store it as an attachment

Parameters:
- `note_id` (path, required): string / uuid - Note ID

Request body (required):
- `application/json`: ImportAttachmentFromUrlRequest

Responses:
- `201` Attachment created (application/json: DataResponse_Attachment)
- `400` Invalid request or URL not allowed
- `401` Unauthorized
- `404` Note not found

## Attachments

### GET /publishers/seren-passwords/vaults/{vault_id}/items/{item_id}/attachments

Operation ID: `attachment_list`
Operation page: `/api/operations/attachment_list`
List attachment metadata for an item (without blob bytes).

Parameters:
- `vault_id` (path, required): string / uuid - Vault id
- `item_id` (path, required): string / uuid - Item id

Responses:
- `200` Attachment list (application/json: DataResponseAttachmentViewList)
- `401` Caller is not authenticated
- `403` Approval required; see error.approval_request_id
- `404` Item or vault not found, or caller has no active account identity
- `429` Attachment read rate limit exceeded

### POST /publishers/seren-passwords/vaults/{vault_id}/items/{item_id}/attachments

Operation ID: `attachment_create`
Operation page: `/api/operations/attachment_create`
Upload an encrypted attachment blob plus its wrapped content key.

Requires write membership on the vault and is blocked while the vault is
in `rotating` state.

Parameters:
- `vault_id` (path, required): string / uuid - Vault id
- `item_id` (path, required): string / uuid - Item id

Request body (required):
- `application/json`: CreateAttachmentRequest

Responses:
- `200` Created attachment metadata (application/json: DataResponseAttachmentView)
- `400` Empty or oversized blob
- `401` Caller is not authenticated
- `403` Caller does not have write access
- `404` Vault or item not found
- `422` Request body failed validation
- `423` Vault is locked due to ongoing key rotation

### DELETE /publishers/seren-passwords/vaults/{vault_id}/items/{item_id}/attachments/{attachment_id}

Operation ID: `attachment_delete`
Operation page: `/api/operations/attachment_delete`
Delete an attachment. Requires write membership and is blocked while the
vault is in `rotating` state.

Parameters:
- `vault_id` (path, required): string / uuid - Vault id
- `item_id` (path, required): string / uuid - Item id
- `attachment_id` (path, required): string / uuid - Attachment id

Responses:
- `200` Deleted (application/json: DataResponseJsonValue)
- `401` Caller is not authenticated
- `403` Caller does not have write access
- `404` Attachment, item, or vault not found
- `423` Vault is locked due to ongoing key rotation

### GET /publishers/seren-passwords/vaults/{vault_id}/items/{item_id}/attachments/{attachment_id}

Operation ID: `attachment_get`
Operation page: `/api/operations/attachment_get`
Fetch one attachment with its encrypted blob bytes.

Parameters:
- `vault_id` (path, required): string / uuid - Vault id
- `item_id` (path, required): string / uuid - Item id
- `attachment_id` (path, required): string / uuid - Attachment id

Responses:
- `200` Attachment with blob (application/json: DataResponseAttachmentWithBlobView)
- `401` Caller is not authenticated
- `403` Approval required; see error.approval_request_id
- `404` Attachment, item, or vault not found
- `429` Attachment read rate limit exceeded

## Audit

### GET /publishers/seren-passwords/audit/events

Operation ID: `audit_event_list`
Operation page: `/api/operations/audit_event_list`
List audit log entries visible to the caller, filtered by actor, action,
target, and time window.

Parameters:
- `actor_identity_id` (query): string | null / uuid
- `action` (query): string | null
- `target_kind` (query): string | null
- `target_id` (query): string | null / uuid
- `from` (query): string | null / date-time
- `to` (query): string | null / date-time
- `limit` (query): integer | null / int64
- `offset` (query): integer | null / int64

Responses:
- `200` Audit log entries (application/json: DataResponseAuditLogEntryList)
- `401` Caller is not authenticated
- `404` Caller has no active account identity

### GET /publishers/seren-passwords/audit/verify

Operation ID: `audit_chain_verify`
Operation page: `/api/operations/audit_chain_verify`
Verify the audit log hash chain for this organization database.

The result proves current chain consistency. It does not provide external
anchoring or per-row non-repudiation.

Responses:
- `200` Audit hash-chain verification result (application/json: DataResponseAuditChainVerifyResult)
- `401` Caller is not authenticated
- `403` Only user identities may verify audit chain

## Audit Logs

### GET /organizations/{organization_id}/audit-logs

Operation ID: `list_audit_logs`
Operation page: `/api/operations/list_audit_logs`
List audit logs for an organization

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `actor_id` (query): string | null / uuid - Filter by actor ID
- `action` (query): string | null - Filter by action (e.g., "project.create")
- `resource_type` (query): string | null - Filter by resource type (e.g., "project", "branch")
- `resource_id` (query): string | null / uuid - Filter by resource ID
- `status` (query): string | null - Filter by status
- `action_category` (query): string | null - Filter by action category
- `start_date` (query): string | null - Filter by start date (ISO 8601)
- `end_date` (query): string | null - Filter by end date (ISO 8601)
- `limit` (query): integer / int64 - Maximum number of results (default 50, max 100)
- `offset` (query): integer / int64 - Offset for pagination

Responses:
- `200` Audit logs retrieved successfully (application/json: DataResponse_AuditLogList)
- `401` Unauthorized
- `403` Forbidden - not a member of this organization
- `404` Organization not found

### GET /organizations/{organization_id}/audit-logs/{log_id}

Operation ID: `get_audit_log`
Operation page: `/api/operations/get_audit_log`
Get a specific audit log entry

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `log_id` (path, required): string / uuid - Audit log ID

Responses:
- `200` Audit log retrieved successfully (application/json: DataResponse_AuditLog)
- `401` Unauthorized
- `403` Forbidden - not a member of this organization
- `404` Audit log not found

## Auth

### POST /auth/accept-invite

Operation ID: `accept_organization_invite`
Operation page: `/api/operations/accept_organization_invite`
Accept an organization invite for the authenticated user.

Request body (required):
- `application/json`: AcceptOrganizationInviteRequest

Responses:
- `200` Organization invite accepted (application/json: DataResponse_AcceptOrganizationInviteResult)
- `400` Invalid or expired invite
- `401` Unauthorized
- `404` Invite not found

### GET /auth/account-security

Operation ID: `get_account_security`
Operation page: `/api/operations/get_account_security`
Return account-level auth state (password presence and linked social providers).

Responses:
- `200` Account security state (application/json: DataResponse_AccountSecurity)
- `401` Unauthorized
- `404` User not found

### POST /auth/change-password

Operation ID: `change_password`
Operation page: `/api/operations/change_password`
Change the authenticated user's password and revoke active refresh sessions

Request body (required):
- `application/json`: UpdatePasswordRequest

Responses:
- `200` Password updated successfully (application/json: DataResponse_PasswordUpdated)
- `400` Invalid current password or weak new password
- `401` Unauthorized
- `403` Password login is not enabled for this account
- `404` User not found

### POST /auth/forgot-password

Operation ID: `forgot_password`
Operation page: `/api/operations/forgot_password`
Request a password reset email

Request body (required):
- `application/json`: ForgotPasswordRequest

Responses:
- `200` Password reset email sent if account exists (application/json: DataResponse_PasswordResetSent)
- `400` Invalid request

### POST /auth/login

Operation ID: `login`
Operation page: `/api/operations/login`
Login with email and password.

Request body (required):
- `application/json`: LoginRequest

Responses:
- `200` Login successful (application/json: DataResponse_LoginResult)
- `400` Invalid request
- `401` Invalid credentials
- `403` Email verification required

### POST /auth/logout

Operation ID: `logout`
Operation page: `/api/operations/logout`
Revoke all sessions for current user.

Responses:
- `200` Sessions revoked (application/json: DataResponse_LogoutResult)
- `401` Unauthorized

### GET /auth/me

Operation ID: `get_current_user`
Operation page: `/api/operations/get_current_user`
Get current authenticated user information with default organization

Responses:
- `200` Current user information with default organization (application/json: DataResponse_UserMe)
- `401` Unauthorized

### POST /auth/refresh

Operation ID: `refresh_token`
Operation page: `/api/operations/refresh_token`
Exchange refresh token for new access token and refresh token (rotation).

Request body (required):
- `application/json`: RefreshTokenRequest

Responses:
- `200` Tokens rotated (application/json: DataResponse_TokenRefresh)
- `401` Missing, invalid, expired, or reused refresh token

### POST /auth/resend-verification

Operation ID: `resend_verification_email`
Operation page: `/api/operations/resend_verification_email`
Resend email verification link

Request body (required):
- `application/json`: ResendVerificationRequest

Responses:
- `200` Verification email sent if account exists (application/json: DataResponse_VerificationSent)
- `400` Invalid request

### POST /auth/reset-password

Operation ID: `reset_password`
Operation page: `/api/operations/reset_password`
Reset password using a valid token

Request body (required):
- `application/json`: ResetPasswordRequest

Responses:
- `200` Password reset successfully (application/json: DataResponse_PasswordReset)
- `400` Invalid or expired token
- `404` Token not found

### POST /auth/signup

Operation ID: `signup`
Operation page: `/api/operations/signup`
Register a new user with email and password

Request body (required):
- `application/json`: SignupRequest

Responses:
- `201` Account created (application/json: DataResponse_SignupResult)
- `400` Invalid request or weak password
- `409` Email already registered

### POST /auth/verify-email

Operation ID: `verify_email`
Operation page: `/api/operations/verify_email`
Verify email address using a token from the verification email link.
Called by an application frontend when the user clicks the link; agents
do not need to call this directly.
On success, automatically logs the user in and returns tokens

Request body (required):
- `application/json`: VerifyEmailRequest

Responses:
- `200` Email verified and user logged in (application/json: DataResponse_LoginResult)
- `400` Invalid or expired token

### GET /organizations/{organization_id}/api-keys

Operation ID: `list_org_api_keys`
Operation page: `/api/operations/list_org_api_keys`
List API keys for a specific organization

Requires a signed-in user access token. API keys cannot manage API keys.

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization

Responses:
- `200` List of API keys (application/json: DataResponse_Vec_ApiKeyInfo)
- `401` Unauthorized
- `403` A signed-in user session is required
- `404` Organization not found

### POST /organizations/{organization_id}/api-keys

Operation ID: `create_org_api_key`
Operation page: `/api/operations/create_org_api_key`
Create a new API key for a specific organization

Requires a signed-in user access token. API keys cannot manage API keys.

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization

Request body (required):
- `application/json`: CreateApiKeyRequest

Responses:
- `201` API key created (application/json: DataResponse_ApiKeyCreated)
- `401` Unauthorized
- `403` A signed-in user session is required
- `404` Organization not found

### DELETE /organizations/{organization_id}/api-keys/{key_id}

Operation ID: `revoke_org_api_key`
Operation page: `/api/operations/revoke_org_api_key`
Revoke an organization API key

Requires a signed-in user access token. API keys cannot manage API keys.

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `key_id` (path, required): string / uuid - API key ID

Responses:
- `200` API key revoked
- `401` Unauthorized
- `403` A signed-in user session is required
- `404` API key not found

### PATCH /organizations/{organization_id}/api-keys/{key_id}/scopes

Operation ID: `update_org_api_key_scopes`
Operation page: `/api/operations/update_org_api_key_scopes`
Replace the least-privilege scopes on an organization API key.

Requires a signed-in user access token. A user may update only their own
active user API keys; API keys cannot update their own privileges.

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID
- `key_id` (path, required): string / uuid - API key ID

Request body (required):
- `application/json`: UpdateApiKeyScopesRequest

Responses:
- `200` API key scopes replaced (application/json: DataResponse_ApiKeyInfo)
- `400` Invalid scope set
- `401` Unauthorized
- `403` A signed-in user session is required
- `404` API key not found

### GET /organizations/default/api-keys

Operation ID: `list_default_org_api_keys`
Operation page: `/api/operations/list_default_org_api_keys`
List API keys for the user's default organization

Requires a signed-in user access token. API keys cannot manage API keys.

Responses:
- `200` List of API keys (application/json: DataResponse_Vec_ApiKeyInfo)
- `400` User has no organization
- `401` Unauthorized
- `403` A signed-in user session is required

### POST /organizations/default/api-keys

Operation ID: `create_default_org_api_key`
Operation page: `/api/operations/create_default_org_api_key`
Create a new API key for the user's default organization

This convenience endpoint resolves "default" to the user's first organization. It requires a signed-in user access token; API keys cannot manage API keys.

Request body (required):
- `application/json`: CreateApiKeyRequest

Responses:
- `201` API key created (application/json: DataResponse_ApiKeyCreated)
- `400` User has no organization
- `401` Unauthorized
- `403` A signed-in user session is required

### DELETE /organizations/default/api-keys/{key_id}

Operation ID: `revoke_default_org_api_key`
Operation page: `/api/operations/revoke_default_org_api_key`
Revoke an API key from the user's default organization

Requires a signed-in user access token. API keys cannot manage API keys.

Parameters:
- `key_id` (path, required): string / uuid - API key ID

Responses:
- `200` API key revoked
- `400` User has no organization
- `401` Unauthorized
- `403` A signed-in user session is required
- `404` API key not found

### PATCH /organizations/default/api-keys/{key_id}/scopes

Operation ID: `update_default_org_api_key_scopes`
Operation page: `/api/operations/update_default_org_api_key_scopes`
Replace scopes on an API key in the user's default organization.

Requires a signed-in user access token. API keys cannot update their own privileges.

Parameters:
- `key_id` (path, required): string / uuid - API key ID

Request body (required):
- `application/json`: UpdateApiKeyScopesRequest

Responses:
- `200` API key scopes replaced (application/json: DataResponse_ApiKeyInfo)
- `400` Invalid scope set
- `401` Unauthorized
- `403` A signed-in user session is required
- `404` API key not found

## billing

### GET /billing/health

Operation ID: `get_billing_health`
Operation page: `/api/operations/get_billing_health`
High-level billing and metering health summary for Seren Core

Responses:
- `200` Billing health retrieved successfully (application/json: DataResponse_BillingHealth)
- `500` Internal server error

### GET /billing/invoices/{id}

Operation ID: `get_invoice`
Operation page: `/api/operations/get_invoice`
Get invoice details with line items

Parameters:
- `id` (path, required): string / uuid - Invoice ID

Responses:
- `200` Invoice retrieved successfully (application/json: DataResponse_Invoice)
- `404` Invoice not found
- `500` Internal server error

### POST /billing/invoices/{id}/issue

Operation ID: `issue_invoice`
Operation page: `/api/operations/issue_invoice`
Issue a draft invoice

Parameters:
- `id` (path, required): string / uuid - Invoice ID

Responses:
- `200` Invoice issued successfully
- `404` Invoice not found
- `500` Internal server error

### POST /billing/invoices/generate

Operation ID: `generate_invoices`
Operation page: `/api/operations/generate_invoices`
Generate monthly invoices for all organizations

Request body (required):
- `application/json`: GenerateInvoicesRequest

Responses:
- `200` Invoices generated successfully (application/json: DataResponse_InvoicesGenerated)
- `400` Invalid request
- `500` Internal server error

### GET /billing/usage/{organization_id}

Operation ID: `get_usage_summary`
Operation page: `/api/operations/get_usage_summary`
Get usage summary for an organization

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID
- `start_date` (query): string | null
- `end_date` (query): string | null

Responses:
- `200` Usage summary retrieved (application/json: DataResponse_Vec_UsageSummary)
- `404` Organization not found
- `500` Internal server error

### GET /organizations/{organization_id}/billing/endpoints/{endpoint_id}/events

Operation ID: `get_endpoint_billing_events`
Operation page: `/api/operations/get_endpoint_billing_events`
Debug endpoint: show recent usage_events and compute_usage_events for an endpoint

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `endpoint_id` (path, required): string / uuid - Endpoint ID

Responses:
- `200` Billing events retrieved successfully (application/json: DataResponse_EndpointBillingEvents)
- `404` Endpoint not found for organization
- `500` Internal server error

### GET /organizations/{organization_id}/consumption

Operation ID: `get_organization_consumption`
Operation page: `/api/operations/get_organization_consumption`
Aggregated organization-level consumption over a billing window.

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `start_date` (query): string | null - Optional ISO-8601 start date (YYYY-MM-DD), defaults to first day of current month.
- `end_date` (query): string | null - Optional ISO-8601 end date (YYYY-MM-DD), defaults to today (UTC).

Responses:
- `200` Organization consumption retrieved (application/json: DataResponse_OrganizationConsumption)
- `401` Unauthorized
- `403` User is not a member of the organization
- `500` Internal server error

## Connector Webhooks

### GET /webhooks/{route_id}

Operation ID: `get_connector_webhook`
Operation page: `/api/operations/get_connector_webhook`
Supports provider verification callbacks that use GET.

Parameters:
- `route_id` (path, required): string - Opaque connector webhook route id

Responses:
- `200` Provider-specific webhook verification response
- `202` Webhook verification accepted
- `400` Invalid route id
- `404` Unknown, disabled, or stale route
- `502` Connector gateway rejected or failed the callback
- `503` Connector route temporarily unavailable

### POST /webhooks/{route_id}

Operation ID: `post_connector_webhook`
Operation page: `/api/operations/post_connector_webhook`
Accepts provider webhook callbacks for managed agent channel connectors.

This route is intentionally public because providers call it directly. The
route id maps to server-side connector routing metadata; provider-specific
signature verification happens inside the selected connector plugin.

Parameters:
- `route_id` (path, required): string - Opaque connector webhook route id

Responses:
- `200` Provider-specific webhook response
- `202` Webhook event accepted
- `400` Invalid route id
- `404` Unknown, disabled, or stale route
- `502` Connector gateway rejected or failed the callback
- `503` Connector route temporarily unavailable

## Databases

### GET /databases

Operation ID: `list_all_databases`
Operation page: `/api/operations/list_all_databases`
List all databases across all projects for the authenticated user

Returns all databases the user has access to, with project and branch context included.
This provides a single view of all databases without needing to query each project/branch separately.

Responses:
- `200` List of all databases with context (application/json: DataResponse_Vec_DatabaseWithContext)
- `401` Unauthorized

## Delegations

### POST /publishers/seren-passwords/delegations

Operation ID: `delegation_request_create`
Operation page: `/api/operations/delegation_request_create`

Request body (required):
- `application/json`: CreateDelegationRequest

Responses:
- `200` Created delegation request and one-time consent capability (application/json: DataResponseDelegationRequestCreated)
- `400` Invalid public key or display name
- `401` Caller is not authenticated
- `403` Only user callers may create delegation requests
- `422` Request body failed validation
- `503` Consent capability signing is not configured

### GET /publishers/seren-passwords/delegations/{request_id}

Operation ID: `delegation_request_get`
Operation page: `/api/operations/delegation_request_get`

Parameters:
- `request_id` (path, required): string / uuid - Delegation request id

Responses:
- `200` Delegation request (application/json: DataResponseDelegationRequestRecord)
- `401` Caller is not authenticated
- `403` Only user callers may read delegation requests
- `404` Delegation request not found

### POST /publishers/seren-passwords/delegations/{request_id}/approve

Operation ID: `delegation_request_approve`
Operation page: `/api/operations/delegation_request_approve`

Parameters:
- `request_id` (path, required): string / uuid - Delegation request id

Request body (required):
- `application/json`: ApproveDelegationRequest

Responses:
- `200` Approved delegation request (application/json: DataResponseDelegationRequestRecord)
- `400` Invalid approval request
- `401` Caller is not authenticated
- `403` Caller is not authorized to approve
- `404` Delegation request not found
- `422` Request body failed validation

### POST /publishers/seren-passwords/delegations/{request_id}/deny

Operation ID: `delegation_request_deny`
Operation page: `/api/operations/delegation_request_deny`

Parameters:
- `request_id` (path, required): string / uuid - Delegation request id

Responses:
- `200` Denied delegation request (application/json: DataResponseDelegationRequestRecord)
- `401` Caller is not authenticated
- `403` Only user callers may deny delegation requests
- `404` Delegation request not found

### POST /publishers/seren-passwords/delegations/approve

Operation ID: `delegation_consent_approve`
Operation page: `/api/operations/delegation_consent_approve`

Request body (required):
- `application/json`: ApproveDelegationConsentRequest

Responses:
- `200` Approved cross-user or cross-organization delegation (application/json: DataResponseDelegationRequestRecord)
- `400` Malformed grants, unsupported cross-organization admin access, or invalid signatures
- `401` Human user authentication required
- `403` Caller is not an admin of every selected vault
- `404` Consent capability is invalid
- `409` Consent retry does not match the claimed approval
- `410` Consent capability is expired or already used
- `422` Request body failed validation
- `423` A selected vault is rotating

### POST /publishers/seren-passwords/delegations/consent

Operation ID: `delegation_consent_read`
Operation page: `/api/operations/delegation_consent_read`

Request body (required):
- `application/json`: DelegationConsentCapabilityRequest

Responses:
- `200` Minimum public metadata for a valid pending consent capability (application/json: DataResponseDelegationConsentView)
- `401` Human user authentication required
- `404` Consent capability is invalid
- `410` Consent capability is expired or already used
- `422` Request body failed validation

### POST /publishers/seren-passwords/delegations/deny

Operation ID: `delegation_consent_deny`
Operation page: `/api/operations/delegation_consent_deny`

Request body (required):
- `application/json`: DelegationConsentCapabilityRequest

Responses:
- `200` Denied delegation request (application/json: DataResponseDelegationRequestRecord)
- `401` Human user authentication required
- `404` Consent capability is invalid
- `410` Consent capability is expired, claimed, or already used
- `422` Request body failed validation

## Eval

### GET /eval/community-prior

Operation ID: `get_community_prior`
Operation page: `/api/operations/get_community_prior`
Get an aggregate community routing prior for a task/model pair.

Parameters:
- `task_type` (query, required): TaskType
- `model_id` (query, required): string

Responses:
- `200` Community routing prior (application/json: DataResponse_CommunityPriorResponse)
- `400` Invalid query parameters
- `401` Unauthorized

### GET /eval/matrix

Operation ID: `get_matrix`
Operation page: `/api/operations/get_matrix`
Get the global eval routing matrix.

Responses:
- `200` Eval matrix (application/json: DataResponse_EvalMatrixResponse)
- `401` Unauthorized

### POST /eval/signals

Operation ID: `post_signals`
Operation page: `/api/operations/post_signals`
Ingest eval signals from Seren Desktop clients.

Request body (required):
- `application/json`: EvalSignalRequest

Responses:
- `201` Signals accepted (application/json: DataResponse_EvalSignalResponse)
- `400` Invalid request
- `401` Unauthorized

## federation

### GET /federation

Operation ID: `list_resources`
Operation page: `/api/operations/list_resources`
List federated resources with optional filtering.
Used for cross-publisher resource discovery.

Parameters:
- `publisher_slug` (query): string | null - Filter by publisher slug
- `resource_type` (query): string | null - Filter by resource type (e.g., "bounty", "dataset")
- `status` (query): string | null - Filter by status (default: "active")
- `limit` (query): integer / int64 - Maximum number of results (default: 50, max: 100)
- `offset` (query): integer / int64 - Offset for pagination

Responses:
- `200` Resources retrieved successfully (application/json: DataResponse_Vec_FederatedResourceWithPublisherResponse)
- `400` Invalid query parameters
- `500` Internal server error

### POST /federation

Operation ID: `upsert_resource`
Operation page: `/api/operations/upsert_resource`
Upsert a federated resource for a publisher.
Publishers use this to register/update their resources for cross-publisher discovery.

Request body (required):
- `application/json`: UpsertFederatedResourceRequest

Responses:
- `200` Resource upserted successfully (application/json: DataResponse_FederatedResourceResponse)
- `400` Invalid request
- `401` Authentication required
- `403` Not authorized - must be a publisher
- `500` Internal server error

### GET /federation/{id}

Operation ID: `get_resource`
Operation page: `/api/operations/get_resource`
Get a specific federated resource by ID.

Parameters:
- `id` (path, required): string / uuid - Federated resource ID

Responses:
- `200` Resource retrieved successfully (application/json: DataResponse_FederatedResourceResponse)
- `404` Resource not found
- `500` Internal server error

### DELETE /federation/{resource_type}/{external_id}

Operation ID: `delete_resource`
Operation page: `/api/operations/delete_resource`
Delete a federated resource by type and external ID.
Only the owning publisher can delete their resources.

Parameters:
- `resource_type` (path, required): string - Resource type
- `external_id` (path, required): string - External resource ID

Responses:
- `204` Resource deleted successfully
- `401` Authentication required
- `403` Not authorized to delete this resource
- `404` Resource not found
- `500` Internal server error

### GET /federation/history

Operation ID: `list_history`
Operation page: `/api/operations/list_history`
List append-only federation history events.

Parameters:
- `publisher_slug` (query): string | null - Filter by publisher slug
- `resource_type` (query): string | null - Filter by resource type
- `external_id` (query): string | null - Filter by external resource ID
- `operation` (query): string | null - Filter by history operation: insert, update, delete
- `limit` (query): integer / int64 - Maximum number of results (default: 50, max: 100)
- `offset` (query): integer / int64 - Offset for pagination

Responses:
- `200` History retrieved successfully (application/json: DataResponse_Vec_FederatedResourceHistoryResponse)
- `400` Invalid query parameters
- `500` Internal server error

### GET /federation/history/stats

Operation ID: `get_history_stats`
Operation page: `/api/operations/get_history_stats`
Get aggregate statistics over federation history.

Parameters:
- `publisher_slug` (query): string | null - Filter by publisher slug (optional)
- `resource_type` (query): string | null - Filter by resource type (optional)

Responses:
- `200` History stats retrieved successfully (application/json: DataResponse_FederationHistoryStatsResponse)
- `500` Internal server error

### GET /federation/stats

Operation ID: `get_stats`
Operation page: `/api/operations/get_stats`
Get federation statistics, optionally filtered by publisher.

Parameters:
- `publisher_slug` (query): string | null - Filter by publisher slug (optional - if omitted, returns stats across all publishers)

Responses:
- `200` Stats retrieved successfully (application/json: DataResponse_FederationStatsResponse)
- `500` Internal server error

## Health

### GET /publishers/seren-memory

Operation ID: `seren_memory_root`
Operation page: `/api/operations/seren_memory_root`
Describe the Seren Memory service

Responses:
- `200` Service health (application/json: SerenMemoryDataResponse_HealthResponse)

### GET /publishers/seren-memory/health

Operation ID: `seren_memory_health`
Operation page: `/api/operations/seren_memory_health`
Check service health

Responses:
- `200` Service health (application/json: SerenMemoryDataResponse_HealthResponse)

### GET /publishers/seren-memory/health/detailed

Operation ID: `seren_memory_health_detailed`
Operation page: `/api/operations/seren_memory_health_detailed`
Check detailed service health

Responses:
- `200` Detailed service health (application/json: SerenMemoryDataResponse_HealthResponse)

### GET /publishers/seren-memory/livez

Operation ID: `seren_memory_livez`
Operation page: `/api/operations/seren_memory_livez`
Check process liveness

Responses:
- `200` Process is live

### GET /publishers/seren-memory/readyz

Operation ID: `seren_memory_readyz`
Operation page: `/api/operations/seren_memory_readyz`
Check service readiness

Responses:
- `200` Service is ready (application/json: SerenMemoryDataResponse_ReadinessResponse)
- `503` A required dependency is unavailable (application/json: SerenMemoryDataResponse_ReadinessResponse)

### GET /publishers/seren-storage/health

Operation ID: `seren_storage_health`
Operation page: `/api/operations/seren_storage_health`

Responses:
- `200` Service health (application/json: SerenStorageDataResponse_HealthStatus)

## Identities

### GET /publishers/seren-passwords/identities

Operation ID: `identity_list`
Operation page: `/api/operations/identity_list`
List active identities visible to the caller (org-scoped).

Responses:
- `200` Identities in this organization (application/json: DataResponseIdentityRecordList)
- `401` Caller is not authenticated
- `403` Agent callers may not enumerate identities

### GET /publishers/seren-passwords/identities/{identity_id}

Operation ID: `identity_get`
Operation page: `/api/operations/identity_get`
Fetch a single identity by id.

Parameters:
- `identity_id` (path, required): string / uuid - Identity id

Responses:
- `200` Identity record (application/json: DataResponseIdentityRecord)
- `401` Caller is not authenticated
- `403` Agent callers may not look up other identities
- `404` Identity not found

### POST /publishers/seren-passwords/identities/{identity_id}/revoke

Operation ID: `identity_revoke`
Operation page: `/api/operations/identity_revoke`
Revoke an identity owned by the calling user.

Soft-revocation: the identity stays in the directory for audit reasons
but is rejected on subsequent authenticated calls and access checks.

Parameters:
- `identity_id` (path, required): string / uuid - Identity id to revoke

Responses:
- `200` Revoked (application/json: DataResponseJsonValue)
- `401` Caller is not authenticated
- `403` Caller does not own the target identity
- `404` Identity not found

### GET /publishers/seren-passwords/identities/agents

Operation ID: `agent_identity_list`
Operation page: `/api/operations/agent_identity_list`
List the calling user's owned, active agent identities, each with the
vaults that agent currently has access to. Powers `seren passwords agent
list`. Returns only public key material and grant metadata; no wrapped key
material ever appears in the response.

Responses:
- `200` Owned agent identities and their vault grants (application/json: DataResponseAgentSummaryList)
- `401` Caller is not authenticated
- `403` Only user identities may list agents

### POST /publishers/seren-passwords/identities/agents

Operation ID: `agent_identity_create`
Operation page: `/api/operations/agent_identity_create`
Create an agent identity owned by the calling user. The server verifies
an Ed25519 signature over the canonical request bytes before persisting
the new identity; the signature itself is not stored in the audit row.

Request body (required):
- `application/json`: CreateAgentIdentityRequest

Responses:
- `200` Newly created agent identity (application/json: DataResponseIdentityRecord)
- `400` Malformed body, canonical signature payload, or signature verification failure
- `401` Caller is not authenticated
- `403` Only user identities may create agents
- `404` Caller has no active account identity
- `422` Request body failed validation

### POST /publishers/seren-passwords/identities/agents/freeze

Operation ID: `agent_identity_freeze`
Operation page: `/api/operations/agent_identity_freeze`
Revoke every active agent identity owned by the calling user.

Responses:
- `200` Owned active agent identities revoked (application/json: DataResponseAgentFreeze)
- `401` Caller is not authenticated
- `403` Only user identities may freeze agents
- `404` Caller has no active account identity

### POST /publishers/seren-passwords/identities/agents/hosted

Operation ID: `agent_identity_create_hosted`
Operation page: `/api/operations/agent_identity_create_hosted`
Create a hosted agent identity owned by the calling user. The server
generates the agent keypairs and stores only KMS-wrapped private-key
envelopes. The user signs the creation intent before the server persists
anything.

Request body (required):
- `application/json`: CreateHostedAgentIdentityRequest

Responses:
- `200` Newly created hosted agent identity (application/json: DataResponseIdentityRecord)
- `400` Malformed body, canonical signature payload, signature verification failure, or hosted-agent KMS unavailable
- `401` Caller is not authenticated
- `403` Only user identities may create agents
- `404` Caller has no active account identity
- `422` Request body failed validation

### POST /publishers/seren-passwords/identities/agents/hosted/ensure

Operation ID: `agent_identity_ensure_hosted`
Operation page: `/api/operations/agent_identity_ensure_hosted`
Return the active hosted agent identity for a user-defined provenance
context, creating it when absent.

Request body (required):
- `application/json`: CreateHostedAgentIdentityRequest

Responses:
- `200` Existing or newly created hosted agent identity (application/json: DataResponseIdentityRecord)
- `400` Malformed body, missing provenance context, canonical signature payload, signature verification failure, or hosted-agent KMS unavailable
- `401` Caller is not authenticated
- `403` Only user identities may ensure agents
- `404` Caller has no active account identity
- `422` Request body failed validation

### GET /publishers/seren-passwords/identities/me

Operation ID: `identity_get_me`
Operation page: `/api/operations/identity_get_me`
Fetch the effective active identity for the caller. Agent callers receive
their agent identity, hosted API-key callers receive the hosted identity
bound to that key, and browser user sessions receive the user identity.

Responses:
- `200` Caller's active identity (application/json: DataResponseIdentityRecord)
- `401` Caller is not authenticated
- `404` Agent identity not found, revoked, or user has no active account identity

## Invitations

### POST /publishers/seren-passwords/invitations/{invitation_id}/complete

Operation ID: `invitation_complete`
Operation page: `/api/operations/invitation_complete`
Complete a redeemed invitation by storing the vault key wrapped for the
recipient identity. Same-org recipients become local memberships; cross-org
recipients become owner-side foreign memberships plus a recipient discovery
pointer.

Parameters:
- `invitation_id` (path, required): string / uuid - Invitation id

Request body (required):
- `application/json`: CompleteInvitationRequest

Responses:
- `200` Completed membership (application/json: DataResponseMembershipRecord)
- `400` Malformed request or grant signature
- `401` Caller is not authenticated
- `403` Caller is not an admin of this vault
- `404` Invitation not found
- `409` Recipient already has an active membership
- `422` Request body failed validation
- `423` Vault is locked due to ongoing key rotation

### GET /publishers/seren-passwords/invitations/pending

Operation ID: `invitation_list_pending`
Operation page: `/api/operations/invitation_list_pending`
List invitations the caller has issued that are awaiting a vault-key
re-wrap on the inviter side.

Responses:
- `200` Pending invitations awaiting wrap (application/json: DataResponseInvitationViewList)
- `401` Caller is not authenticated
- `404` Caller has no active account identity

### POST /publishers/seren-passwords/invitations/redeem

Operation ID: `invitation_redeem`
Operation page: `/api/operations/invitation_redeem`
Redeem an invitation token. The caller becomes the awaited identity that
the inviter then re-wraps the vault key for.

Request body (required):
- `application/json`: RedeemRequest

Responses:
- `200` Redeemed invitation (application/json: DataResponseInvitationView)
- `400` Missing or malformed invitation_token
- `401` Caller is not authenticated
- `403` Agents may not redeem invitations
- `404` Token does not match any active invitation
- `422` Request body failed validation

### GET /publishers/seren-passwords/vaults/{vault_id}/invitations

Operation ID: `invitation_list_for_vault`
Operation page: `/api/operations/invitation_list_for_vault`
List all invitations issued for a vault. Admin only.

Parameters:
- `vault_id` (path, required): string / uuid - Vault id

Responses:
- `200` Vault invitations (application/json: DataResponseInvitationViewList)
- `401` Caller is not authenticated
- `403` Caller is not an admin of this vault
- `404` Vault not found

### POST /publishers/seren-passwords/vaults/{vault_id}/invitations

Operation ID: `invitation_create`
Operation page: `/api/operations/invitation_create`
Mint an out-of-band invitation token for an email address; the response
echoes the plain token once so the inviter can deliver it out of band.

Parameters:
- `vault_id` (path, required): string / uuid - Vault id

Request body (required):
- `application/json`: CreateInvitationRequest

Responses:
- `200` Invitation token (one-shot) (application/json: DataResponseInvitationCreated)
- `400` Malformed request or invitation tokens unavailable
- `401` Caller is not authenticated
- `403` Caller is not an admin of this vault
- `404` Vault not found
- `409` Invitation id or token already exists
- `422` Request body failed validation

## Items

### GET /publishers/seren-passwords/vaults/{vault_id}/items

Operation ID: `item_list`
Operation page: `/api/operations/item_list`
List item summaries in a vault, optionally filtered by lifecycle state,
blind index, or `updated_since` for delta-sync.

Parameters:
- `vault_id` (path, required): string / uuid - Vault id
- `title_blind_index` (query): string | null - Optional base64-encoded blind-index for exact title lookup.
- `state` (query): null | ListStateParam - Lifecycle state to list. Defaults to active. `trashed` returns items in the trash (DELETE'd but not yet hard-deleted); `archived` returns archived items (the existing `archived_at` lifecycle).
- `updated_since` (query): string | null / date-time - RFC3339 timestamp. When set, only items with `updated_at` strictly greater than this point appear in the result. Delta-sync callers should pass the most recent `updated_at` they have already ingested; the boundary row is excluded so polling does not re-deliver it.

Responses:
- `200` Item summaries (application/json: DataResponseItemSummaryList)
- `400` Malformed query (e.g. invalid blind index)
- `401` Caller is not authenticated
- `404` Vault not found or caller is not a member

### POST /publishers/seren-passwords/vaults/{vault_id}/items

Operation ID: `item_create`
Operation page: `/api/operations/item_create`
Create an encrypted item in a vault. Requires write membership and is
blocked while the vault is in `rotating` state. Emits a weak `ETag`
header derived from `updated_at` so the client can immediately PATCH
the freshly-created row without an extra GET.

Parameters:
- `vault_id` (path, required): string / uuid - Vault id

Request body (required):
- `application/json`: CreateItemRequest

Responses:
- `200` Created item record (application/json: DataResponseItemRecord)
- `401` Caller is not authenticated
- `403` Caller does not have write access
- `404` Vault not found
- `409` wrapping_key_version did not match vault_key_version
- `422` Request body failed validation
- `423` Vault is locked due to ongoing key rotation

### DELETE /publishers/seren-passwords/vaults/{vault_id}/items/{item_id}

Operation ID: `item_delete`
Operation page: `/api/operations/item_delete`
Trash an item. A second DELETE on a trashed item hard-deletes the row.

Parameters:
- `vault_id` (path, required): string / uuid - Vault id
- `item_id` (path, required): string / uuid - Item id

Responses:
- `200` Body is `{"data":{"state":"trashed"}}` on the first DELETE against an active item, and `{"data":{"state":"hard_deleted"}}` on a second DELETE against an already-trashed item (application/json: DataResponseJsonValue)
- `401` Caller is not authenticated
- `403` Caller does not have write access
- `404` Vault or item not found
- `423` Vault is locked due to ongoing key rotation

### GET /publishers/seren-passwords/vaults/{vault_id}/items/{item_id}

Operation ID: `item_get`
Operation page: `/api/operations/item_get`
Fetch one item by id. Emits a weak `ETag` header derived from
`updated_at` for use with `If-Match` on PATCH.

Parameters:
- `vault_id` (path, required): string / uuid - Vault id
- `item_id` (path, required): string / uuid - Item id

Responses:
- `200` Item record (application/json: DataResponseItemRecord)
- `401` Caller is not authenticated
- `403` Approval required; see error.approval_request_id
- `404` Vault or item not found
- `429` Item read rate limit exceeded

### PATCH /publishers/seren-passwords/vaults/{vault_id}/items/{item_id}

Operation ID: `item_update`
Operation page: `/api/operations/item_update`
Update an item's ciphertext. Honors `If-Match` for optimistic concurrency
(412 when stale) and rejects writes during rotation (423).

Parameters:
- `vault_id` (path, required): string / uuid - Vault id
- `item_id` (path, required): string / uuid - Item id
- `If-Match` (header): string | null - Weak ETag from a prior GET; rejected with 412 if it does not match updated_at

Request body (required):
- `application/json`: UpdateItemRequest

Responses:
- `200` Updated item record (application/json: DataResponseItemRecord)
- `400` Malformed If-Match header
- `401` Caller is not authenticated
- `403` Caller does not have write access
- `404` Vault or item not found
- `409` wrapping_key_version did not match vault_key_version
- `412` If-Match etag does not match the stored updated_at
- `422` Request body failed validation
- `423` Vault is locked due to ongoing key rotation

### POST /publishers/seren-passwords/vaults/{vault_id}/items/{item_id}/duplicate

Operation ID: `item_duplicate`
Operation page: `/api/operations/item_duplicate`
Duplicate an encrypted item. The duplicate receives a new item id; because
item ciphertext is AAD-bound to item id, the client supplies ciphertexts
encrypted for that new id and a content-key wrap sealed under the
destination vault key.

Parameters:
- `vault_id` (path, required): string / uuid - Source vault id
- `item_id` (path, required): string / uuid - Source item id

Request body (required):
- `application/json`: DuplicateItemRequest

Responses:
- `200` Duplicated item record (application/json: DataResponseItemRecord)
- `400` Malformed duplicate request
- `401` Caller is not authenticated
- `403` Caller does not have write access
- `404` Source or target vault/item not found
- `409` wrapping_key_version did not match target vault_key_version
- `422` Request body failed validation
- `423` Source or target vault is locked due to ongoing key rotation

### GET /publishers/seren-passwords/vaults/{vault_id}/items/{item_id}/history

Operation ID: `item_history_list`
Operation page: `/api/operations/item_history_list`
List archived prior content ciphertexts for an item, oldest first.

Parameters:
- `vault_id` (path, required): string / uuid - Vault id
- `item_id` (path, required): string / uuid - Item id

Responses:
- `200` History entries (application/json: DataResponseHistoryEntryList)
- `401` Caller is not authenticated
- `403` Approval required; see error.approval_request_id
- `404` Vault or item not found
- `429` Item read rate limit exceeded

### POST /publishers/seren-passwords/vaults/{vault_id}/items/{item_id}/move

Operation ID: `item_move`
Operation page: `/api/operations/item_move`
Move an encrypted item to another vault. The item id and body ciphertext
stay stable; the client supplies vault-key-scoped ciphertexts and the
content-key wrap re-sealed under the target vault key.

Parameters:
- `vault_id` (path, required): string / uuid - Source vault id
- `item_id` (path, required): string / uuid - Item id

Request body (required):
- `application/json`: MoveItemRequest

Responses:
- `200` Moved item record (application/json: DataResponseItemRecord)
- `400` Malformed move request
- `401` Caller is not authenticated
- `403` Caller does not have write access
- `404` Source or target vault/item not found
- `409` wrapping_key_version did not match target vault_key_version
- `422` Request body failed validation
- `423` Source or target vault is locked due to ongoing key rotation

### POST /publishers/seren-passwords/vaults/{vault_id}/items/{item_id}/restore

Operation ID: `item_restore`
Operation page: `/api/operations/item_restore`
Restore a trashed item. Active and archived items return 409.

Parameters:
- `vault_id` (path, required): string / uuid - Vault id
- `item_id` (path, required): string / uuid - Item id

Responses:
- `200` Restored item record (application/json: DataResponseItemRecord)
- `401` Caller is not authenticated
- `403` Caller does not have write access
- `404` Vault or item not found
- `409` Item is already active or is archived
- `423` Vault is locked due to ongoing key rotation

## Knowledge

### GET /publishers/seren-memory/knowledge/domains

Operation ID: `seren_memory_list_knowledge_domains`
Operation page: `/api/operations/seren_memory_list_knowledge_domains`
List accessible organizational knowledge domains

Responses:
- `200` Accessible knowledge domains (application/json: SerenMemoryDataResponse_KnowledgeDomainsResponse)
- `401` Authentication required (application/json: SerenMemoryErrorBody)

### POST /publishers/seren-memory/knowledge/entities/open

Operation ID: `seren_memory_open_knowledge_entity`
Operation page: `/api/operations/seren_memory_open_knowledge_entity`
Open an organizational knowledge entity

Request body (required):
- `application/json`: SerenMemoryOpenKnowledgeEntityRequest

Responses:
- `200` Organizational knowledge entity (application/json: SerenMemoryDataResponse_KnowledgeOperationResult)
- `400` Invalid request (application/json: SerenMemoryErrorBody)
- `401` Authentication required (application/json: SerenMemoryErrorBody)
- `404` Organizational knowledge is not published (application/json: SerenMemoryErrorBody)
- `502` Knowledge backend unavailable (application/json: SerenMemoryErrorBody)

### GET /publishers/seren-memory/knowledge/operations

Operation ID: `seren_memory_list_knowledge_operations`
Operation page: `/api/operations/seren_memory_list_knowledge_operations`
List available organizational knowledge operations

Parameters:
- `domain_id` (query): string | null / uuid

Responses:
- `200` Published organizational knowledge operations (application/json: SerenMemoryDataResponse_KnowledgeOperationsResponse)
- `401` Authentication required (application/json: SerenMemoryErrorBody)
- `404` Knowledge is not configured (application/json: SerenMemoryErrorBody)
- `502` Knowledge service unavailable (application/json: SerenMemoryErrorBody)

### POST /publishers/seren-memory/knowledge/operations/{operation_name}

Operation ID: `seren_memory_invoke_knowledge_operation`
Operation page: `/api/operations/seren_memory_invoke_knowledge_operation`
Invoke a published organizational knowledge operation

Parameters:
- `operation_name` (path, required): string - Published operation name

Request body (required):
- `application/json`: SerenMemoryInvokeKnowledgeOperationRequest

Responses:
- `200` Organizational knowledge operation result (application/json: SerenMemoryDataResponse_KnowledgeOperationResult)
- `400` Invalid operation or parameters (application/json: SerenMemoryErrorBody)
- `401` Authentication required (application/json: SerenMemoryErrorBody)
- `404` Knowledge is not configured (application/json: SerenMemoryErrorBody)
- `502` Knowledge service unavailable (application/json: SerenMemoryErrorBody)

### POST /publishers/seren-memory/knowledge/search

Operation ID: `seren_memory_search_knowledge`
Operation page: `/api/operations/seren_memory_search_knowledge`
Search governed organizational knowledge

Request body (required):
- `application/json`: SerenMemorySearchKnowledgeRequest

Responses:
- `200` Organizational knowledge query result (application/json: SerenMemoryDataResponse_KnowledgeOperationResult)
- `400` Invalid request (application/json: SerenMemoryErrorBody)
- `401` Authentication required (application/json: SerenMemoryErrorBody)
- `404` Organizational knowledge is not published (application/json: SerenMemoryErrorBody)
- `502` Knowledge backend unavailable (application/json: SerenMemoryErrorBody)

## Knowledge Administration

### POST /publishers/seren-memory/knowledge/domains

Operation ID: `seren_memory_create_knowledge_domain`
Operation page: `/api/operations/seren_memory_create_knowledge_domain`
Create an organizational knowledge domain

Request body (required):
- `application/json`: SerenMemoryCreateKnowledgeDomainRequest

Responses:
- `200` Created knowledge domain (application/json: SerenMemoryDataResponse_KnowledgeDomainResponse)
- `400` Invalid domain (application/json: SerenMemoryErrorBody)
- `401` Authentication required (application/json: SerenMemoryErrorBody)
- `403` Organization owner or administrator required (application/json: SerenMemoryErrorBody)
- `409` Domain slug already exists (application/json: SerenMemoryErrorBody)
- `413` Organization knowledge domain limit exceeded (application/json: SerenMemoryErrorBody)

### PUT /publishers/seren-memory/knowledge/domains/{domain_id}

Operation ID: `seren_memory_put_knowledge_domain`
Operation page: `/api/operations/seren_memory_put_knowledge_domain`
Update an organizational knowledge domain

Parameters:
- `domain_id` (path, required): string / uuid - Knowledge domain identifier

Request body (required):
- `application/json`: SerenMemoryUpdateKnowledgeDomainRequest

Responses:
- `200` Updated knowledge domain (application/json: SerenMemoryDataResponse_KnowledgeDomainResponse)
- `400` Invalid domain (application/json: SerenMemoryErrorBody)
- `401` Authentication required (application/json: SerenMemoryErrorBody)
- `403` Domain owner permission required (application/json: SerenMemoryErrorBody)

### GET /publishers/seren-memory/knowledge/domains/{domain_id}/grants

Operation ID: `seren_memory_list_knowledge_domain_grants`
Operation page: `/api/operations/seren_memory_list_knowledge_domain_grants`
List grants for an organizational knowledge domain

Parameters:
- `domain_id` (path, required): string / uuid - Knowledge domain identifier

Responses:
- `200` Knowledge domain grants (application/json: SerenMemoryDataResponse_KnowledgeDomainGrantsResponse)
- `401` Authentication required (application/json: SerenMemoryErrorBody)
- `403` Domain owner permission required (application/json: SerenMemoryErrorBody)

### PUT /publishers/seren-memory/knowledge/domains/{domain_id}/grants

Operation ID: `seren_memory_put_knowledge_domain_grant`
Operation page: `/api/operations/seren_memory_put_knowledge_domain_grant`
Set a grant for an organizational knowledge domain

Parameters:
- `domain_id` (path, required): string / uuid - Knowledge domain identifier

Request body (required):
- `application/json`: SerenMemoryKnowledgeDomainGrantRequest

Responses:
- `200` Knowledge domain grant (application/json: SerenMemoryDataResponse_KnowledgeDomainGrantResponse)
- `400` Invalid grant (application/json: SerenMemoryErrorBody)
- `401` Authentication required (application/json: SerenMemoryErrorBody)
- `403` Domain owner permission required (application/json: SerenMemoryErrorBody)

### DELETE /publishers/seren-memory/knowledge/domains/{domain_id}/grants/{principal_type}/{principal_id}

Operation ID: `seren_memory_delete_knowledge_domain_grant`
Operation page: `/api/operations/seren_memory_delete_knowledge_domain_grant`
Remove a grant from an organizational knowledge domain

Parameters:
- `domain_id` (path, required): string / uuid
- `principal_type` (path, required): string
- `principal_id` (path, required): string / uuid

Responses:
- `200` Knowledge domain grant deletion result (application/json: SerenMemoryDataResponse_DeleteKnowledgeDomainGrantResponse)
- `400` Invalid principal type (application/json: SerenMemoryErrorBody)
- `401` Authentication required (application/json: SerenMemoryErrorBody)
- `403` Domain owner permission required (application/json: SerenMemoryErrorBody)
- `409` Domain must retain an owner (application/json: SerenMemoryErrorBody)

### GET /publishers/seren-memory/knowledge/model

Operation ID: `seren_memory_get_knowledge_model`
Operation page: `/api/operations/seren_memory_get_knowledge_model`
Get the desired organizational knowledge model

Parameters:
- `domain_id` (query): string | null / uuid

Responses:
- `200` Organization knowledge model (application/json: SerenMemoryDataResponse_KnowledgeModelConfigurationResponse)
- `401` Authentication required (application/json: SerenMemoryErrorBody)
- `403` Domain editor permission required (application/json: SerenMemoryErrorBody)
- `404` Knowledge model is not configured (application/json: SerenMemoryErrorBody)

### PUT /publishers/seren-memory/knowledge/model

Operation ID: `seren_memory_put_knowledge_model`
Operation page: `/api/operations/seren_memory_put_knowledge_model`
Set the desired organizational knowledge model

Parameters:
- `domain_id` (query): string | null / uuid

Request body (required):
- `application/json`: SerenMemoryKnowledgeModel

Responses:
- `200` Queued organization knowledge model (application/json: SerenMemoryDataResponse_KnowledgeModelConfigurationResponse)
- `400` Invalid knowledge model (application/json: SerenMemoryErrorBody)
- `401` Authentication required (application/json: SerenMemoryErrorBody)
- `403` Domain editor or organization administrator required (application/json: SerenMemoryErrorBody)

### GET /publishers/seren-memory/knowledge/records

Operation ID: `seren_memory_list_knowledge_records`
Operation page: `/api/operations/seren_memory_list_knowledge_records`
List canonical organizational knowledge records

Parameters:
- `domain_id` (query): string | null / uuid
- `limit` (query): integer | null / int64
- `offset` (query): integer | null / int64

Responses:
- `200` Canonical organization knowledge records (application/json: SerenMemoryDataResponse_ListKnowledgeRecordsResponse)
- `401` Authentication required (application/json: SerenMemoryErrorBody)
- `403` Human organization member required (application/json: SerenMemoryErrorBody)

### DELETE /publishers/seren-memory/knowledge/records/{record_key}

Operation ID: `seren_memory_delete_knowledge_record`
Operation page: `/api/operations/seren_memory_delete_knowledge_record`
Delete a canonical organizational knowledge record

Parameters:
- `record_key` (path, required): string - Stable record key
- `domain_id` (query): string | null / uuid

Responses:
- `200` Knowledge record deletion result (application/json: SerenMemoryDataResponse_DeleteKnowledgeRecordResponse)
- `401` Authentication required (application/json: SerenMemoryErrorBody)
- `403` Human organization member required (application/json: SerenMemoryErrorBody)

### PUT /publishers/seren-memory/knowledge/records/{record_key}

Operation ID: `seren_memory_put_knowledge_record`
Operation page: `/api/operations/seren_memory_put_knowledge_record`
Create or replace a canonical organizational knowledge record

Parameters:
- `record_key` (path, required): string - Stable record key
- `domain_id` (query): string | null / uuid

Request body (required):
- `application/json`: SerenMemoryUpsertKnowledgeRecordRequest

Responses:
- `200` Queued canonical knowledge record (application/json: SerenMemoryDataResponse_KnowledgeRecordResponse)
- `400` Invalid knowledge record (application/json: SerenMemoryErrorBody)
- `401` Authentication required (application/json: SerenMemoryErrorBody)
- `403` Domain editor permission required (application/json: SerenMemoryErrorBody)
- `404` Knowledge model is not configured (application/json: SerenMemoryErrorBody)
- `413` Organization knowledge limit exceeded (application/json: SerenMemoryErrorBody)

## MCP

### POST /publishers/seren-memory/mcp

Operation ID: `seren_memory_mcp_handler`
Operation page: `/api/operations/seren_memory_mcp_handler`
Call the Seren Memory MCP transport

Request body (required):
- `application/json`: object

Responses:
- `200` MCP protocol response
- `401` Authentication required (application/json: SerenMemoryErrorBody)

## Memberships

### DELETE /publishers/seren-passwords/vaults/{vault_id}/foreign-memberships/{recipient_organization_id}/{recipient_identity_id}

Operation ID: `membership_revoke_foreign`
Operation page: `/api/operations/membership_revoke_foreign`
Revoke a cross-organization member's access to a vault. Requires admin
membership in the owner org and updates the recipient-local discovery
pointer after the owner-side revoke commits.

Parameters:
- `vault_id` (path, required): string / uuid - Vault id
- `recipient_organization_id` (path, required): string / uuid - Recipient organization id
- `recipient_identity_id` (path, required): string / uuid - Recipient identity id

Responses:
- `200` Revoked (application/json: DataResponseJsonValue)
- `401` Caller is not authenticated
- `403` Caller is not an admin of this vault
- `404` Vault or foreign membership not found
- `423` Vault is locked due to ongoing key rotation

### GET /publishers/seren-passwords/vaults/{vault_id}/memberships

Operation ID: `membership_list`
Operation page: `/api/operations/membership_list`
List active memberships for a vault.

Parameters:
- `vault_id` (path, required): string / uuid - Vault id

Responses:
- `200` Membership list (application/json: DataResponseMembershipRecordList)
- `401` Caller is not authenticated
- `404` Vault not found or caller is not a member

### POST /publishers/seren-passwords/vaults/{vault_id}/memberships

Operation ID: `membership_grant`
Operation page: `/api/operations/membership_grant`
Grant a vault membership to an identity. Requires admin membership on the
vault and is blocked while the vault is in `rotating` state.

Parameters:
- `vault_id` (path, required): string / uuid - Vault id

Request body (required):
- `application/json`: MembershipGrantRequest

Responses:
- `200` Granted membership (application/json: DataResponseMembershipRecord)
- `400` granted_signature fails verification
- `401` Caller is not authenticated
- `403` Caller is not an admin of this vault
- `404` Vault not found
- `409` Identity already has an active membership
- `422` Request body failed validation
- `423` Vault is locked due to ongoing key rotation

### DELETE /publishers/seren-passwords/vaults/{vault_id}/memberships/{identity_id}

Operation ID: `membership_revoke`
Operation page: `/api/operations/membership_revoke`
Revoke a member's access to a vault. Requires admin membership.

Parameters:
- `vault_id` (path, required): string / uuid - Vault id
- `identity_id` (path, required): string / uuid - Identity whose membership to revoke

Responses:
- `200` Revoked (application/json: DataResponseJsonValue)
- `401` Caller is not authenticated
- `403` Caller is not an admin of this vault
- `404` Vault or membership not found
- `409` Revocation would remove the final active admin
- `423` Vault is locked due to ongoing key rotation

### PUT /publishers/seren-passwords/vaults/{vault_id}/memberships/{identity_id}

Operation ID: `membership_update_access`
Operation page: `/api/operations/membership_update_access`
Change an active membership's access level atomically. Requires a fresh
grant signature from an active vault admin and is blocked during rotation.

Parameters:
- `vault_id` (path, required): string / uuid - Vault id
- `identity_id` (path, required): string / uuid - Identity whose access level to update

Request body (required):
- `application/json`: MembershipGrantRequest

Responses:
- `200` Updated membership (application/json: DataResponseMembershipRecord)
- `400` Path identity does not match the body or granted_signature fails verification
- `401` Caller is not authenticated
- `403` Caller is not an admin of this vault
- `404` Vault or active membership not found
- `409` Access is unchanged or the update would remove the final active admin
- `422` Request body failed validation
- `423` Vault is locked due to ongoing key rotation

## Memory

### POST /publishers/seren-memory/bootstrap

Operation ID: `seren_memory_session_bootstrap`
Operation page: `/api/operations/seren_memory_session_bootstrap`
Bootstrap private context for a session

Request body (required):
- `application/json`: SerenMemorySessionBootstrapParams

Responses:
- `200` Session memory context (application/json: SerenMemoryDataResponse_SessionContext)
- `400` Invalid request (application/json: SerenMemoryErrorBody)
- `401` Authentication required (application/json: SerenMemoryErrorBody)

### POST /publishers/seren-memory/capture_agent_turn

Operation ID: `seren_memory_capture_agent_turn`
Operation page: `/api/operations/seren_memory_capture_agent_turn`
Capture a completed agent turn from a lifecycle hook

Dedicated ingestion operation for automatic agent capture. Accepts prompt and assistant-response content as separate fields so the current organization policy can independently permit each content class before the service assembles an extraction transcript. Requires a stable source_external_id in the reserved hook: namespace and the current server-issued organization policy_version. Stale callers must refresh the policy and re-sanitize queued content. The operation always stores a metadata source envelope for idempotent retries and stores the assembled raw payload only when both retain_source is requested and organization policy permits it. Source metadata is provenance validated against a separate 16,000-byte serialized bound and does not count against max_transcript_bytes.

Request body (required):
- `application/json`: SerenMemoryCaptureAgentTurnParams

Responses:
- `200` Extracted memory candidates (application/json: SerenMemoryDataResponse_ExtractionResult)
- `400` Invalid request (application/json: SerenMemoryErrorBody)
- `401` Authentication required (application/json: SerenMemoryErrorBody)
- `403` Automatic capture or the requested capture mode is disabled by organization policy (application/json: SerenMemoryErrorBody)
- `409` The submitted organization policy revision is stale (application/json: SerenMemoryErrorBody)
- `413` The captured transcript and project context exceed the organization policy limit (application/json: SerenMemoryErrorBody)
- `503` The organization policy could not be verified (application/json: SerenMemoryErrorBody)

### POST /publishers/seren-memory/forget

Operation ID: `seren_memory_forget_memory`
Operation page: `/api/operations/seren_memory_forget_memory`
Soft-delete a private memory

Request body (required):
- `application/json`: SerenMemoryForgetParams

Responses:
- `200` Memory forgetting result (application/json: SerenMemoryDataResponse_ForgetMemoryResponse)
- `401` Authentication required (application/json: SerenMemoryErrorBody)
- `500` Unexpected service error (application/json: SerenMemoryErrorBody)

### POST /publishers/seren-memory/ingest/document

Operation ID: `seren_memory_ingest_document`
Operation page: `/api/operations/seren_memory_ingest_document`
Ingest a managed rich document

Request body (required):
- `application/json`: SerenMemoryIngestDocumentRequest

Responses:
- `200` Document ingestion result (application/json: SerenMemoryDataResponse_IngestDocumentOutput)
- `400` Invalid request (application/json: SerenMemoryErrorBody)
- `401` Authentication required (application/json: SerenMemoryErrorBody)

### POST /publishers/seren-memory/jobs/consolidate

Operation ID: `seren_memory_consolidate_job`
Operation page: `/api/operations/seren_memory_consolidate_job`
Consolidate private memories

Request body (required):
- `application/json`: SerenMemoryConsolidateJobRequest

Responses:
- `200` Consolidation result (application/json: SerenMemoryDataResponse_ConsolidateJobResponse)
- `401` Authentication required (application/json: SerenMemoryErrorBody)
- `500` Unexpected service error (application/json: SerenMemoryErrorBody)

### POST /publishers/seren-memory/learn_from_error

Operation ID: `seren_memory_learn_from_error`
Operation page: `/api/operations/seren_memory_learn_from_error`
Store a verified error and fix

Request body (required):
- `application/json`: SerenMemoryLearnFromErrorParams

Responses:
- `200` Learned memory result (application/json: SerenMemoryDataResponse_RememberOutput)
- `400` Invalid request (application/json: SerenMemoryErrorBody)
- `401` Authentication required (application/json: SerenMemoryErrorBody)

### GET /publishers/seren-memory/memories

Operation ID: `seren_memory_list_memories`
Operation page: `/api/operations/seren_memory_list_memories`
List private memories

Parameters:
- `memory_type` (query): string
- `is_pinned` (query): boolean
- `is_consolidated` (query): boolean
- `lifecycle_status` (query): SerenMemoryMemoryLifecycle
- `project_id` (query): string / uuid
- `org_id` (query): string / uuid
- `limit` (query): integer / int64
- `offset` (query): integer / int64

Responses:
- `200` Memories matching the requested scope (application/json: SerenMemoryDataResponse_ListMemoriesResponse)
- `400` Invalid request (application/json: SerenMemoryErrorBody)
- `401` Authentication required (application/json: SerenMemoryErrorBody)

### DELETE /publishers/seren-memory/memories/{id}

Operation ID: `seren_memory_delete_memory`
Operation page: `/api/operations/seren_memory_delete_memory`
Permanently delete a private memory

Parameters:
- `id` (path, required): string / uuid - Memory ID

Responses:
- `200` Memory deletion result (application/json: SerenMemoryDataResponse_DeleteMemoryResponse)
- `401` Authentication required (application/json: SerenMemoryErrorBody)
- `500` Unexpected service error (application/json: SerenMemoryErrorBody)

### GET /publishers/seren-memory/memories/{id}

Operation ID: `seren_memory_get_memory`
Operation page: `/api/operations/seren_memory_get_memory`
Get a private memory

Parameters:
- `id` (path, required): string / uuid - Memory ID

Responses:
- `200` Memory record (application/json: SerenMemoryDataResponse_Option_MemoryOutput)
- `401` Authentication required (application/json: SerenMemoryErrorBody)
- `500` Unexpected service error (application/json: SerenMemoryErrorBody)

### POST /publishers/seren-memory/memories/{id}/append

Operation ID: `seren_memory_append_memory`
Operation page: `/api/operations/seren_memory_append_memory`
Append to a private memory

Parameters:
- `id` (path, required): string / uuid - Memory ID

Request body (required):
- `application/json`: SerenMemoryAppendMemoryRequest

Responses:
- `200` Updated memory (application/json: SerenMemoryDataResponse_MemoryOutput)
- `400` Invalid request (application/json: SerenMemoryErrorBody)
- `401` Authentication required (application/json: SerenMemoryErrorBody)
- `404` Memory not found (application/json: SerenMemoryErrorBody)
- `409` Source-managed memory requires re-ingestion (application/json: SerenMemoryErrorBody)

### PUT /publishers/seren-memory/memories/{id}/review

Operation ID: `seren_memory_set_memory_review`
Operation page: `/api/operations/seren_memory_set_memory_review`
Set a private memory review status

Explicit review transition. No ingestion channel grants reviewed trust automatically, and this operation is intentionally not exposed as an MCP tool.

Parameters:
- `id` (path, required): string / uuid - Memory ID

Request body (required):
- `application/json`: SerenMemorySetMemoryReviewRequest

Responses:
- `200` Review transition result (application/json: SerenMemoryDataResponse_SetMemoryReviewResponse)
- `401` Authentication required (application/json: SerenMemoryErrorBody)
- `404` Memory not found (application/json: SerenMemoryErrorBody)

### GET /publishers/seren-memory/memories/{id}/revisions

Operation ID: `seren_memory_list_memory_revisions`
Operation page: `/api/operations/seren_memory_list_memory_revisions`
List a private memory's revisions

Parameters:
- `id` (path, required): string / uuid - Memory ID

Responses:
- `200` Memory revisions newest first (application/json: SerenMemoryDataResponse_Vec_MemoryRevision)
- `401` Authentication required (application/json: SerenMemoryErrorBody)
- `404` Memory not found (application/json: SerenMemoryErrorBody)

### PUT /publishers/seren-memory/memories/{id}/status

Operation ID: `seren_memory_set_memory_status`
Operation page: `/api/operations/seren_memory_set_memory_status`
Set a private memory lifecycle status

Parameters:
- `id` (path, required): string / uuid - Memory ID

Request body (required):
- `application/json`: SerenMemorySetMemoryStatusRequest

Responses:
- `200` Updated memory (application/json: SerenMemoryDataResponse_Option_MemoryOutput)
- `400` Invalid request (application/json: SerenMemoryErrorBody)
- `401` Authentication required (application/json: SerenMemoryErrorBody)

### GET /publishers/seren-memory/memories/{id}/timeline

Operation ID: `seren_memory_memory_timeline`
Operation page: `/api/operations/seren_memory_memory_timeline`

Parameters:
- `id` (path, required): string / uuid
- `as_of` (query): string | null / date-time

Responses:
- `200` Temporal memory relationships (application/json: SerenMemoryDataResponse_Vec_MemoryEdge)
- `401` Authentication required (application/json: SerenMemoryErrorBody)
- `404` Memory not found (application/json: SerenMemoryErrorBody)

### DELETE /publishers/seren-memory/memories/by-source

Operation ID: `seren_memory_delete_memories_by_source`
Operation page: `/api/operations/seren_memory_delete_memories_by_source`
Permanently delete retained sources and derived memories

Request body (required):
- `application/json`: SerenMemoryDeleteMemoriesBySourceParams

Responses:
- `200` Source deletion result (application/json: SerenMemoryDataResponse_DeleteBySourceOutcome)
- `400` Invalid request (application/json: SerenMemoryErrorBody)
- `401` Authentication required (application/json: SerenMemoryErrorBody)

### DELETE /publishers/seren-memory/memories/connections

Operation ID: `seren_memory_unlink_memories`
Operation page: `/api/operations/seren_memory_unlink_memories`
Disconnect two private memories

Request body (required):
- `application/json`: SerenMemoryMemoryConnectionRequest

Responses:
- `200` Connection result (application/json: SerenMemoryDataResponse_MemoryConnectionResponse)
- `400` Invalid request (application/json: SerenMemoryErrorBody)
- `401` Authentication required (application/json: SerenMemoryErrorBody)
- `404` Memory not found (application/json: SerenMemoryErrorBody)

### POST /publishers/seren-memory/memories/connections

Operation ID: `seren_memory_link_memories`
Operation page: `/api/operations/seren_memory_link_memories`
Connect two private memories

Request body (required):
- `application/json`: SerenMemoryMemoryConnectionRequest

Responses:
- `200` Connection result (application/json: SerenMemoryDataResponse_MemoryConnectionResponse)
- `400` Invalid request (application/json: SerenMemoryErrorBody)
- `401` Authentication required (application/json: SerenMemoryErrorBody)
- `404` Memory not found (application/json: SerenMemoryErrorBody)

### GET /publishers/seren-memory/memories/export

Operation ID: `seren_memory_export_memories`
Operation page: `/api/operations/seren_memory_export_memories`

Returns parallel pages from the memory and conversation-source collections. The same limit and offset are applied independently to each collection; continue with next_offset until it is null.

Parameters:
- `project_id` (query): string | null / uuid
- `limit` (query): integer | null / int64
- `offset` (query): integer | null / int64 - Shared offset applied independently to memories and conversation sources.

Responses:
- `200` Portable private-memory export page (application/json: SerenMemoryDataResponse_MemoryExportResponse)
- `401` Authentication required (application/json: SerenMemoryErrorBody)

### POST /publishers/seren-memory/migrations

Operation ID: `seren_memory_create_migration`
Operation page: `/api/operations/seren_memory_create_migration`
Create a durable import migration record

Request body (required):
- `application/json`: SerenMemoryCreateMigrationRequest

Responses:
- `200` Created migration (application/json: SerenMemoryDataResponse_MemoryMigration)
- `400` Invalid request (application/json: SerenMemoryErrorBody)
- `401` Authentication required (application/json: SerenMemoryErrorBody)
- `409` Snapshot or series identity conflict (application/json: SerenMemoryErrorBody)

### GET /publishers/seren-memory/migrations/{id}

Operation ID: `seren_memory_get_migration`
Operation page: `/api/operations/seren_memory_get_migration`
Get one migration record with live record counts

Parameters:
- `id` (path, required): string / uuid - Migration ID

Responses:
- `200` Migration status (application/json: SerenMemoryDataResponse_MigrationStatusResponse)
- `401` Authentication required (application/json: SerenMemoryErrorBody)
- `404` Migration not found (application/json: SerenMemoryErrorBody)

### POST /publishers/seren-memory/migrations/{id}/embeddings

Operation ID: `seren_memory_embed_migration_records`
Operation page: `/api/operations/seren_memory_embed_migration_records`
Generate embeddings for imported migration records

Processes a bounded batch of pending or failed imported memories. Call until embedding_pending and embedding_failed are both zero before completing the migration.

Parameters:
- `id` (path, required): string / uuid - Migration ID

Request body (required):
- `application/json`: SerenMemoryEmbedMigrationRecordsRequest

Responses:
- `200` Current embedding status (application/json: SerenMemoryDataResponse_EmbedMigrationRecordsResponse)
- `400` Invalid request (application/json: SerenMemoryErrorBody)
- `401` Authentication required (application/json: SerenMemoryErrorBody)
- `404` Migration not found (application/json: SerenMemoryErrorBody)
- `409` Migration state does not accept embedding work (application/json: SerenMemoryErrorBody)
- `502` Embedding service unavailable (application/json: SerenMemoryErrorBody)

### POST /publishers/seren-memory/migrations/{id}/records

Operation ID: `seren_memory_import_migration_records`
Operation page: `/api/operations/seren_memory_import_migration_records`
Import a batch of already-extracted records under a migration

Records use the reserved import: namespace and are idempotent per source_external_id. Extraction never runs. The response reports the outcome and durable IDs for every submitted record.

Parameters:
- `id` (path, required): string / uuid - Migration ID

Request body (required):
- `application/json`: SerenMemoryImportRecordsRequest

Responses:
- `200` Batch outcome (application/json: SerenMemoryDataResponse_ImportRecordsResponse)
- `400` Invalid request (application/json: SerenMemoryErrorBody)
- `401` Authentication required (application/json: SerenMemoryErrorBody)
- `404` Migration not found (application/json: SerenMemoryErrorBody)
- `409` Migration state or stable record identity conflict (application/json: SerenMemoryErrorBody)

### POST /publishers/seren-memory/migrations/{id}/rollback

Operation ID: `seren_memory_rollback_migration`
Operation page: `/api/operations/seren_memory_rollback_migration`
Remove every record created by a migration run or its series

Selection is strictly by stored migration provenance; hook, MCP, manual, and unrelated import records can never be selected.

Parameters:
- `id` (path, required): string / uuid - Migration ID

Request body (required):
- `application/json`: SerenMemoryRollbackMigrationRequest

Responses:
- `200` Rollback result (application/json: SerenMemoryDataResponse_RollbackMigrationResponse)
- `401` Authentication required (application/json: SerenMemoryErrorBody)
- `404` Migration not found (application/json: SerenMemoryErrorBody)
- `409` Rollback is already in progress (application/json: SerenMemoryErrorBody)

### PUT /publishers/seren-memory/migrations/{id}/state

Operation ID: `seren_memory_set_migration_state`
Operation page: `/api/operations/seren_memory_set_migration_state`
Transition a migration lifecycle state

Parameters:
- `id` (path, required): string / uuid - Migration ID

Request body (required):
- `application/json`: SerenMemorySetMigrationStateRequest

Responses:
- `200` Transition result (application/json: SerenMemoryDataResponse_MemoryMigration)
- `401` Authentication required (application/json: SerenMemoryErrorBody)
- `404` Migration not found (application/json: SerenMemoryErrorBody)
- `409` Invalid or concurrent state transition (application/json: SerenMemoryErrorBody)

### POST /publishers/seren-memory/process_conversation

Operation ID: `seren_memory_process_conversation`
Operation page: `/api/operations/seren_memory_process_conversation`
Extract private memories from a conversation

Request body (required):
- `application/json`: SerenMemoryProcessConversationParams

Responses:
- `200` Extracted memory candidates (application/json: SerenMemoryDataResponse_ExtractionResult)
- `400` Invalid request (application/json: SerenMemoryErrorBody)
- `401` Authentication required (application/json: SerenMemoryErrorBody)

### POST /publishers/seren-memory/recall

Operation ID: `seren_memory_recall`
Operation page: `/api/operations/seren_memory_recall`
Recall relevant private memories

Request body (required):
- `application/json`: SerenMemoryRecallParams

Responses:
- `200` Relevant memories (application/json: SerenMemoryDataResponse_RecallResponse)
- `400` Invalid request (application/json: SerenMemoryErrorBody)
- `401` Authentication required (application/json: SerenMemoryErrorBody)

### POST /publishers/seren-memory/remember

Operation ID: `seren_memory_remember`
Operation page: `/api/operations/seren_memory_remember`
Remember durable private context

Request body (required):
- `application/json`: SerenMemoryRememberParams

Responses:
- `200` Memory operation result (application/json: SerenMemoryDataResponse_RememberOutput)
- `400` Invalid request (application/json: SerenMemoryErrorBody)
- `401` Authentication required (application/json: SerenMemoryErrorBody)

### GET /publishers/seren-memory/sync/status

Operation ID: `seren_memory_sync_status`
Operation page: `/api/operations/seren_memory_sync_status`
Get memory synchronization status

Responses:
- `200` Synchronization status (application/json: SerenMemoryDataResponse_SyncStatus)
- `401` Authentication required (application/json: SerenMemoryErrorBody)

### POST /publishers/seren-memory/workspaces/merge

Operation ID: `seren_memory_execute_workspace_merge`
Operation page: `/api/operations/seren_memory_execute_workspace_merge`
Execute a reviewed workspace merge

Rechecks the state-bound preview under workspace locks, rewrites source envelopes to the canonical target, creates a durable alias for future captures, and records an immutable audit row. Retrying the same accepted plan is idempotent.

Request body (required):
- `application/json`: SerenMemoryExecuteWorkspaceMergeRequest

Responses:
- `200` Completed workspace merge (application/json: SerenMemoryDataResponse_WorkspaceMergeResult)
- `400` Invalid workspace keys or plan hash (application/json: SerenMemoryErrorBody)
- `401` Authentication required (application/json: SerenMemoryErrorBody)
- `409` Preview is stale or workspace alias conflicts (application/json: SerenMemoryErrorBody)

### POST /publishers/seren-memory/workspaces/merge/preview

Operation ID: `seren_memory_preview_workspace_merge`
Operation page: `/api/operations/seren_memory_preview_workspace_merge`
Preview a controlled workspace merge

Returns content-free source counts, shared external-session collisions, dependent aliases, and a state-bound plan hash. No records are changed.

Request body (required):
- `application/json`: SerenMemoryPreviewWorkspaceMergeRequest

Responses:
- `200` Workspace merge preview (application/json: SerenMemoryDataResponse_WorkspaceMergePreview)
- `400` Invalid workspace keys (application/json: SerenMemoryErrorBody)
- `401` Authentication required (application/json: SerenMemoryErrorBody)
- `409` Source workspace is already an alias (application/json: SerenMemoryErrorBody)

## Meta

### GET /publishers/seren-memory/openapi.json

Operation ID: `seren_memory_serve_openapi`
Operation page: `/api/operations/seren_memory_serve_openapi`
Get the Seren Memory OpenAPI document

Responses:
- `200` OpenAPI document (application/json: object)

### GET /publishers/seren-memory/skill.md

Operation ID: `seren_memory_skill_md`
Operation page: `/api/operations/seren_memory_skill_md`
Get the Seren Memory skill document

Responses:
- `200` Publisher skill definition (text/markdown: unspecified)

### GET /publishers/seren-passwords/openapi.json

Operation ID: `openapi_get`
Operation page: `/api/operations/openapi_get`
Return the live OpenAPI 3.1 document for this service. Body is the raw
document (not wrapped in `DataResponse`) so it can be fed directly into
off-the-shelf code generators that expect a vanilla OpenAPI payload.

Responses:
- `200` OpenAPI 3.1 document for this service (application/json: object)

### GET /publishers/seren-storage

Operation ID: `seren_storage_root`
Operation page: `/api/operations/seren_storage_root`

Responses:
- `200` Service metadata (application/json: SerenStorageDataResponse_ServiceInfo)

### GET /publishers/seren-storage/openapi.json

Operation ID: `seren_storage_serve_openapi`
Operation page: `/api/operations/seren_storage_serve_openapi`

Responses:
- `200` OpenAPI document (application/json: object)

## notes

### GET /publishers/seren-notes/notes

Operation ID: `list_notes`
Operation page: `/api/operations/list_notes`
List notes with filters

Parameters:
- `parent_id` (query): string | null / uuid
- `tag` (query): string | null
- `include_archived` (query): boolean | null
- `limit` (query): integer | null / int64
- `offset` (query): integer | null / int64

Responses:
- `200` List of notes (application/json: DataResponse_Vec_NoteSummary)
- `401` Unauthorized

### POST /publishers/seren-notes/notes

Operation ID: `create_note`
Operation page: `/api/operations/create_note`
Create a new note

Request body (required):
- `application/json`: CreateNoteRequest

Responses:
- `201` Note created (application/json: DataResponse_NoteResponse)
- `400` Invalid request
- `401` Unauthorized

### DELETE /publishers/seren-notes/notes/{note_id}

Operation ID: `delete_note`
Operation page: `/api/operations/delete_note`
Delete a note

Parameters:
- `note_id` (path, required): string / uuid - Note ID

Responses:
- `204` Note deleted
- `401` Unauthorized
- `404` Note not found

### GET /publishers/seren-notes/notes/{note_id}

Operation ID: `get_note`
Operation page: `/api/operations/get_note`
Get a specific note

Parameters:
- `note_id` (path, required): string / uuid - Note ID
- `format` (query): NoteFormat

Responses:
- `200` Note found (application/json: DataResponse_NoteResponse)
- `401` Unauthorized
- `404` Note not found

### PATCH /publishers/seren-notes/notes/{note_id}

Operation ID: `update_note`
Operation page: `/api/operations/update_note`
Update a note

Parameters:
- `note_id` (path, required): string / uuid - Note ID

Request body (required):
- `application/json`: UpdateNoteRequest

Responses:
- `200` Note updated (application/json: DataResponse_NoteResponse)
- `401` Unauthorized
- `404` Note not found
- `409` Version conflict

### POST /publishers/seren-notes/notes/{note_id}/append

Operation ID: `append_to_note`
Operation page: `/api/operations/append_to_note`
Append content to a note

Parameters:
- `note_id` (path, required): string / uuid - Note ID

Request body (required):
- `application/json`: AppendToNoteRequest

Responses:
- `200` Content appended (application/json: DataResponse_NoteResponse)
- `401` Unauthorized
- `404` Note not found

### GET /publishers/seren-notes/notes/search

Operation ID: `search_notes`
Operation page: `/api/operations/search_notes`
Full-text search notes

Parameters:
- `query` (query, required): string
- `include_archived` (query): boolean | null
- `limit` (query): integer | null / int64
- `offset` (query): integer | null / int64

Responses:
- `200` Search results (application/json: DataResponse_Vec_NoteSummary)
- `400` Invalid request
- `401` Unauthorized

## notifications

### POST /notifications/{notification_id}/read

Operation ID: `mark_notification_read`
Operation page: `/api/operations/mark_notification_read`

Parameters:
- `notification_id` (path, required): string / uuid - Notification ID

Responses:
- `200` Notification marked read (application/json: DataResponse_NotificationReadResponse)
- `401` Unauthorized
- `404` Notification not found

## OAuth

### GET /oauth/{provider}/authorize

Operation ID: `initiate_oauth`
Operation page: `/api/operations/initiate_oauth`
Initiate OAuth authorization flow

Redirects the user to the OAuth provider's consent screen.
After authorization, the provider will redirect back to the callback URL.

Parameters:
- `provider` (path, required): string - OAuth provider slug (e.g., 'neon')
- `redirect_uri` (query, required): string - Where to redirect after OAuth completes

Responses:
- `302` Redirect to OAuth provider
- `400` Invalid or missing redirect URI
- `404` Provider not found
- `503` OAuth account access is unavailable

### GET /oauth/{provider}/callback

Operation ID: `oauth_callback`
Operation page: `/api/operations/oauth_callback`
Handle OAuth callback

Called by the OAuth provider after the user authorizes.
Exchanges the authorization code for tokens and stores them.

Parameters:
- `provider` (path, required): string - OAuth provider slug
- `code` (query, required): string - Authorization code from provider
- `state` (query, required): string - State parameter for CSRF verification

Responses:
- `302` Redirect to frontend with success/error
- `400` Invalid callback parameters

### GET /oauth/connections

Operation ID: `list_connections`
Operation page: `/api/operations/list_connections`
List user's OAuth connections

Returns all OAuth providers the user has connected to.

Responses:
- `200` List of user's OAuth connections (application/json: ConnectionsResponse)

### DELETE /oauth/connections/{connection_id}

Operation ID: `revoke_connection_by_id`
Operation page: `/api/operations/revoke_connection_by_id`
Revoke an OAuth connection by connection ID.

Parameters:
- `connection_id` (path, required): string / uuid - OAuth connection UUID to disconnect

Responses:
- `200` Connection revoked successfully (application/json: RevokeResponse)
- `404` Connection not found

### PUT /oauth/connections/{connection_id}/default

Operation ID: `set_default_connection`
Operation page: `/api/operations/set_default_connection`
Set the default OAuth connection

Marks one of the authenticated user's OAuth connections as the default for its provider.

Parameters:
- `connection_id` (path, required): string / uuid - OAuth connection UUID

Responses:
- `200` Default connection updated (application/json: SetDefaultConnectionResponse)
- `404` Connection not found

### GET /oauth/providers

Operation ID: `list_providers`
Operation page: `/api/operations/list_providers`
List available OAuth providers

Returns all active OAuth providers that users can connect to,
including global providers and providers from organizations the user belongs to.

Responses:
- `200` List of available OAuth providers (application/json: ProvidersResponse)

### GET /oauth/providers/{provider_id}/authorize

Operation ID: `initiate_oauth_by_id`
Operation page: `/api/operations/initiate_oauth_by_id`
Initiate OAuth authorization flow by provider ID (supports org-scoped providers)

Parameters:
- `provider_id` (path, required): string / uuid - OAuth provider UUID
- `redirect_uri` (query, required): string - Where to redirect after OAuth completes

Responses:
- `302` Redirect to OAuth provider
- `400` Invalid or missing redirect URI
- `404` Provider not found
- `503` OAuth account access is unavailable

### GET /oauth/providers/{provider_id}/callback

Operation ID: `oauth_callback_by_id`
Operation page: `/api/operations/oauth_callback_by_id`
Handle OAuth callback by provider ID (supports org-scoped providers)

Parameters:
- `provider_id` (path, required): string / uuid - OAuth provider UUID
- `code` (query, required): string - Authorization code from provider
- `state` (query, required): string - State parameter for CSRF verification

Responses:
- `302` Redirect to frontend with success/error
- `400` Invalid callback parameters
- `404` Provider not found

## oauth-providers

### GET /organizations/{organization_id}/oauth/providers

Operation ID: `list_org_oauth_providers`
Operation page: `/api/operations/list_org_oauth_providers`

List all OAuth providers for an organization.

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization

Responses:
- `200` List of OAuth providers (application/json: DataResponse_Vec_OAuthProviderResponse)
- `401` Unauthorized
- `403` Forbidden - not a member of the organization
- `500` Internal server error

### POST /organizations/{organization_id}/oauth/providers

Operation ID: `create_org_oauth_provider`
Operation page: `/api/operations/create_org_oauth_provider`

Create a new OAuth provider for an organization.

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization

Request body (required):
- `application/json`: CreateOAuthProviderRequest

Responses:
- `201` OAuth provider created (application/json: DataResponse_OAuthProviderResponse)
- `400` Invalid request
- `401` Unauthorized
- `403` Forbidden - not a member of the organization
- `409` Conflict - provider with this slug already exists
- `500` Internal server error

### DELETE /organizations/{organization_id}/oauth/providers/{provider_id}

Operation ID: `delete_org_oauth_provider`
Operation page: `/api/operations/delete_org_oauth_provider`

Delete an OAuth provider for an organization.

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `provider_id` (path, required): string / uuid - OAuth provider ID

Responses:
- `204` OAuth provider deleted
- `401` Unauthorized
- `403` Forbidden - not a member of the organization
- `404` Provider not found
- `500` Internal server error

### GET /organizations/{organization_id}/oauth/providers/{provider_id}

Operation ID: `get_org_oauth_provider`
Operation page: `/api/operations/get_org_oauth_provider`

Get a specific OAuth provider for an organization.

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `provider_id` (path, required): string / uuid - OAuth provider ID

Responses:
- `200` OAuth provider details (application/json: DataResponse_OAuthProviderResponse)
- `401` Unauthorized
- `403` Forbidden - not a member of the organization
- `404` Provider not found
- `500` Internal server error

### PATCH /organizations/{organization_id}/oauth/providers/{provider_id}

Operation ID: `update_org_oauth_provider`
Operation page: `/api/operations/update_org_oauth_provider`

Update an OAuth provider for an organization.

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `provider_id` (path, required): string / uuid - OAuth provider ID

Request body (required):
- `application/json`: UpdateOAuthProviderRequest

Responses:
- `200` OAuth provider updated (application/json: DataResponse_OAuthProviderResponse)
- `400` Invalid request
- `401` Unauthorized
- `403` Forbidden - not a member of the organization
- `404` Provider not found
- `409` Conflict - provider with this slug already exists
- `500` Internal server error

## Objects

### GET /publishers/seren-storage/buckets

Operation ID: `seren_storage_list_buckets`
Operation page: `/api/operations/seren_storage_list_buckets`

Responses:
- `200` Storage buckets retrieved (application/json: SerenStorageDataResponse_Vec_ObjectStorageBucket)
- `401` Authentication required (application/json: SerenStorageErrorBody)

### PUT /publishers/seren-storage/buckets/{bucket_slug}/lifecycle

Operation ID: `seren_storage_put_bucket_lifecycle`
Operation page: `/api/operations/seren_storage_put_bucket_lifecycle`

Parameters:
- `bucket_slug` (path, required): string - Storage bucket slug

Request body (required):
- `application/json`: SerenStoragePutObjectStorageBucketLifecycleRequest

Responses:
- `200` Bucket lifecycle updated (application/json: SerenStorageDataResponse_ObjectStorageBucket)
- `403` Organization management permission required (application/json: SerenStorageErrorBody)

### GET /publishers/seren-storage/buckets/{bucket_slug}/objects

Operation ID: `seren_storage_list_objects`
Operation page: `/api/operations/seren_storage_list_objects`

Parameters:
- `bucket_slug` (path, required): string - Storage bucket slug
- `prefix` (query): string | null
- `delimiter` (query): string | null
- `view` (query): string
- `cursor` (query): string | null
- `limit` (query): integer / int64

Responses:
- `200` Storage objects and directory prefixes retrieved (application/json: SerenStorageDataResponse_ObjectStorageObjectPage)

### DELETE /publishers/seren-storage/buckets/{bucket_slug}/objects/{object_id}

Operation ID: `seren_storage_delete_object`
Operation page: `/api/operations/seren_storage_delete_object`

Parameters:
- `bucket_slug` (path, required): string - Storage bucket slug
- `object_id` (path, required): string / uuid - Storage object ID

Responses:
- `200` Storage object moved to trash (application/json: SerenStorageDataResponse_ObjectStorageObject)

### POST /publishers/seren-storage/buckets/{bucket_slug}/objects/{object_id}/confirm-upload

Operation ID: `seren_storage_confirm_upload`
Operation page: `/api/operations/seren_storage_confirm_upload`

Parameters:
- `bucket_slug` (path, required): string - Storage bucket slug
- `object_id` (path, required): string / uuid - Storage object ID

Request body (required):
- `application/json`: SerenStorageConfirmObjectStorageUploadRequest

Responses:
- `200` Upload confirmed (application/json: SerenStorageDataResponse_ObjectStorageObject)

### POST /publishers/seren-storage/buckets/{bucket_slug}/objects/{object_id}/copy

Operation ID: `seren_storage_copy_object`
Operation page: `/api/operations/seren_storage_copy_object`

Parameters:
- `bucket_slug` (path, required): string - Source storage bucket slug
- `object_id` (path, required): string / uuid - Source storage object ID

Request body (required):
- `application/json`: SerenStorageCopyObjectStorageObjectRequest

Responses:
- `201` Storage object copied (application/json: SerenStorageDataResponse_ObjectStorageObject)
- `409` Destination key already exists (application/json: SerenStorageErrorBody)

### GET /publishers/seren-storage/buckets/{bucket_slug}/objects/{object_id}/download

Operation ID: `seren_storage_download_object_by_id`
Operation page: `/api/operations/seren_storage_download_object_by_id`

Parameters:
- `bucket_slug` (path, required): string - Storage bucket slug
- `object_id` (path, required): string / uuid - Storage object ID

Responses:
- `200` Download URL created (application/json: SerenStorageDataResponse_ObjectStorageDownload)

### POST /publishers/seren-storage/buckets/{bucket_slug}/objects/{object_id}/move

Operation ID: `seren_storage_move_object`
Operation page: `/api/operations/seren_storage_move_object`

Parameters:
- `bucket_slug` (path, required): string - Source storage bucket slug
- `object_id` (path, required): string / uuid - Source storage object ID

Request body (required):
- `application/json`: SerenStorageMoveObjectStorageObjectRequest

Responses:
- `200` Storage object moved (application/json: SerenStorageDataResponse_ObjectStorageObject)
- `409` Destination key already exists (application/json: SerenStorageErrorBody)

### DELETE /publishers/seren-storage/buckets/{bucket_slug}/objects/{object_id}/multipart-upload

Operation ID: `seren_storage_abort_multipart_upload`
Operation page: `/api/operations/seren_storage_abort_multipart_upload`

Parameters:
- `bucket_slug` (path, required): string - Storage bucket slug
- `object_id` (path, required): string / uuid - Storage object ID

Responses:
- `200` Multipart upload aborted (application/json: SerenStorageDataResponse_ObjectStorageObject)

### POST /publishers/seren-storage/buckets/{bucket_slug}/objects/{object_id}/multipart-upload/complete

Operation ID: `seren_storage_complete_multipart_upload`
Operation page: `/api/operations/seren_storage_complete_multipart_upload`

Parameters:
- `bucket_slug` (path, required): string - Storage bucket slug
- `object_id` (path, required): string / uuid - Storage object ID

Responses:
- `200` Multipart upload completed (application/json: SerenStorageDataResponse_ObjectStorageObject)

### POST /publishers/seren-storage/buckets/{bucket_slug}/objects/{object_id}/multipart-upload/parts/{part_number}

Operation ID: `seren_storage_create_multipart_part_upload`
Operation page: `/api/operations/seren_storage_create_multipart_part_upload`

Parameters:
- `bucket_slug` (path, required): string - Storage bucket slug
- `object_id` (path, required): string / uuid - Storage object ID
- `part_number` (path, required): integer / int32 - Multipart part number

Request body (required):
- `application/json`: SerenStorageCreateObjectStorageMultipartPartRequest

Responses:
- `201` Multipart part upload URL created (application/json: SerenStorageDataResponse_ObjectStorageMultipartPartUpload)

### POST /publishers/seren-storage/buckets/{bucket_slug}/objects/{object_id}/restore

Operation ID: `seren_storage_restore_object`
Operation page: `/api/operations/seren_storage_restore_object`

Parameters:
- `bucket_slug` (path, required): string - Storage bucket slug
- `object_id` (path, required): string / uuid - Storage object ID

Responses:
- `200` Storage object restored (application/json: SerenStorageDataResponse_ObjectStorageObject)
- `409` Object key is already in use (application/json: SerenStorageErrorBody)

### GET /publishers/seren-storage/buckets/{bucket_slug}/objects/by-key/download

Operation ID: `seren_storage_download_object`
Operation page: `/api/operations/seren_storage_download_object`

Parameters:
- `bucket_slug` (path, required): string - Storage bucket slug
- `object_key` (query, required): string

Responses:
- `200` Download URL created (application/json: SerenStorageDataResponse_ObjectStorageDownload)

### POST /publishers/seren-storage/buckets/{bucket_slug}/objects/multipart-uploads

Operation ID: `seren_storage_create_multipart_upload`
Operation page: `/api/operations/seren_storage_create_multipart_upload`

Parameters:
- `bucket_slug` (path, required): string - Storage bucket slug

Request body (required):
- `application/json`: SerenStorageCreateObjectStorageMultipartUploadRequest

Responses:
- `201` Multipart upload initiated (application/json: SerenStorageDataResponse_ObjectStorageMultipartUpload)
- `409` Object key already exists (application/json: SerenStorageErrorBody)

### POST /publishers/seren-storage/buckets/{bucket_slug}/objects/uploads

Operation ID: `seren_storage_create_upload`
Operation page: `/api/operations/seren_storage_create_upload`

Parameters:
- `bucket_slug` (path, required): string - Storage bucket slug

Request body (required):
- `application/json`: SerenStorageCreateObjectStorageUploadRequest

Responses:
- `201` Upload intent created (application/json: SerenStorageDataResponse_ObjectStorageUpload)
- `409` Object key already exists (application/json: SerenStorageErrorBody)

### GET /publishers/seren-storage/usage

Operation ID: `seren_storage_usage`
Operation page: `/api/operations/seren_storage_usage`

Responses:
- `200` Organization storage usage retrieved (application/json: SerenStorageDataResponse_ObjectStorageUsage)

## Organizations

### GET /organizations

Operation ID: `list_organizations`
Operation page: `/api/operations/list_organizations`
List all organizations for the authenticated user

Responses:
- `200` List of organizations (application/json: DataResponse_Vec_Organization)
- `401` Unauthorized

### GET /organizations/{organization_id}/agent-credential-secrets

Operation ID: `list_agent_credential_secrets`
Operation page: `/api/operations/list_agent_credential_secrets`

Parameters:
- `organization_id` (path, required): string
- `scope` (query): null | AgentCredentialSecretScope

Responses:
- `200` Managed-agent credential secrets retrieved (application/json: DataResponse_Vec_AgentCredentialSecret)
- `403` Only organization owners or admins can list credential secrets

### POST /organizations/{organization_id}/agent-credential-secrets

Operation ID: `upsert_agent_credential_secret`
Operation page: `/api/operations/upsert_agent_credential_secret`

Parameters:
- `organization_id` (path, required): string

Request body (required):
- `application/json`: UpsertAgentCredentialSecretRequest

Responses:
- `200` Managed-agent credential secret upserted (application/json: DataResponse_AgentCredentialSecret)
- `400` Invalid secret name or value
- `403` Only organization owners or admins can manage credential secrets

### DELETE /organizations/{organization_id}/agent-credential-secrets/{secret_id}

Operation ID: `delete_agent_credential_secret`
Operation page: `/api/operations/delete_agent_credential_secret`

Parameters:
- `organization_id` (path, required): string
- `secret_id` (path, required): string / uuid

Responses:
- `200` Managed-agent credential secret deleted (application/json: DataResponse_AgentCredentialSecretDeleted)
- `403` Only organization owners or admins can manage credential secrets
- `404` Credential secret not found

### GET /organizations/{organization_id}/custom-skills

Operation ID: `list_custom_skills`
Operation page: `/api/operations/list_custom_skills`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID
- `q` (query): string | null
- `include_archived` (query): boolean

Responses:
- `200` Custom skills retrieved (application/json: DataResponse_Vec_OrganizationCustomSkill)

### POST /organizations/{organization_id}/custom-skills

Operation ID: `create_custom_skill`
Operation page: `/api/operations/create_custom_skill`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID

Request body (required):
- `application/json`: CreateOrganizationCustomSkillRequest

Responses:
- `200` Custom skill created (application/json: DataResponse_OrganizationCustomSkill)

### GET /organizations/{organization_id}/custom-skills/{skill_id}

Operation ID: `get_custom_skill`
Operation page: `/api/operations/get_custom_skill`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID
- `skill_id` (path, required): string / uuid - Custom skill ID

Responses:
- `200` Custom skill retrieved (application/json: DataResponse_OrganizationCustomSkill)
- `404` Custom skill not found

### PATCH /organizations/{organization_id}/custom-skills/{skill_id}

Operation ID: `update_custom_skill`
Operation page: `/api/operations/update_custom_skill`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID
- `skill_id` (path, required): string / uuid - Custom skill ID

Request body (required):
- `application/json`: UpdateOrganizationCustomSkillRequest

Responses:
- `200` Custom skill updated (application/json: DataResponse_OrganizationCustomSkill)
- `404` Custom skill not found

### GET /organizations/{organization_id}/custom-skills/{skill_id}/revisions

Operation ID: `list_custom_skill_revisions`
Operation page: `/api/operations/list_custom_skill_revisions`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID
- `skill_id` (path, required): string / uuid - Custom skill ID

Responses:
- `200` Custom skill revisions retrieved (application/json: DataResponse_Vec_OrganizationCustomSkillRevisionSummary)

### POST /organizations/{organization_id}/custom-skills/{skill_id}/revisions

Operation ID: `create_custom_skill_revision`
Operation page: `/api/operations/create_custom_skill_revision`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID
- `skill_id` (path, required): string / uuid - Custom skill ID

Request body (required):
- `application/json`: CreateOrganizationCustomSkillRevisionRequest

Responses:
- `200` Custom skill revision created (application/json: DataResponse_OrganizationCustomSkillRevision)

### GET /organizations/{organization_id}/custom-skills/{skill_id}/revisions/{revision_id}

Operation ID: `get_custom_skill_revision`
Operation page: `/api/operations/get_custom_skill_revision`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID
- `skill_id` (path, required): string / uuid - Custom skill ID
- `revision_id` (path, required): string / uuid - Revision ID

Responses:
- `200` Custom skill revision retrieved (application/json: DataResponse_OrganizationCustomSkillRevision)

### GET /organizations/{organization_id}/custom-skills/{skill_id}/revisions/{revision_id}/bundle

Operation ID: `download_custom_skill_revision_bundle`
Operation page: `/api/operations/download_custom_skill_revision_bundle`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID
- `skill_id` (path, required): string / uuid - Custom skill ID
- `revision_id` (path, required): string / uuid - Revision ID

Responses:
- `200` Revision bundle download (application/gzip: unspecified)

### GET /organizations/{organization_id}/custom-skills/{skill_id}/revisions/{revision_id}/file

Operation ID: `get_custom_skill_revision_file`
Operation page: `/api/operations/get_custom_skill_revision_file`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID
- `skill_id` (path, required): string / uuid - Custom skill ID
- `revision_id` (path, required): string / uuid - Revision ID
- `path` (query, required): string

Responses:
- `200` Revision file retrieved (application/json: DataResponse_OrganizationCustomSkillFileContent)

### POST /organizations/{organization_id}/custom-skills/{skill_id}/revisions/{revision_id}/publish

Operation ID: `publish_custom_skill_revision`
Operation page: `/api/operations/publish_custom_skill_revision`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID
- `skill_id` (path, required): string / uuid - Custom skill ID
- `revision_id` (path, required): string / uuid - Revision ID

Responses:
- `200` Revision published (application/json: DataResponse_OrganizationCustomSkill)

### GET /organizations/{organization_id}/employee-collaboration-policy

Operation ID: `get_employee_collaboration_policy`
Operation page: `/api/operations/get_employee_collaboration_policy`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for the authenticated user's default organization

Responses:
- `200` Organization employee collaboration policy (application/json: DataResponse_OrganizationEmployeeCollaborationPolicy)
- `403` User is not a member of the organization

### PUT /organizations/{organization_id}/employee-collaboration-policy

Operation ID: `update_employee_collaboration_policy`
Operation page: `/api/operations/update_employee_collaboration_policy`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for the authenticated user's default organization

Request body (required):
- `application/json`: UpdateOrganizationEmployeeCollaborationPolicyRequest

Responses:
- `200` Updated organization employee collaboration policy (application/json: DataResponse_OrganizationEmployeeCollaborationPolicy)
- `400` Invalid policy or no current employee assignment
- `403` Only a signed-in organization owner or administrator can update the policy
- `409` Policy revision is stale

### GET /organizations/{organization_id}/employee-collaboration/assignments

Operation ID: `list_employee_collaboration_assignments`
Operation page: `/api/operations/list_employee_collaboration_assignments`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for the authenticated user's default organization
- `include_revoked` (query): boolean

Responses:
- `200` Managed agent collaboration assignments, optionally including revoked assignments (application/json: DataResponse_Vec_OrganizationEmployeeCollaborationAssignment)
- `403` Only a signed-in organization owner or administrator can list assignments

### DELETE /organizations/{organization_id}/employee-collaboration/assignments/{deployment_id}

Operation ID: `revoke_employee_collaboration_assignment`
Operation page: `/api/operations/revoke_employee_collaboration_assignment`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for the authenticated user's default organization
- `deployment_id` (path, required): string / uuid - Managed agent deployment ID
- `expected_assignment_generation` (query, required): integer / int64

Responses:
- `200` Whether an active assignment was revoked (application/json: DataResponse_bool)
- `400` Expected assignment generation is invalid
- `403` Only a signed-in organization owner or administrator can manage assignments
- `409` Assignment generation is stale

### PUT /organizations/{organization_id}/employee-collaboration/assignments/{deployment_id}

Operation ID: `upsert_employee_collaboration_assignment`
Operation page: `/api/operations/upsert_employee_collaboration_assignment`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for the authenticated user's default organization
- `deployment_id` (path, required): string / uuid - Managed agent deployment ID

Request body (required):
- `application/json`: UpsertOrganizationEmployeeCollaborationAssignmentRequest

Responses:
- `200` Created or updated employee collaboration assignment (application/json: DataResponse_OrganizationEmployeeCollaborationAssignment)
- `400` Deployment is not a managed agent with a stable agent identity
- `403` Only a signed-in organization owner or administrator can manage assignments
- `409` Assignment generation is stale or the assignment requires explicit reactivation

### POST /organizations/{organization_id}/employee-collaboration/assignments/{deployment_id}/reactivate

Operation ID: `reactivate_employee_collaboration_assignment`
Operation page: `/api/operations/reactivate_employee_collaboration_assignment`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for the authenticated user's default organization
- `deployment_id` (path, required): string / uuid - Managed agent deployment ID

Request body (required):
- `application/json`: UpsertOrganizationEmployeeCollaborationAssignmentRequest

Responses:
- `200` Reactivated employee collaboration assignment (application/json: DataResponse_OrganizationEmployeeCollaborationAssignment)
- `400` Expected assignment generation is missing or invalid
- `403` Only a signed-in organization owner or administrator can manage assignments
- `409` Assignment is active or its generation is stale

### GET /organizations/{organization_id}/invites

Operation ID: `list_invites`
Operation page: `/api/operations/list_invites`
List pending and historical organization invites.

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization

Responses:
- `200` Organization invites retrieved (application/json: DataResponse_Vec_OrganizationInvite)
- `403` User is not allowed to view invites
- `500` Internal server error

### POST /organizations/{organization_id}/invites

Operation ID: `create_invite`
Operation page: `/api/operations/create_invite`
Create a new organization invite and send an email via the configured mailer.

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization

Request body (required):
- `application/json`: CreateOrganizationInviteRequest

Responses:
- `201` Invite created and email sent (application/json: DataResponse_OrganizationInvite)
- `400` Invalid request
- `403` User is not allowed to create invites
- `500` Internal server error

### GET /organizations/{organization_id}/members

Operation ID: `list_members`
Operation page: `/api/operations/list_members`
List organization members with basic user details.

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization

Responses:
- `200` Organization members retrieved (application/json: DataResponse_Vec_OrganizationMemberWithUser)
- `403` User is not a member of the organization
- `500` Internal server error

### GET /organizations/{organization_id}/memory-capture-policy

Operation ID: `get_memory_capture_policy`
Operation page: `/api/operations/get_memory_capture_policy`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for the authenticated user's default organization

Responses:
- `200` Organization automatic memory-capture policy (application/json: DataResponse_OrganizationMemoryCapturePolicy)
- `403` User is not a member of the organization

### PUT /organizations/{organization_id}/memory-capture-policy

Operation ID: `update_memory_capture_policy`
Operation page: `/api/operations/update_memory_capture_policy`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for the authenticated user's default organization

Request body (required):
- `application/json`: UpdateOrganizationMemoryCapturePolicyRequest

Responses:
- `200` Updated organization automatic memory-capture policy (application/json: DataResponse_OrganizationMemoryCapturePolicy)
- `400` Invalid policy
- `403` User is not allowed to update the organization

### GET /organizations/{organization_id}/otp-policy

Operation ID: `get_organization_otp_policy`
Operation page: `/api/operations/get_organization_otp_policy`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization

Responses:
- `200` Organization OTP policy (application/json: DataResponse_OrganizationOtpPolicy)
- `403` User is not allowed to view the organization OTP policy
- `500` Internal server error

### PUT /organizations/{organization_id}/otp-policy

Operation ID: `update_organization_otp_policy`
Operation page: `/api/operations/update_organization_otp_policy`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization

Request body (required):
- `application/json`: UpdateOrganizationOtpPolicyRequest

Responses:
- `200` Updated organization OTP policy (application/json: DataResponse_OrganizationOtpPolicy)
- `400` Invalid request
- `403` User is not allowed to update the organization OTP policy
- `500` Internal server error

### POST /organizations/{organization_id}/otp/enrollment

Operation ID: `begin_organization_otp_enrollment`
Operation page: `/api/operations/begin_organization_otp_enrollment`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization

Responses:
- `200` Organization OTP enrollment challenge (application/json: DataResponse_OrganizationOtpEnrollmentChallenge)
- `403` User is not a member of the organization
- `500` Internal server error

### POST /organizations/{organization_id}/otp/enrollment/confirm

Operation ID: `confirm_organization_otp_enrollment`
Operation page: `/api/operations/confirm_organization_otp_enrollment`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization

Request body (required):
- `application/json`: OrganizationOtpCodeRequest

Responses:
- `200` Organization OTP enrollment confirmed (application/json: DataResponse_OrganizationOtpStatus)
- `400` Invalid request
- `403` User is not a member of the organization
- `500` Internal server error

### POST /organizations/{organization_id}/otp/members/{user_id}/reset

Operation ID: `reset_organization_member_otp`
Operation page: `/api/operations/reset_organization_member_otp`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `user_id` (path, required): string / uuid - Target user ID

Responses:
- `200` Organization OTP reset completed (application/json: DataResponse_OrganizationOtpResetResponse)
- `403` User is not allowed to reset organization OTP
- `500` Internal server error

### GET /organizations/{organization_id}/otp/status

Operation ID: `get_organization_otp_status`
Operation page: `/api/operations/get_organization_otp_status`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `scope` (query, required): OrganizationOtpScope

Responses:
- `200` Organization OTP status for the current user and scope (application/json: DataResponse_OrganizationOtpStatus)
- `403` User is not a member of the organization
- `500` Internal server error

### POST /organizations/{organization_id}/otp/verify

Operation ID: `verify_organization_otp_scope`
Operation page: `/api/operations/verify_organization_otp_scope`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization

Request body (required):
- `application/json`: OrganizationOtpVerifyRequest

Responses:
- `200` Organization OTP scope verified (application/json: DataResponse_OrganizationOtpStatus)
- `400` Invalid request
- `403` OTP required or organization membership missing
- `500` Internal server error

### GET /organizations/{organization_id}/private-models-policy

Operation ID: `get_private_models_policy`
Operation page: `/api/operations/get_private_models_policy`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization

Responses:
- `200` Organization private models policy (application/json: DataResponse_OrganizationPrivateModelsPolicy)
- `403` User is not a member of the organization
- `500` Internal server error

### PUT /organizations/{organization_id}/private-models-policy

Operation ID: `update_private_models_policy`
Operation page: `/api/operations/update_private_models_policy`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization

Request body (required):
- `application/json`: UpdateOrganizationPrivateModelsPolicyRequest

Responses:
- `200` Updated organization private models policy (application/json: DataResponse_OrganizationPrivateModelsPolicy)
- `400` Invalid request
- `403` User is not allowed to update the organization
- `500` Internal server error

### GET /organizations/{organization_id}/publishers

Operation ID: `list_org_publishers`
Operation page: `/api/operations/list_org_publishers`
List publishers owned by an organization

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization

Responses:
- `200` Publishers retrieved successfully (application/json: DataResponse_Vec_PublisherResponse)
- `403` Not authorized
- `500` Internal server error

### POST /organizations/{organization_id}/publishers

Operation ID: `create_publisher`
Operation page: `/api/operations/create_publisher`
Create a new publisher

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization

Request body (required):
- `application/json`: CreatePublisherRequest

Responses:
- `201` Publisher created successfully (application/json: DataResponse_PublisherResponse)
- `400` Invalid request
- `403` Not authorized
- `409` Publisher slug already exists
- `500` Internal server error

### DELETE /organizations/{organization_id}/publishers/{publisher_id}

Operation ID: `delete_publisher`
Operation page: `/api/operations/delete_publisher`
Soft delete a publisher

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `publisher_id` (path, required): string / uuid - Publisher ID

Responses:
- `200` Publisher deleted successfully
- `403` Not authorized
- `404` Publisher not found
- `500` Internal server error

### GET /organizations/{organization_id}/publishers/{publisher_id}

Operation ID: `get_org_publisher`
Operation page: `/api/operations/get_org_publisher`
Get publisher details

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `publisher_id` (path, required): string / uuid - Publisher ID

Responses:
- `200` Publisher retrieved successfully (application/json: DataResponse_PublisherResponse)
- `403` Not authorized
- `404` Publisher not found
- `500` Internal server error

### PUT /organizations/{organization_id}/publishers/{publisher_id}

Operation ID: `update_publisher`
Operation page: `/api/operations/update_publisher`
Update a publisher

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `publisher_id` (path, required): string / uuid - Publisher ID

Request body (required):
- `application/json`: UpdatePublisherRequest

Responses:
- `200` Publisher updated successfully (application/json: DataResponse_PublisherResponse)
- `400` Invalid request
- `403` Not authorized
- `404` Publisher not found
- `500` Internal server error

### GET /organizations/{organization_id}/publishers/{publisher_id}/earnings

Operation ID: `get_org_publisher_earnings`
Operation page: `/api/operations/get_org_publisher_earnings`
List earnings for a publisher (per asset).

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `publisher_id` (path, required): string / uuid - Publisher ID

Responses:
- `200` Earnings retrieved successfully (application/json: DataResponse_Vec_PublisherEarningsResponse)
- `403` Not authorized
- `404` Publisher not found
- `500` Internal server error

### POST /organizations/{organization_id}/publishers/{publisher_id}/logo

Operation ID: `upload_publisher_logo`
Operation page: `/api/operations/upload_publisher_logo`
Upload a logo for a publisher

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `publisher_id` (path, required): string / uuid - Publisher ID

Request body (required):
- `application/json`: LogoUploadRequest

Responses:
- `200` Logo uploaded successfully (application/json: DataResponse_LogoUploadResponse)
- `400` Invalid image format or size
- `403` Not authorized
- `404` Publisher not found
- `500` Internal server error

### GET /organizations/{organization_id}/publishers/{publisher_id}/payouts

Operation ID: `list_org_publisher_payouts`
Operation page: `/api/operations/list_org_publisher_payouts`
List payout requests for a publisher.

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `publisher_id` (path, required): string / uuid - Publisher ID
- `limit` (query): integer | null / int64 - Maximum number of results (default: 50)
- `offset` (query): integer | null / int64 - Offset for pagination

Responses:
- `200` Payouts retrieved successfully (application/json: DataResponse_Vec_PublisherPayoutResponse)
- `403` Not authorized
- `404` Publisher not found
- `500` Internal server error

### POST /organizations/{organization_id}/publishers/{publisher_id}/payouts

Operation ID: `create_org_publisher_payout`
Operation page: `/api/operations/create_org_publisher_payout`
Request a payout for a publisher's earnings.

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `publisher_id` (path, required): string / uuid - Publisher ID

Request body (required):
- `application/json`: CreatePublisherPayoutRequest

Responses:
- `201` Payout request created (application/json: DataResponse_PublisherPayoutResponse)
- `400` Invalid request
- `403` Not authorized
- `404` Publisher not found
- `500` Internal server error

### PUT /organizations/{organization_id}/publishers/{publisher_id}/pricing

Operation ID: `update_publisher_pricing`
Operation page: `/api/operations/update_publisher_pricing`
Update publisher pricing config for a specific asset

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `publisher_id` (path, required): string / uuid - Publisher ID

Request body (required):
- `application/json`: UpdatePricingRequest

Responses:
- `200` Pricing updated successfully (application/json: DataResponse_PricingConfigResponse)
- `400` Invalid request
- `403` Not authorized
- `404` Publisher not found
- `500` Internal server error

## payments

### POST /billing/invoices/{id}/pay

Operation ID: `create_payment_intent`
Operation page: `/api/operations/create_payment_intent`
Create a payment intent for an invoice

Parameters:
- `id` (path, required): string / uuid - Invoice ID

Responses:
- `200` Payment intent created (application/json: DataResponse_PaymentIntentCreated)
- `400` Invoice not in payable state
- `404` Invoice not found
- `500` Internal server error

### GET /billing/invoices/{id}/payments

Operation ID: `get_payment_history`
Operation page: `/api/operations/get_payment_history`
Get payment history for an invoice

Parameters:
- `id` (path, required): string / uuid - Invoice ID

Responses:
- `200` Payment history retrieved (application/json: DataResponse_PaymentHistory)
- `404` Invoice not found
- `500` Internal server error

### GET /billing/payment-methods

Operation ID: `list_payment_methods`
Operation page: `/api/operations/list_payment_methods`
List payment methods for the organization

Responses:
- `200` Payment methods retrieved (application/json: DataResponse_Vec_PaymentMethod)
- `500` Internal server error

### POST /billing/payment-methods

Operation ID: `add_payment_method`
Operation page: `/api/operations/add_payment_method`
Add a payment method for the organization

Request body (required):
- `application/json`: AddPaymentMethodRequest

Responses:
- `200` Payment method added (application/json: DataResponse_PaymentMethodAdded)
- `400` Invalid request
- `500` Internal server error

### DELETE /billing/payment-methods/{id}

Operation ID: `delete_payment_method`
Operation page: `/api/operations/delete_payment_method`
Remove a payment method from the organization

Parameters:
- `id` (path, required): string / uuid - Payment method ID

Responses:
- `204` Payment method removed
- `404` Payment method not found
- `500` Internal server error

### GET /payments/supported

Operation ID: `get_supported`
Operation page: `/api/operations/get_supported`
Returns supported x402 payment kinds for facilitator discovery.

Responses:
- `200` Supported payment kinds (application/json: SupportedResponse)
- `500` Internal server error

## Plans

### GET /organizations/{organization_id}/plan

Operation ID: `get_organization_plan`
Operation page: `/api/operations/get_organization_plan`
Get the current plan for an organization

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization

Responses:
- `200` Organization plan retrieved successfully (application/json: DataResponse_OrganizationPlanWithDetails)
- `404` Organization or plan not found
- `500` Internal server error

### POST /organizations/{organization_id}/plan

Operation ID: `change_organization_plan`
Operation page: `/api/operations/change_organization_plan`
Upgrade or downgrade an organization's plan

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization

Request body (required):
- `application/json`: ChangePlanRequest

Responses:
- `200` Plan changed successfully (application/json: DataResponse_OrganizationPlanWithDetails)
- `400` Invalid request
- `404` Organization or plan not found
- `500` Internal server error

### GET /organizations/{organization_id}/quota

Operation ID: `get_quota_usage`
Operation page: `/api/operations/get_quota_usage`
Get current quota usage for an organization

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization

Responses:
- `200` Quota usage retrieved successfully (application/json: DataResponse_QuotaUsage)
- `404` Organization or plan not found
- `500` Internal server error

### GET /plans

Operation ID: `list_plans`
Operation page: `/api/operations/list_plans`
List all available subscription plans

Responses:
- `200` Plans retrieved successfully (application/json: DataResponse_Vec_Plan)
- `500` Internal server error

### GET /plans/{plan_id}

Operation ID: `get_plan`
Operation page: `/api/operations/get_plan`
Get details of a specific plan

Parameters:
- `plan_id` (path, required): string / uuid - Plan ID

Responses:
- `200` Plan retrieved successfully (application/json: DataResponse_Plan)
- `404` Plan not found
- `500` Internal server error

## publisher-payments

### POST /billing/publishers/{slug}/charges

Operation ID: `create_charge`
Operation page: `/api/operations/create_charge`

Parameters:
- `slug` (path, required): string - Publisher slug

Request body (required):
- `application/json`: CreateChargeRequest

Responses:
- `200` Charge created (application/json: DataResponse_PublisherChargeInfo)
- `401` Unauthorized
- `402` Insufficient balance
- `403` Forbidden
- `404` Publisher not found

### GET /billing/publishers/{slug}/charges/{charge_id}

Operation ID: `get_charge_status`
Operation page: `/api/operations/get_charge_status`

Parameters:
- `slug` (path, required): string - Publisher slug
- `charge_id` (path, required): string / uuid - Charge ID

Responses:
- `200` Charge retrieved (application/json: DataResponse_PublisherChargeInfo)
- `401` Unauthorized
- `403` Forbidden
- `404` Charge not found

### POST /billing/publishers/{slug}/charges/{charge_id}/refund

Operation ID: `refund_charge`
Operation page: `/api/operations/refund_charge`

Parameters:
- `slug` (path, required): string - Publisher slug
- `charge_id` (path, required): string / uuid - Charge ID

Request body (required):
- `application/json`: RefundChargeRequest

Responses:
- `200` Charge refunded (application/json: DataResponse_PublisherChargeInfo)
- `401` Unauthorized
- `403` Forbidden
- `404` Charge not found

### POST /billing/publishers/{slug}/charges/{charge_id}/slash

Operation ID: `slash_charge`
Operation page: `/api/operations/slash_charge`

Parameters:
- `slug` (path, required): string - Publisher slug
- `charge_id` (path, required): string / uuid - Original charge ID

Request body (required):
- `application/json`: SlashChargeRequest

Responses:
- `204` Slash applied
- `401` Unauthorized
- `402` Insufficient balance
- `403` Forbidden
- `404` Charge not found

### POST /billing/publishers/{slug}/payouts

Operation ID: `create_payout`
Operation page: `/api/operations/create_payout`

Parameters:
- `slug` (path, required): string - Publisher slug

Request body (required):
- `application/json`: CreatePayoutRequest

Responses:
- `200` Payout created (application/json: DataResponse_PublisherPayoutInfo)
- `401` Unauthorized
- `403` Forbidden
- `404` Publisher not found

### GET /billing/publishers/{slug}/payouts/{payout_id}

Operation ID: `get_payout_status`
Operation page: `/api/operations/get_payout_status`

Parameters:
- `slug` (path, required): string - Publisher slug
- `payout_id` (path, required): string / uuid - Payout ID

Responses:
- `200` Payout retrieved (application/json: DataResponse_PublisherPayoutInfo)
- `401` Unauthorized
- `403` Forbidden
- `404` Payout not found

### GET /wallet/lookup/{agent_wallet}

Operation ID: `get_agent_balance`
Operation page: `/api/operations/get_agent_balance`
Look up an agent's available balance (for publisher pre-checks)

Parameters:
- `agent_wallet` (path, required): string - Agent wallet address

Responses:
- `200` Balance retrieved (application/json: DataResponse_PublisherAgentBalance)
- `401` Unauthorized
- `403` Forbidden
- `404` Publisher not found

## publishers

### GET /publishers

Operation ID: `list_store_publishers`
Operation page: `/api/operations/list_store_publishers`
List publishers with full details and pricing (store view)

Parameters:
- `is_verified` (query): boolean | null - Filter by verification status
- `category` (query): null | PublisherCategory - Filter by publisher category
- `search` (query): string | null - Search by name or slug
- `limit` (query): integer / int64 - Maximum number of results (default: 50, max: 100)
- `offset` (query): integer / int64 - Offset for pagination

Responses:
- `200` Publishers retrieved successfully (application/json: PaginatedResponse_Vec_PublisherResponse)
- `400` Invalid query parameters
- `500` Internal server error

### GET /publishers/{slug}

Operation ID: `get_store_publisher`
Operation page: `/api/operations/get_store_publisher`
Get publisher by slug (store view with full details)

Parameters:
- `slug` (path, required): string - Publisher slug

Responses:
- `200` Publisher retrieved successfully (application/json: DataResponse_PublisherResponse)
- `404` Publisher not found
- `500` Internal server error

### POST /publishers/{slug}

Operation ID: `publisher_root_handler`
Operation page: `/api/operations/publisher_root_handler`
Handle requests to the publisher root.

For database publishers, this executes a query from the request body.
For API publishers, this proxies to the root endpoint.
For agent publishers (compute_type=agent), this creates a task and returns 202 Accepted.
For MCP publishers, this returns an error (use specific tool/resource endpoints).

Parameters:
- `slug` (path, required): string - Publisher slug identifier

Request body (required):
- `application/json`: PublisherRootRequest

Responses:
- `200` Request processed successfully (database/API) (application/json: object)
- `202` Agent task accepted (async) (application/json: object)
- `402` Payment required
- `404` Publisher not found
- `500` Internal server error

### GET /publishers/{slug}/{path}

Operation ID: `proxy_to_publisher_get`
Operation page: `/api/operations/proxy_to_publisher_get`

Parameters:
- `slug` (path, required): string - Publisher slug identifier
- `path` (path, required): string - Path to proxy to the publisher
- `x-seren-oauth-connection-id` (header): string | null / uuid - Optional OAuth connection UUID for BYOC publishers
- `connection_id` (query): string / uuid - Optional OAuth connection UUID for MCP publisher routes

Request body (required):
- `application/octet-stream`: object

Responses:
- `200` Request proxied successfully. Response shape depends on publisher type and sub-path; first-class publisher endpoints document typed schemas. (application/json: object)
- `402` Payment required
- `403` Publisher is geo-restricted and routing is not enabled (application/json: GeoRestrictedError)
- `404` Publisher or endpoint not found
- `409` Multiple OAuth connections are available and no selector/default was provided (application/json: MultipleOAuthConnectionsAmbiguousResponse)
- `500` Internal server error

### POST /publishers/{slug}/{path}

Operation ID: `proxy_to_publisher_post`
Operation page: `/api/operations/proxy_to_publisher_post`

Parameters:
- `slug` (path, required): string - Publisher slug identifier
- `path` (path, required): string - Path to proxy to the publisher
- `x-seren-oauth-connection-id` (header): string | null / uuid - Optional OAuth connection UUID for BYOC publishers
- `connection_id` (query): string / uuid - Optional OAuth connection UUID for MCP publisher routes

Request body (required):
- `application/octet-stream`: object

Responses:
- `200` Request proxied successfully. Response shape depends on publisher type and sub-path; first-class publisher endpoints document typed schemas. (application/json: object)
- `402` Payment required
- `403` Publisher is geo-restricted and routing is not enabled (application/json: GeoRestrictedError)
- `404` Publisher or endpoint not found
- `409` Multiple OAuth connections are available and no selector/default was provided (application/json: MultipleOAuthConnectionsAmbiguousResponse)
- `500` Internal server error

### POST /publishers/{slug}/estimate

Operation ID: `estimate_query`
Operation page: `/api/operations/estimate_query`
Estimate query cost without payment

Parameters:
- `slug` (path, required): string - Publisher slug

Request body (required):
- `application/json`: EstimateRequestBody

Responses:
- `200` Cost estimate (application/json: EstimateResponse)
- `404` Publisher not found
- `500` Internal server error

### GET /publishers/{slug}/logo

Operation ID: `get_store_publisher_logo`
Operation page: `/api/operations/get_store_publisher_logo`
Fetch publisher logo (inline data or redirect to URL)
Accepts either publisher slug or UUID for backwards compatibility

Parameters:
- `slug` (path, required): string - Publisher slug or UUID

Responses:
- `200` Publisher logo bytes
- `302` Redirect to external logo URL
- `404` Logo not found

### POST /publishers/seren-models/chat/completions

Operation ID: `seren_models_chat_completions`
Operation page: `/api/operations/seren_models_chat_completions`

Request body (required):
- `application/json`: object

Responses:
- `200` Publisher chat completion response (application/json: DataResponse_ApiResultResponse)
- `401` Authentication required
- `402` Payment required
- `500` Internal server error

### POST /publishers/seren-private-models/chat/completions

Operation ID: `post_chat_completions`
Operation page: `/api/operations/post_chat_completions`

Request body (required):
- `application/json`: PrivateModelsChatCompletionsRequest

Responses:
- `200` Publisher chat completion response (application/json: DataResponse_ApiResultResponse)
- `401` Authentication required
- `403` Private models are not configured for this organization
- `500` Internal server error

### GET /publishers/seren-private-models/models

Operation ID: `get_private_models`
Operation page: `/api/operations/get_private_models`

Responses:
- `200` Available private models (application/json: DataResponse_PrivateModelsListResponse)
- `401` Authentication required
- `403` Private models are not configured for this organization
- `500` Internal server error

### GET /publishers/suggest

Operation ID: `suggest_publishers`
Operation page: `/api/operations/suggest_publishers`
Suggest publishers based on a task or query

Parameters:
- `query` (query, required): string - The task or query to match against publisher capabilities. Examples: "scrape website", "AI research", "PDF extraction"
- `type` (query): string - Type of suggestions: "publisher", "agent", or "both" (default: "both") Note: Agent suggestions are planned but not yet implemented.
- `limit` (query): integer / int64 - Maximum number of results (default: 5, max: 20)

Responses:
- `200` Publisher suggestions retrieved successfully (application/json: DataResponse_SuggestResponse)
- `400` Invalid query parameters
- `500` Internal server error

## RBAC

### PUT /organizations/{organization_id}/members/{member_id}/role

Operation ID: `assign_role`
Operation page: `/api/operations/assign_role`
Assign a role to an organization member

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `member_id` (path, required): string / uuid - Member user ID

Request body (required):
- `application/json`: AssignRoleRequest

Responses:
- `200` Role assigned successfully
- `400` Invalid request
- `401` Unauthorized
- `403` Forbidden - requires org.manage_members permission
- `404` Member or role not found

### GET /organizations/{organization_id}/permissions/check/{permission}

Operation ID: `check_permission`
Operation page: `/api/operations/check_permission`
Check if the current user has a specific permission

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `permission` (path, required): string - Permission name to check

Responses:
- `200` Permission check result (application/json: DataResponse_bool)
- `401` Unauthorized
- `403` Forbidden - not a member of this organization

### GET /organizations/{organization_id}/permissions/mine

Operation ID: `get_my_permissions`
Operation page: `/api/operations/get_my_permissions`
Get current user's permissions in an organization

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization

Responses:
- `200` User's permissions (application/json: DataResponse_Vec_String)
- `401` Unauthorized
- `403` Forbidden - not a member of this organization

### GET /organizations/{organization_id}/roles

Operation ID: `list_organization_roles`
Operation page: `/api/operations/list_organization_roles`
List roles for an organization (includes built-in roles)

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization

Responses:
- `200` Roles retrieved successfully (application/json: DataResponse_Vec_RbacRole)
- `401` Unauthorized
- `403` Forbidden - not a member of this organization

### POST /organizations/{organization_id}/roles

Operation ID: `create_organization_role`
Operation page: `/api/operations/create_organization_role`
Create a custom role

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization

Request body (required):
- `application/json`: CreateRoleRequest

Responses:
- `201` Role created successfully (application/json: DataResponse_RbacRole)
- `400` Invalid request
- `401` Unauthorized
- `403` Forbidden - requires org.manage_roles permission

### DELETE /organizations/{organization_id}/roles/{role_id}

Operation ID: `delete_organization_role`
Operation page: `/api/operations/delete_organization_role`
Delete a custom role

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `role_id` (path, required): string / uuid - Role ID

Responses:
- `204` Role deleted successfully
- `400` Cannot delete built-in role
- `401` Unauthorized
- `403` Forbidden - requires org.manage_roles permission
- `404` Role not found

### GET /organizations/{organization_id}/roles/{role_id}

Operation ID: `get_role`
Operation page: `/api/operations/get_role`
Get a specific role

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `role_id` (path, required): string / uuid - Role ID

Responses:
- `200` Role retrieved successfully (application/json: DataResponse_RbacRole)
- `401` Unauthorized
- `403` Forbidden - not a member of this organization
- `404` Role not found

### PATCH /organizations/{organization_id}/roles/{role_id}

Operation ID: `update_role`
Operation page: `/api/operations/update_role`
Update a custom role

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `role_id` (path, required): string / uuid - Role ID

Request body (required):
- `application/json`: UpdateRoleRequest

Responses:
- `200` Role updated successfully (application/json: DataResponse_RbacRole)
- `400` Invalid request or cannot modify built-in role
- `401` Unauthorized
- `403` Forbidden - requires org.manage_roles permission
- `404` Role not found

### GET /permissions

Operation ID: `list_permissions`
Operation page: `/api/operations/list_permissions`
List all permissions

Responses:
- `200` Permissions retrieved successfully (application/json: DataResponse_Vec_Permission)
- `401` Unauthorized

## Resolve

### POST /publishers/seren-passwords/resolve

Operation ID: `resolve_secret`
Operation page: `/api/operations/resolve_secret`
Resolve a single `seren-secrets://...` reference. The request signature is
verified against the caller identity's signing key; resolution gates on
vault membership and the approval policy.

Parameters:
- `X-Seren-Correlation-Id` (header): string | null / uuid - Optional invocation correlation id for audit lineage

Request body (required):
- `application/json`: ResolveRequest

Responses:
- `200` Wrapped material for the referenced field (application/json: DataResponseResolve)
- `400` Malformed uri or signature outside the freshness window
- `401` Invalid resolve signature or caller revoked
- `403` Approval required; see error.approval_request_id
- `404` Vault or item not found
- `409` No wrapped vault key available for the caller
- `422` Request body failed validation
- `429` Resolve read rate limit exceeded

### POST /publishers/seren-passwords/resolve/batch

Operation ID: `resolve_batch`
Operation page: `/api/operations/resolve_batch`
Resolve a batch of references in one round-trip. Each entry is signed and
audited independently; per-entry failures surface in the result list
rather than failing the whole batch.

Parameters:
- `X-Seren-Correlation-Id` (header): string | null / uuid - Optional invocation correlation id for audit lineage

Request body (required):
- `application/json`: BatchResolveRequest

Responses:
- `200` Per-entry resolve results (application/json: DataResponseBatchResolve)
- `400` Batch is empty or exceeds the per-call cap
- `401` Caller is not authenticated
- `422` Request body failed validation
- `429` Resolve read rate limit exceeded

## Rotation

### POST /publishers/seren-passwords/vaults/{vault_id}/rotate-key/cancel

Operation ID: `vault_rotation_cancel`
Operation page: `/api/operations/vault_rotation_cancel`
Abandon an in-progress rotation and re-open the vault for writes.

Parameters:
- `vault_id` (path, required): string / uuid - Vault id

Request body (required):
- `application/json`: RotationCancelRequest

Responses:
- `200` Cancelled (application/json: DataResponseJsonValue)
- `401` Caller is not authenticated
- `403` Caller is not an admin of this vault
- `404` Vault not found or rotation_token did not match
- `422` Request body failed validation

### POST /publishers/seren-passwords/vaults/{vault_id}/rotate-key/complete

Operation ID: `vault_rotation_complete`
Operation page: `/api/operations/vault_rotation_complete`
Atomically commit a rotation: re-wrap every member's vault key,
re-encrypt every item, attachment metadata, and invitation email under
the new vault key, and re-wrap every attachment content key.

Parameters:
- `vault_id` (path, required): string / uuid - Vault id

Request body (required):
- `application/json`: RotationCompleteRequest

Responses:
- `200` Completed (application/json: DataResponseJsonValue)
- `400` Submitted membership/item set does not match the vault
- `401` Caller is not authenticated
- `403` Caller is not an admin of this vault
- `404` Vault not found or rotation_token did not match
- `422` Request body failed validation

### POST /publishers/seren-passwords/vaults/{vault_id}/rotate-key/initiate

Operation ID: `vault_rotation_initiate`
Operation page: `/api/operations/vault_rotation_initiate`
Begin a key rotation on a vault: marks the vault `rotating`, mints a
rotation_token, and blocks vault writes from this point on.

Parameters:
- `vault_id` (path, required): string / uuid - Vault id

Responses:
- `200` Rotation token (application/json: DataResponseRotationInitiate)
- `401` Caller is not authenticated
- `403` Caller is not an admin of this vault
- `404` Vault not found
- `423` Vault is already rotating

## search

### PUT /publishers/seren-notes/notes/{note_id}/embedding

Operation ID: `update_embedding`
Operation page: `/api/operations/update_embedding`
Update a note's embedding

Parameters:
- `note_id` (path, required): string / uuid - Note ID

Request body (required):
- `application/json`: UpdateEmbeddingRequest

Responses:
- `204` Embedding updated
- `400` Invalid embedding
- `401` Unauthorized
- `404` Note not found

### GET /publishers/seren-notes/notes/{note_id}/embedding/content

Operation ID: `get_embedding_content`
Operation page: `/api/operations/get_embedding_content`
Get note content for embedding generation

Parameters:
- `note_id` (path, required): string / uuid - Note ID

Responses:
- `200` Note content for embedding
- `401` Unauthorized
- `404` Note not found

### GET /publishers/seren-notes/notes/embeddings/stale

Operation ID: `get_stale_embeddings`
Operation page: `/api/operations/get_stale_embeddings`
Get notes that need embedding updates

Parameters:
- `limit` (query): integer / int32 - Maximum notes to return

Responses:
- `200` List of note IDs needing embeddings
- `401` Unauthorized

### POST /publishers/seren-notes/notes/search/semantic

Operation ID: `semantic_search`
Operation page: `/api/operations/semantic_search`
Semantic search using embedding vector

Request body (required):
- `application/json`: SemanticSearchQuery

Responses:
- `200` Semantic search results (application/json: DataResponse_Vec_SemanticSearchResultResponse)
- `400` Invalid embedding
- `401` Unauthorized

## Secrets Gateway

### GET /publishers/seren-passwords/secrets-gateway/delegation-config

Operation ID: `secrets_gateway_delegation_config`
Operation page: `/api/operations/secrets_gateway_delegation_config`

Responses:
- `200` GrantDelegate metadata for client-signed secret resolution delegations (application/json: DataResponseSecretsGatewayDelegationConfig)
- `401` Caller is not authenticated
- `404` Secret gateway material issuer is not configured

## seren-agent

### GET /publishers/seren-agent/capabilities

Operation ID: `seren_agent_capabilities`
Operation page: `/api/operations/seren_agent_capabilities`
Inspect available orchestration features and runtime limits.

Responses:
- `200` Capabilities retrieved (application/json: DataResponse_AgentCapabilitiesResponse)

### POST /publishers/seren-agent/deploy

Operation ID: `seren_agent_deploy`
Operation page: `/api/operations/seren_agent_deploy`
Create or update an orchestrated deployment (forwarded to seren-cloud).

Request body (required):
- `application/json`: AgentSpec

Responses:
- `202` Deployment accepted (application/json: DataResponse_CloudDeploymentSummary)
- `400` Bad request
- `401` Unauthorized
- `500` Deployment could not be initialized (application/json: ErrorResponse)

### GET /publishers/seren-agent/deployments

Operation ID: `seren_agent_list_deployments`
Operation page: `/api/operations/seren_agent_list_deployments`
List orchestrated deployments and their runtime metadata.

Responses:
- `200` Deployments listed (application/json: DataResponse_Vec_CloudDeploymentSummary)
- `401` Unauthorized

### DELETE /publishers/seren-agent/deployments/{id}

Operation ID: `seren_agent_delete_managed_deployment`
Operation page: `/api/operations/seren_agent_delete_managed_deployment`
Delete a managed seren-agent deployment and clean up runtime resources.

Parameters:
- `id` (path, required): string / uuid - Deployment ID

Responses:
- `200` Managed deployment deleted (application/json: DataResponse_CloudDeploymentActionStatusResponse)
- `400` Bad request
- `404` Deployment not found

### GET /publishers/seren-agent/deployments/{id}/activity

Operation ID: `seren_agent_get_deployment_activity`
Operation page: `/api/operations/seren_agent_get_deployment_activity`
Get recent activity for a managed seren-agent deployment.

Returns recent managed-agent activity with run status, timing, cost, token, and artifact-count summaries. This endpoint omits prompt, output, and tool payload details; use seren-cloud run-history APIs for full runtime history.

Parameters:
- `id` (path, required): string / uuid - Deployment ID
- `limit` (query): integer / int64 - Max run activity entries to return (default: 20, max: 100)
- `offset` (query): integer / int64 - Pagination offset

Responses:
- `200` Managed deployment activity retrieved (application/json: DataResponse_ManagedAgentDeploymentActivityReport)
- `400` Deployment is not managed by seren-agent
- `401` Unauthorized
- `403` Forbidden
- `404` Deployment not found

### GET /publishers/seren-agent/deployments/{id}/health

Operation ID: `seren_agent_get_deployment_health`
Operation page: `/api/operations/seren_agent_get_deployment_health`
Get health for a managed seren-agent deployment.

Returns a managed-agent health projection for a seren-agent deployment. Use seren-cloud deployment APIs for raw runtime state and run history.

Parameters:
- `id` (path, required): string / uuid - Deployment ID

Responses:
- `200` Managed deployment health retrieved (application/json: DataResponse_ManagedAgentDeploymentHealthReport)
- `400` Deployment is not managed by seren-agent
- `401` Unauthorized
- `403` Forbidden
- `404` Deployment not found

### GET /publishers/seren-agent/deployments/{id}/managed

Operation ID: `seren_agent_get_managed_deployment`
Operation page: `/api/operations/seren_agent_get_managed_deployment`
Get the resolved managed spec for a seren-agent deployment.

Returns the resolved managed-agent configuration for a seren-agent deployment. Use seren-cloud deployment APIs for raw runtime operations.

Parameters:
- `id` (path, required): string / uuid - Deployment ID

Responses:
- `200` Managed deployment detail retrieved (application/json: DataResponse_ManagedAgentDeploymentDetail)
- `403` Managed deployment is opaque to this caller
- `404` Deployment not found

### PATCH /publishers/seren-agent/deployments/{id}/managed

Operation ID: `seren_agent_update_managed_deployment`
Operation page: `/api/operations/seren_agent_update_managed_deployment`
Update the editable managed spec for a seren-agent deployment.

Parameters:
- `id` (path, required): string / uuid - Deployment ID

Request body (required):
- `application/json`: AgentSpecUpdate

Responses:
- `200` Managed deployment updated (application/json: DataResponse_CloudDeploymentSummary)
- `400` Bad request
- `403` Managed deployment is opaque to this caller
- `404` Deployment not found

### PATCH /publishers/seren-agent/deployments/{id}/managed/files

Operation ID: `seren_agent_patch_managed_deployment_files`
Operation page: `/api/operations/seren_agent_patch_managed_deployment_files`
Update files for a managed deployment.

Parameters:
- `id` (path, required): string / uuid - Deployment ID

Request body (required):
- `application/json`: AgentBundlePatch

Responses:
- `200` Managed deployment files updated (application/json: DataResponse_CloudDeploymentSummary)
- `400` Bad request
- `403` Managed deployment is opaque to this caller
- `404` Deployment not found

### POST /publishers/seren-agent/deployments/{id}/managed/preview

Operation ID: `seren_agent_preview_managed_deployment_update`
Operation page: `/api/operations/seren_agent_preview_managed_deployment_update`
Preview a managed update before applying it.

Parameters:
- `id` (path, required): string / uuid - Deployment ID

Request body (required):
- `application/json`: AgentSpecUpdate

Responses:
- `200` Managed deployment update preview (application/json: DataResponse_ManagedAgentDeploymentUpdatePreview)
- `400` Bad request
- `403` Managed deployment is opaque to this caller
- `404` Deployment not found

### GET /publishers/seren-agent/deployments/{id}/managed/revisions

Operation ID: `seren_agent_list_managed_deployment_revisions`
Operation page: `/api/operations/seren_agent_list_managed_deployment_revisions`
List immutable revision snapshots for a managed deployment.

Parameters:
- `id` (path, required): string / uuid - Deployment ID

Responses:
- `200` Managed deployment revisions listed (application/json: DataResponse_Vec_ManagedAgentDeploymentRevisionSummary)
- `403` Managed deployment is opaque to this caller
- `404` Deployment not found

### POST /publishers/seren-agent/deployments/{id}/managed/rollback

Operation ID: `seren_agent_rollback_managed_deployment`
Operation page: `/api/operations/seren_agent_rollback_managed_deployment`
Roll a managed deployment back to a prior revision.

Parameters:
- `id` (path, required): string / uuid - Deployment ID

Request body (required):
- `application/json`: RollbackSerenAgentDeploymentRequest

Responses:
- `200` Managed deployment rolled back (application/json: DataResponse_CloudDeploymentSummary)
- `400` Bad request
- `403` Managed deployment is opaque to this caller
- `404` Deployment or revision not found

### POST /publishers/seren-agent/deployments/{id}/managed/rollback/preview

Operation ID: `seren_agent_preview_managed_deployment_rollback`
Operation page: `/api/operations/seren_agent_preview_managed_deployment_rollback`
Preview rolling a managed deployment back to a prior revision.

Parameters:
- `id` (path, required): string / uuid - Deployment ID

Request body (required):
- `application/json`: RollbackSerenAgentDeploymentRequest

Responses:
- `200` Managed deployment rollback preview (application/json: DataResponse_ManagedAgentDeploymentRollbackPreview)
- `400` Bad request
- `403` Managed deployment is opaque to this caller
- `404` Deployment or revision not found

### POST /publishers/seren-agent/deployments/{id}/managed/runtime-policy-reconciliation

Operation ID: `seren_agent_apply_runtime_policy_reconciliation`
Operation page: `/api/operations/seren_agent_apply_runtime_policy_reconciliation`
Apply an eligible runtime-policy reconciliation as a normal managed
deployment revision.

Parameters:
- `id` (path, required): string / uuid - Deployment ID

Responses:
- `200` Runtime-policy reconciliation result (application/json: DataResponse_ManagedAgentRuntimePolicyReconciliationResult)
- `400` Deployment is not eligible
- `403` Forbidden
- `404` Deployment not found
- `409` Stored timeout conflicts with the declared policy

### POST /publishers/seren-agent/deployments/{id}/managed/runtime-policy-reconciliation/preview

Operation ID: `seren_agent_preview_runtime_policy_reconciliation`
Operation page: `/api/operations/seren_agent_preview_runtime_policy_reconciliation`
Preview safe reconciliation for a deployment created before canonical
runtime-policy deadline metadata.

Parameters:
- `id` (path, required): string / uuid - Deployment ID

Responses:
- `200` Runtime-policy reconciliation preview (application/json: DataResponse_ManagedAgentRuntimePolicyReconciliationPreview)
- `403` Forbidden
- `404` Deployment not found

### GET /publishers/seren-agent/deployments/{id}/resources

Operation ID: `seren_agent_get_deployment_resources`
Operation page: `/api/operations/seren_agent_get_deployment_resources`
Get platform resources available to a managed seren-agent deployment.

Returns a managed-agent resource summary. This endpoint is a managed-agent projection; use seren-cloud deployment APIs for full runtime operations.

Parameters:
- `id` (path, required): string / uuid - Deployment ID

Responses:
- `200` Managed deployment resources retrieved (application/json: DataResponse_ManagedAgentDeploymentResources)
- `400` Deployment is not managed by seren-agent
- `401` Unauthorized
- `403` Forbidden
- `404` Deployment not found

### POST /publishers/seren-agent/deployments/{id}/start

Operation ID: `seren_agent_start_managed_deployment`
Operation page: `/api/operations/seren_agent_start_managed_deployment`
Start a managed seren-agent deployment.

Parameters:
- `id` (path, required): string / uuid - Deployment ID

Responses:
- `200` Managed deployment started (application/json: DataResponse_CloudDeploymentActionStatusResponse)
- `400` Bad request
- `404` Deployment not found

### POST /publishers/seren-agent/deployments/{id}/stop

Operation ID: `seren_agent_stop_managed_deployment`
Operation page: `/api/operations/seren_agent_stop_managed_deployment`
Stop a managed seren-agent deployment.

Parameters:
- `id` (path, required): string / uuid - Deployment ID

Responses:
- `200` Managed deployment stopped (application/json: DataResponse_CloudDeploymentActionStatusResponse)
- `400` Bad request
- `404` Deployment not found

### GET /publishers/seren-agent/deployments/{id}/tool-groups

Operation ID: `seren_agent_list_deployment_tool_groups`
Operation page: `/api/operations/seren_agent_list_deployment_tool_groups`
List tool groups currently assigned to a managed seren-agent deployment.

Returns the resolved tool-group read model for a managed seren-agent deployment. Today these groups are derived from the deployment's tool_presets config inputs; future explicit tool-group assignments will use the same response shape.

Parameters:
- `id` (path, required): string / uuid - Deployment ID

Responses:
- `200` Managed deployment tool groups retrieved (application/json: DataResponse_ManagedAgentToolGroupResponse)
- `400` Deployment is not managed by seren-agent
- `401` Unauthorized
- `403` Forbidden
- `404` Deployment not found

### GET /publishers/seren-agent/deployments/{id}/tools

Operation ID: `seren_agent_list_deployment_tools`
Operation page: `/api/operations/seren_agent_list_deployment_tools`
List tools currently visible to a managed seren-agent deployment.

Returns the declared tool catalog for a managed seren-agent deployment, including source, approval, and side-effect metadata. This endpoint is a managed-agent projection; use seren-cloud run APIs for runtime execution.

Parameters:
- `id` (path, required): string / uuid - Deployment ID
- `q` (query): string - Optional case-insensitive search over tool names, descriptions, and sources

Responses:
- `200` Managed deployment tool catalog retrieved (application/json: DataResponse_ManagedAgentToolCatalogResponse)
- `400` Deployment is not managed by seren-agent
- `401` Unauthorized
- `403` Forbidden
- `404` Deployment not found

### GET /publishers/seren-agent/deployments/{id}/tools/{tool_name}

Operation ID: `seren_agent_describe_deployment_tool`
Operation page: `/api/operations/seren_agent_describe_deployment_tool`
Describe one tool currently visible to a managed seren-agent deployment.

Returns one declared tool descriptor for a managed seren-agent deployment, including source, approval, and side-effect metadata. This endpoint is a managed-agent projection; use seren-cloud run APIs for runtime execution.

Parameters:
- `id` (path, required): string / uuid - Deployment ID
- `tool_name` (path, required): string - Tool name

Responses:
- `200` Managed deployment tool descriptor retrieved (application/json: DataResponse_ManagedAgentToolCatalogEntry)
- `400` Deployment is not managed by seren-agent
- `401` Unauthorized
- `403` Forbidden
- `404` Deployment or tool not found

### GET /publishers/seren-agent/health

Operation ID: `seren_agent_health`
Operation page: `/api/operations/seren_agent_health`
Get organization-level health for managed seren-agent deployments.

Returns an organization-level managed-agent health projection. Use seren-cloud deployment APIs for raw runtime state and run history.

Responses:
- `200` Managed agent health retrieved (application/json: DataResponse_ManagedAgentHealthReport)
- `401` Unauthorized
- `403` Forbidden

### GET /publishers/seren-agent/private-models

Operation ID: `seren_agent_private_models`
Operation page: `/api/operations/seren_agent_private_models`
List the private model catalog available through seren-private-models.

Parameters:
- `region` (query): string - Optional private model region for live discovery. Defaults to us-east-1.

Responses:
- `200` Private model catalog retrieved (application/json: DataResponse_PrivateModelCatalogResponse)

### POST /publishers/seren-agent/test-run

Operation ID: `seren_agent_test_run`
Operation page: `/api/operations/seren_agent_test_run`
Run an unsaved managed seren-agent draft once before deploying.

Request body (required):
- `application/json`: TestSerenAgentDraftRunRequest

Responses:
- `200` Draft test run completed (application/json: DataResponse_TestSerenAgentDraftRunResponse)
- `400` Bad request
- `401` Unauthorized
- `500` Draft runtime could not be initialized (application/json: ErrorResponse)

## seren-cloud

### GET /publishers/seren-cloud/audit

Operation ID: `seren_cloud_list_audit_entries`
Operation page: `/api/operations/seren_cloud_list_audit_entries`
List tamper-evident audit entries for seren-cloud.

Parameters:
- `limit` (query): integer / int64 - Max audit entries to return (default: 50, max: 200)
- `offset` (query): integer / int64 - Pagination offset
- `action` (query): string - Filter by exact audit action
- `q` (query): string - Case-insensitive search across action, actor, and details

Responses:
- `200` Audit entries listed (application/json: DataResponse_Vec_AuditEntry)

### GET /publishers/seren-cloud/audit/{entry_id}

Operation ID: `seren_cloud_get_audit_entry`
Operation page: `/api/operations/seren_cloud_get_audit_entry`
Get a single tamper-evident audit entry.

Parameters:
- `entry_id` (path, required): string / uuid - Audit entry ID

Responses:
- `200` Audit entry details (application/json: DataResponse_AuditEntry)
- `404` Audit entry not found

### GET /publishers/seren-cloud/audit/verify

Operation ID: `seren_cloud_verify_audit`
Operation page: `/api/operations/seren_cloud_verify_audit`
Verify the tamper-evident audit chain.

Parameters:
- `limit` (query): integer / int64 - Max audit entries to verify in sequence order (default: 10000, max: 100000)

Responses:
- `200` Audit verification result (application/json: DataResponse_VerificationResult)

### GET /publishers/seren-cloud/connectors

Operation ID: `seren_cloud_list_connectors`
Operation page: `/api/operations/seren_cloud_list_connectors`
List supported messaging connectors with credential requirements and
this organization's connection status.

Responses:
- `200` Supported connectors with credential fields and connection status (application/json: DataResponse_ConnectorCatalogResponse)
- `401` Unauthorized
- `403` Forbidden

### POST /publishers/seren-cloud/connectors/{connector_ref}/verify

Operation ID: `seren_cloud_verify_connector_credentials`
Operation page: `/api/operations/seren_cloud_verify_connector_credentials`
Verify connector credentials against the provider without storing them.

Parameters:
- `connector_ref` (path, required): string - Connector catalog reference

Request body (required):
- `application/json`: VerifyConnectorCredentialsRequest

Responses:
- `200` Verification outcome; invalid credentials return ok=false (application/json: DataResponse_VerifyConnectorCredentialsResponse)
- `400` Unsupported connector or malformed request
- `401` Unauthorized
- `403` Forbidden
- `404` Unknown connector
- `502` Connector provider is temporarily unavailable

### GET /publishers/seren-cloud/credential-secrets

Operation ID: `seren_cloud_list_credential_secrets`
Operation page: `/api/operations/seren_cloud_list_credential_secrets`
List managed-agent credential secret metadata for the organization.

Parameters:
- `scope` (query): string - Filter by scope: organization or user

Responses:
- `200` Credential secret metadata; values are never returned (application/json: DataResponse_Vec_AgentCredentialSecret)
- `401` Unauthorized
- `403` Forbidden

### POST /publishers/seren-cloud/credential-secrets

Operation ID: `seren_cloud_upsert_credential_secret`
Operation page: `/api/operations/seren_cloud_upsert_credential_secret`
Store or rotate a managed-agent credential secret.

Request body (required):
- `application/json`: UpsertAgentCredentialSecretRequest

Responses:
- `200` Credential secret stored; the value is encrypted and never echoed back (application/json: DataResponse_AgentCredentialSecret)
- `400` Invalid secret name or value
- `401` Unauthorized
- `403` Forbidden

### DELETE /publishers/seren-cloud/credential-secrets/{name}

Operation ID: `seren_cloud_delete_credential_secret`
Operation page: `/api/operations/seren_cloud_delete_credential_secret`
Delete a managed-agent credential secret by name.

Parameters:
- `name` (path, required): string - Credential secret name
- `scope` (query): string - Scope to delete from: organization (default) or user

Responses:
- `200` Credential secret deleted (application/json: DataResponse_AgentCredentialSecretDeleted)
- `401` Unauthorized
- `403` Forbidden
- `404` Credential secret not found

### POST /publishers/seren-cloud/deploy

Operation ID: `seren_cloud_deploy`
Operation page: `/api/operations/seren_cloud_deploy`
Deploy a skill to seren-cloud.

Request body (required):
- `application/json`: CreateCloudDeploymentRequest

Responses:
- `202` Deployment accepted (application/json: DataResponse_CloudDeploymentSummary)
- `400` Bad request
- `401` Unauthorized

### POST /publishers/seren-cloud/deployment-bundles

Operation ID: `seren_cloud_create_deployment_bundle`
Operation page: `/api/operations/seren_cloud_create_deployment_bundle`
Register a content-addressed deployment bundle before uploading raw bytes.

Request body (required):
- `application/json`: CreateCloudDeploymentBundleRequest

Responses:
- `200` Deployment bundle registered (application/json: DataResponse_CreateCloudDeploymentBundleResponse)
- `400` Bad request
- `401` Unauthorized

### GET /publishers/seren-cloud/deployment-bundles/{id}

Operation ID: `seren_cloud_get_deployment_bundle`
Operation page: `/api/operations/seren_cloud_get_deployment_bundle`
Get deployment bundle metadata without raw content.

Parameters:
- `id` (path, required): string / uuid - Deployment bundle ID

Responses:
- `200` Deployment bundle metadata (application/json: DataResponse_CloudDeploymentBundleDetail)
- `401` Unauthorized
- `404` Deployment bundle not found

### POST /publishers/seren-cloud/deployment-bundles/{id}/complete

Operation ID: `seren_cloud_complete_deployment_bundle_upload`
Operation page: `/api/operations/seren_cloud_complete_deployment_bundle_upload`
Complete a direct-to-S3 upload for a registered deployment bundle.

Parameters:
- `id` (path, required): string / uuid - Deployment bundle ID

Responses:
- `200` Deployment bundle upload completed (application/json: DataResponse_CloudDeploymentBundle)
- `400` Bad request
- `401` Unauthorized
- `404` Deployment bundle not found

### GET /publishers/seren-cloud/deployments

Operation ID: `seren_cloud_list_deployments`
Operation page: `/api/operations/seren_cloud_list_deployments`
List all deployments for the authenticated organization.

Responses:
- `200` Deployments listed (application/json: DataResponse_Vec_CloudDeploymentSummary)
- `401` Unauthorized

### DELETE /publishers/seren-cloud/deployments/{id}

Operation ID: `seren_cloud_delete`
Operation page: `/api/operations/seren_cloud_delete`
Delete a deployment and clean up runtime resources.

Parameters:
- `id` (path, required): string / uuid - Deployment ID

Responses:
- `200` Deployment deleted (application/json: DataResponse_CloudDeploymentActionStatusResponse)
- `404` Not found

### GET /publishers/seren-cloud/deployments/{id}

Operation ID: `seren_cloud_get_deployment`
Operation page: `/api/operations/seren_cloud_get_deployment`
Get details of a specific deployment.

Parameters:
- `id` (path, required): string / uuid - Deployment ID

Responses:
- `200` Deployment details (application/json: DataResponse_CloudDeploymentSummary)
- `404` Not found

### PATCH /publishers/seren-cloud/deployments/{id}

Operation ID: `seren_cloud_update_config`
Operation page: `/api/operations/seren_cloud_update_config`
Update config and/or secrets without redeploying code.

Parameters:
- `id` (path, required): string / uuid - Deployment ID

Request body (required):
- `application/json`: UpdateCloudDeploymentRequest

Responses:
- `200` Config updated (application/json: DataResponse_CloudDeploymentActionStatusResponse)
- `404` Not found

### GET /publishers/seren-cloud/deployments/{id}/audit

Operation ID: `seren_cloud_deployment_audit`
Operation page: `/api/operations/seren_cloud_deployment_audit`
List tamper-evident audit entries scoped to a deployment.

Parameters:
- `id` (path, required): string / uuid - Deployment ID
- `limit` (query): integer / int64 - Max audit entries to return (default: 50, max: 200)
- `offset` (query): integer / int64 - Pagination offset
- `action` (query): string - Filter by exact audit action
- `q` (query): string - Case-insensitive search across action, actor, and details

Responses:
- `200` Deployment audit entries listed (application/json: DataResponse_Vec_AuditEntry)
- `404` Deployment not found

### PUT /publishers/seren-cloud/deployments/{id}/connectors/{connector_ref}

Operation ID: `seren_cloud_bind_connector_secrets`
Operation page: `/api/operations/seren_cloud_bind_connector_secrets`
Bind encrypted `seren-secrets://` references to a managed agent connector.

Parameters:
- `id` (path, required): string / uuid - Deployment ID
- `connector_ref` (path, required): string - Connector catalog reference

Request body (required):
- `application/json`: BindConnectorSecretsRequest

Responses:
- `200` Connector secret references bound to the managed agent (application/json: DataResponse_BoundConnectorSecrets)
- `400` Invalid connector secret references
- `401` Unauthorized
- `403` Forbidden
- `404` Deployment or connector not found

### GET /publishers/seren-cloud/deployments/{id}/conversations

Operation ID: `seren_cloud_list_conversations`
Operation page: `/api/operations/seren_cloud_list_conversations`

Parameters:
- `id` (path, required): string / uuid - Deployment ID
- `limit` (query): integer / int64 - Max conversations to return (default: 50, max: 100)
- `cursor` (query): string - Opaque keyset cursor returned by the previous page

Responses:
- `200` Conversations listed (application/json: DataResponse_CloudConversationListResponse)
- `404` Deployment not found

### GET /publishers/seren-cloud/deployments/{id}/conversations/{conversation_id}/messages

Operation ID: `seren_cloud_get_conversation_messages`
Operation page: `/api/operations/seren_cloud_get_conversation_messages`

Parameters:
- `id` (path, required): string / uuid - Deployment ID
- `conversation_id` (path, required): string - Durable conversation ID
- `limit` (query): integer / int64 - Max messages to return (default: 50, max: 200)
- `cursor` (query): string - Opaque keyset cursor returned by the previous page
- `order` (query): ConversationMessageOrder - Message page order, asc or desc (default: desc)
- `include_run` (query): boolean - Include full run records for run-backed messages (default: true)

Responses:
- `200` Conversation messages listed (application/json: DataResponse_CloudConversationMessagesResponse)
- `404` Conversation not found

### GET /publishers/seren-cloud/deployments/{id}/deployment-bundle-download

Operation ID: `seren_cloud_get_deployment_bundle_download`
Operation page: `/api/operations/seren_cloud_get_deployment_bundle_download`
Get a short-lived direct download URL for a deployment runtime bundle.

Parameters:
- `id` (path, required): string / uuid - Deployment ID

Responses:
- `200` Deployment bundle download instructions (application/json: DataResponse_CloudDeploymentBundleDownloadResponse)
- `400` Bad request
- `401` Unauthorized
- `403` Forbidden
- `404` Deployment or bundle not found

### GET /publishers/seren-cloud/deployments/{id}/eval-drift

Operation ID: `seren_cloud_get_deployment_eval_drift`
Operation page: `/api/operations/seren_cloud_get_deployment_eval_drift`
Compare the deployment's current eval-set verdict against the baseline
captured at the last successful apply. Reports `passed`/`failed` deltas
plus an operator-safe summary message.

Parameters:
- `id` (path, required): string / uuid - Deployment ID

Responses:
- `200` Drift snapshot (application/json: DataResponse_CloudDeploymentEvalDrift)
- `400` Deployment has no eval gate configured
- `404` Not found

### GET /publishers/seren-cloud/deployments/{id}/pending_approvals

Operation ID: `seren_cloud_deployment_pending_approvals`
Operation page: `/api/operations/seren_cloud_deployment_pending_approvals`
List awaiting-approval runs for a deployment.

Parameters:
- `id` (path, required): string / uuid - Deployment ID
- `limit` (query): integer / int64 - Max runs to return (default: 50, max: 100)
- `offset` (query): integer / int64 - Pagination offset (default: 0)
- `compute_backend` (query): string - Filter by compute backend (aws_container, cloudflare_worker, daytona)
- `source` (query): string - Filter by run source (api, cli, scheduler, ui, system, unknown)
- `has_artifacts` (query): boolean - Filter runs by artifact existence
- `started_after` (query): string - Filter runs started at/after RFC3339 timestamp
- `started_before` (query): string - Filter runs started at/before RFC3339 timestamp
- `q` (query): string - Case-insensitive search across execution_id, status, source, run_name, output, metadata

Responses:
- `200` Awaiting-approval runs listed (application/json: DataResponse_Vec_CloudPendingApprovalRun)
- `404` Not found

### GET /publishers/seren-cloud/deployments/{id}/runs

Operation ID: `seren_cloud_deployment_runs`
Operation page: `/api/operations/seren_cloud_deployment_runs`
List run events (history) for a deployment.

Parameters:
- `id` (path, required): string / uuid - Deployment ID
- `limit` (query): integer / int64 - Max runs to return (default: 50, max: 100)
- `offset` (query): integer / int64 - Pagination offset (default: 0)
- `conversation_id` (query): string - Filter runs by exact conversation ID
- `status` (query): string - Repeat or comma-separate statuses: queued, running, awaiting_approval, completed, failed, cancelled, timeout, blocked, error
- `compute_backend` (query): string - Filter by compute backend (aws_container, cloudflare_worker, daytona)
- `source` (query): string - Filter by run source (api, cli, scheduler, ui, system, unknown)
- `has_artifacts` (query): boolean - Filter runs by artifact existence
- `started_after` (query): string - Filter runs started at/after RFC3339 timestamp
- `started_before` (query): string - Filter runs started at/before RFC3339 timestamp
- `q` (query): string - Case-insensitive search across execution_id, status, source, run_name, output, metadata

Responses:
- `200` Runs listed (application/json: DataResponse_Vec_CloudDeploymentRunEvent)
- `404` Not found

### POST /publishers/seren-cloud/deployments/{id}/runs

Operation ID: `seren_cloud_run`
Operation page: `/api/operations/seren_cloud_run`

Parameters:
- `id` (path, required): string / uuid - Deployment ID

Request body:
- `application/json`: null | CloudDeploymentRunRequest

Responses:
- `200` Run completed (always_on deployments) (application/json: DataResponse_CloudDeploymentRunInvocationResponse)
- `202` Run triggered (application/json: DataResponse_CloudDeploymentRunInvocationResponse)
- `402` Insufficient SerenBucks balance
- `404` Not found

### GET /publishers/seren-cloud/deployments/{id}/runs/{run_id}

Operation ID: `seren_cloud_deployment_run`
Operation page: `/api/operations/seren_cloud_deployment_run`
Get a single run event for a deployment.

Parameters:
- `id` (path, required): string / uuid - Deployment ID
- `run_id` (path, required): string / uuid - Run event ID

Responses:
- `200` Run event details (application/json: DataResponse_CloudDeploymentRunEvent)
- `404` Not found

### GET /publishers/seren-cloud/deployments/{id}/runs/{run_id}/artifacts

Operation ID: `seren_cloud_deployment_run_artifacts`
Operation page: `/api/operations/seren_cloud_deployment_run_artifacts`
List artifacts emitted by a specific deployment run.

Parameters:
- `id` (path, required): string / uuid - Deployment ID
- `run_id` (path, required): string / uuid - Run event ID
- `limit` (query): integer / int64 - Max artifacts to return (default: 50, max: 200)
- `offset` (query): integer / int64 - Pagination offset (default: 0)

Responses:
- `200` Run artifacts listed (application/json: DataResponse_Vec_CloudDeploymentRunArtifact)
- `404` Not found

### POST /publishers/seren-cloud/deployments/{id}/runs/{run_id}/cancel

Operation ID: `seren_cloud_deployment_run_cancel`
Operation page: `/api/operations/seren_cloud_deployment_run_cancel`
Cancel a queued/running deployment run.

Parameters:
- `id` (path, required): string / uuid - Deployment ID
- `run_id` (path, required): string / uuid - Run event ID

Responses:
- `200` Run cancellation requested (application/json: DataResponse_CloudDeploymentRunEvent)
- `404` Not found

### GET /publishers/seren-cloud/deployments/{id}/runs/{run_id}/evals

Operation ID: `seren_cloud_deployment_run_evals`
Operation page: `/api/operations/seren_cloud_deployment_run_evals`
List eval records linked to a specific deployment run.

Parameters:
- `id` (path, required): string / uuid - Deployment ID
- `run_id` (path, required): string / uuid - Run event ID

Responses:
- `200` Eval records linked to the run (application/json: DataResponse_CloudRunEvalsResponse)
- `404` Not found

### GET /publishers/seren-cloud/deployments/{id}/runs/{run_id}/events

Operation ID: `seren_cloud_deployment_run_events`
Operation page: `/api/operations/seren_cloud_deployment_run_events`
List structured output events emitted by a specific deployment run.

Parameters:
- `id` (path, required): string / uuid - Deployment ID
- `run_id` (path, required): string / uuid - Run event ID
- `limit` (query): integer / int64 - Max events to return (default: 100, max: 500)
- `offset` (query): integer / int64 - Pagination offset (default: 0)
- `kind` (query): string - Filter by event kind (text, thinking, tool_call_started, tool_call_completed, tool_audit, workflow, error, unknown)
- `item_id` (query): string - Filter by tool/output item ID
- `q` (query): string - Case-insensitive search across event type, kind, item ID, and payload

Responses:
- `200` Run output events listed (application/json: DataResponse_Vec_CloudRunOutputEventEnvelope)
- `404` Not found

### GET /publishers/seren-cloud/deployments/{id}/runs/{run_id}/pending_approvals

Operation ID: `seren_cloud_deployment_run_pending_approvals`
Operation page: `/api/operations/seren_cloud_deployment_run_pending_approvals`
List current pending approvals for a specific deployment run.

Parameters:
- `id` (path, required): string / uuid - Deployment ID
- `run_id` (path, required): string / uuid - Run event ID

Responses:
- `200` Current pending approvals for the run (application/json: DataResponse_CloudRunPendingApprovalsResponse)
- `404` Not found

### POST /publishers/seren-cloud/deployments/{id}/runs/{run_id}/resume

Operation ID: `seren_cloud_deployment_run_resume`
Operation page: `/api/operations/seren_cloud_deployment_run_resume`
Resume the exact managed deployment run that owns a durable checkpoint.

Parameters:
- `id` (path, required): string / uuid - Deployment ID
- `run_id` (path, required): string / uuid - Run event ID

Request body:
- `application/json`: null | CloudDeploymentRunResumeRequest

Responses:
- `200` Run resumed and recorded (application/json: DataResponse_CloudDeploymentRunEvent)
- `400` Malformed resume request or runtime rejected the request before execution
- `404` Not found
- `409` Run does not require durable resume
- `503` Deployment could not be woken for resume

### GET /publishers/seren-cloud/deployments/{id}/runs/{run_id}/state

Operation ID: `seren_cloud_deployment_run_state`
Operation page: `/api/operations/seren_cloud_deployment_run_state`
Get the current operational state for a deployment run.

Parameters:
- `id` (path, required): string / uuid - Deployment ID
- `run_id` (path, required): string / uuid - Run event ID

Responses:
- `200` Current run state (application/json: DataResponse_CloudRunLiveState)
- `404` Not found

### GET /publishers/seren-cloud/deployments/{id}/runs/{run_id}/stream

Operation ID: `seren_cloud_deployment_run_stream`
Operation page: `/api/operations/seren_cloud_deployment_run_stream`
Stream a deployment run's events as a sequenced, resumable Server-Sent Events log.

Replays run events from the client's cursor (Last-Event-ID = highest sequence already seen), emits `run.state` and `replay_complete` control frames, then tails live events. Each `run.event` frame's `id` is its monotonic sequence number, so an EventSource resumes from the last received id after a disconnect. Multiple subscribers per run are allowed.

Parameters:
- `id` (path, required): string / uuid - Deployment ID
- `run_id` (path, required): string / uuid - Run event ID
- `Last-Event-ID` (header): string | null - Highest event sequence number already received; replay resumes after it.

Responses:
- `200` SSE stream of sequenced run events (text/event-stream: unspecified)
- `404` Not found

### GET /publishers/seren-cloud/deployments/{id}/schedules

Operation ID: `seren_cloud_list_agent_schedules`
Operation page: `/api/operations/seren_cloud_list_agent_schedules`
List agent-owned future run schedules for a deployment.

Parameters:
- `id` (path, required): string / uuid - Deployment ID
- `limit` (query): integer / int64 - Max schedules to return (default: 50, max: 100)
- `offset` (query): integer / int64 - Pagination offset

Responses:
- `200` Agent schedules listed (application/json: DataResponse_Vec_CloudDeploymentAgentSchedule)
- `404` Deployment not found

### POST /publishers/seren-cloud/deployments/{id}/schedules

Operation ID: `seren_cloud_create_agent_schedule`
Operation page: `/api/operations/seren_cloud_create_agent_schedule`
Create or update an agent-owned future run schedule.

Parameters:
- `id` (path, required): string / uuid - Deployment ID

Request body (required):
- `application/json`: CloudDeploymentAgentScheduleRequest

Responses:
- `201` Agent schedule created (application/json: DataResponse_CloudDeploymentAgentSchedule)
- `400` Invalid schedule request
- `404` Deployment not found

### DELETE /publishers/seren-cloud/deployments/{id}/schedules/{schedule_id}

Operation ID: `seren_cloud_cancel_agent_schedule`
Operation page: `/api/operations/seren_cloud_cancel_agent_schedule`
Cancel an active agent-owned future run schedule.

Parameters:
- `id` (path, required): string / uuid - Deployment ID
- `schedule_id` (path, required): string / uuid - Schedule ID

Responses:
- `200` Agent schedule cancelled (application/json: DataResponse_CloudDeploymentAgentSchedule)
- `404` Deployment not found
- `409` Schedule is not active

### POST /publishers/seren-cloud/deployments/{id}/secret-refs/preview

Operation ID: `seren_cloud_preview_managed_employee_secret_refs`
Operation page: `/api/operations/seren_cloud_preview_managed_employee_secret_refs`
Preview the complete employee secret reference set without mutating the deployment.

Parameters:
- `id` (path, required): string / uuid - Deployment ID

Request body (required):
- `application/json`: PreviewManagedEmployeeSecretRefsRequest

Responses:
- `200` Complete secret reference set for delegation signing (application/json: DataResponse_ManagedEmployeeSecretRefsPreview)
- `400` Invalid employee secret references
- `401` Unauthorized
- `403` Forbidden
- `404` Deployment not found

### GET /publishers/seren-cloud/deployments/{id}/sessions

Operation ID: `seren_cloud_interactive_sessions`
Operation page: `/api/operations/seren_cloud_interactive_sessions`

Parameters:
- `id` (path, required): string / uuid - Deployment ID
- `limit` (query): integer / int64 - Max sessions to return (default: 50, max: 100)
- `offset` (query): integer / int64 - Session pagination offset
- `message_limit` (query): integer / int64 - Max messages returned per session (default: 200, max: 500)
- `message_offset` (query): integer / int64 - Message pagination offset per session
- `message_order` (query): string - Message page order, asc or desc (default: asc)

Responses:
- `200` Interactive sessions listed (application/json: DataResponse_Vec_CloudInteractiveSessionDetailResponse)
- `404` Deployment not found

### POST /publishers/seren-cloud/deployments/{id}/sessions

Operation ID: `seren_cloud_create_interactive_session`
Operation page: `/api/operations/seren_cloud_create_interactive_session`

Parameters:
- `id` (path, required): string / uuid - Deployment ID

Request body:
- `application/json`: null | CloudInteractiveSessionOpenRequest

Responses:
- `201` Interactive session created (application/json: DataResponse_CloudInteractiveSessionOpenResponse)
- `400` Bad request
- `404` Deployment not found

### GET /publishers/seren-cloud/deployments/{id}/sessions/{session_id}

Operation ID: `seren_cloud_get_interactive_session`
Operation page: `/api/operations/seren_cloud_get_interactive_session`

Parameters:
- `id` (path, required): string / uuid - Deployment ID
- `session_id` (path, required): string - Interactive session ID or durable conversation ID
- `message_limit` (query): integer / int64 - Max messages returned (default: 200, max: 500)
- `message_offset` (query): integer / int64 - Message pagination offset
- `message_order` (query): string - Message page order, asc or desc (default: asc)

Responses:
- `200` Interactive session details (application/json: DataResponse_CloudInteractiveSessionDetailResponse)
- `404` Deployment or session not found

### POST /publishers/seren-cloud/deployments/{id}/sessions/{session_id}/messages

Operation ID: `seren_cloud_post_interactive_session_message`
Operation page: `/api/operations/seren_cloud_post_interactive_session_message`

Parameters:
- `id` (path, required): string / uuid - Deployment ID
- `session_id` (path, required): string / uuid - Interactive session ID

Request body (required):
- `application/json`: CloudInteractiveSessionMessageRequest

Responses:
- `200` Duplicate interactive session message replayed (application/json: DataResponse_CloudInteractiveSessionMessageResponse)
- `202` Interactive session message accepted (application/json: DataResponse_CloudInteractiveSessionMessageResponse)
- `409` Interactive session is closed or idempotency conflict

### GET /publishers/seren-cloud/deployments/{id}/spend

Operation ID: `seren_cloud_get_deployment_spend`
Operation page: `/api/operations/seren_cloud_get_deployment_spend`
Run a one-shot invocation of a deployment.

Parameters:
- `id` (path, required): string / uuid - Deployment ID

Responses:
- `200` Aggregated spend summary (application/json: DataResponse_DeploymentSpendSummary)
- `404` Not found

### POST /publishers/seren-cloud/deployments/{id}/start

Operation ID: `seren_cloud_start`
Operation page: `/api/operations/seren_cloud_start`
Start an always-on deployment (scale to 1 replica).

Parameters:
- `id` (path, required): string / uuid - Deployment ID

Responses:
- `200` Deployment started (application/json: DataResponse_CloudDeploymentActionStatusResponse)
- `400` Bad request (not always_on)
- `402` Insufficient SerenBucks balance

### POST /publishers/seren-cloud/deployments/{id}/stop

Operation ID: `seren_cloud_stop`
Operation page: `/api/operations/seren_cloud_stop`
Stop an always-on deployment (scale to 0 replicas).

Parameters:
- `id` (path, required): string / uuid - Deployment ID

Responses:
- `200` Deployment stopped (application/json: DataResponse_CloudDeploymentActionStatusResponse)
- `400` Bad request (not always_on)

### DELETE /publishers/seren-cloud/deployments/{id}/storage

Operation ID: `seren_cloud_detach_storage`
Operation page: `/api/operations/seren_cloud_detach_storage`
Detach organization storage from a managed agent and revoke its bucket
grant.

Parameters:
- `id` (path, required): string / uuid - Deployment ID

Responses:
- `200` Storage detached from the managed agent (application/json: DataResponse_Value)
- `403` Deployment or organization storage management permission required
- `404` Deployment or storage attachment not found

### GET /publishers/seren-cloud/deployments/{id}/storage

Operation ID: `seren_cloud_get_storage`
Operation page: `/api/operations/seren_cloud_get_storage`
Get the storage attachment for a managed agent.

Parameters:
- `id` (path, required): string / uuid - Deployment ID

Responses:
- `200` Managed agent storage attachment (application/json: DataResponse_ManagedStorageAttachment)
- `401` Unauthorized
- `403` Forbidden
- `404` Deployment or storage attachment not found

### PUT /publishers/seren-cloud/deployments/{id}/storage

Operation ID: `seren_cloud_attach_storage`
Operation page: `/api/operations/seren_cloud_attach_storage`
Attach an organization storage bucket to a managed agent and optionally
keep its workspace portable across runtime restarts.

Parameters:
- `id` (path, required): string / uuid - Deployment ID

Request body (required):
- `application/json`: AttachManagedStorageRequest

Responses:
- `200` Storage attached to the managed agent (application/json: DataResponse_ManagedStorageAttachment)
- `400` Invalid storage attachment
- `403` Deployment or organization storage management permission required
- `404` Deployment or storage bucket not found

### GET /publishers/seren-cloud/environments

Operation ID: `seren_cloud_list_environments`
Operation page: `/api/operations/seren_cloud_list_environments`
List reusable execution environment profiles.

Responses:
- `200` Environments listed (application/json: DataResponse_Vec_CloudDeploymentEnvironment)

### POST /publishers/seren-cloud/environments

Operation ID: `seren_cloud_create_environment`
Operation page: `/api/operations/seren_cloud_create_environment`
Create a reusable execution environment profile.

Request body (required):
- `application/json`: CreateCloudDeploymentEnvironmentRequest

Responses:
- `200` Environment created (application/json: DataResponse_CloudDeploymentEnvironment)
- `400` Bad request

### DELETE /publishers/seren-cloud/environments/{id}

Operation ID: `seren_cloud_delete_environment`
Operation page: `/api/operations/seren_cloud_delete_environment`
Delete a reusable execution environment profile.

Parameters:
- `id` (path, required): string / uuid - Environment ID

Responses:
- `204` Environment deleted
- `404` Not found

### GET /publishers/seren-cloud/environments/{id}

Operation ID: `seren_cloud_get_environment`
Operation page: `/api/operations/seren_cloud_get_environment`
Get a reusable execution environment profile.

Parameters:
- `id` (path, required): string / uuid - Environment ID

Responses:
- `200` Environment details (application/json: DataResponse_CloudDeploymentEnvironment)
- `404` Not found

### PATCH /publishers/seren-cloud/environments/{id}

Operation ID: `seren_cloud_update_environment`
Operation page: `/api/operations/seren_cloud_update_environment`
Update a reusable execution environment profile.

Parameters:
- `id` (path, required): string / uuid - Environment ID

Request body (required):
- `application/json`: UpdateCloudDeploymentEnvironmentRequest

Responses:
- `200` Environment updated (application/json: DataResponse_CloudDeploymentEnvironment)
- `404` Not found

### GET /publishers/seren-cloud/eval-sets

Operation ID: `seren_cloud_eval_sets`
Operation page: `/api/operations/seren_cloud_eval_sets`
List eval sets for the authenticated organization.

Parameters:
- `deployment_id` (query): string / uuid - Optional deployment scope
- `limit` (query): integer / int64 - Max eval sets to return (default: 50, max: 200)
- `offset` (query): integer / int64 - Pagination offset

Responses:
- `200` Eval sets listed (application/json: DataResponse_Vec_CloudEvalSet)

### POST /publishers/seren-cloud/eval-sets

Operation ID: `seren_cloud_create_eval_set`
Operation page: `/api/operations/seren_cloud_create_eval_set`
Create a durable eval set for seren-cloud runs.

Request body (required):
- `application/json`: CreateCloudEvalSetRequest

Responses:
- `201` Eval set created (application/json: DataResponse_CloudEvalSet)
- `400` Bad request
- `404` Deployment not found

### GET /publishers/seren-cloud/eval-sets/{id}

Operation ID: `seren_cloud_get_eval_set`
Operation page: `/api/operations/seren_cloud_get_eval_set`
Get a single eval set.

Parameters:
- `id` (path, required): string / uuid - Eval set ID

Responses:
- `200` Eval set details (application/json: DataResponse_CloudEvalSet)
- `404` Eval set not found

### PUT /publishers/seren-cloud/eval-sets/{id}

Operation ID: `seren_cloud_update_eval_set`
Operation page: `/api/operations/seren_cloud_update_eval_set`
Replace an eval set definition, including schedule and criteria.

Parameters:
- `id` (path, required): string / uuid - Eval set ID

Request body (required):
- `application/json`: UpdateCloudEvalSetRequest

Responses:
- `200` Eval set updated (application/json: DataResponse_CloudEvalSet)
- `400` Bad request
- `404` Eval set or deployment not found

### GET /publishers/seren-cloud/eval-sets/{id}/cases

Operation ID: `seren_cloud_eval_cases`
Operation page: `/api/operations/seren_cloud_eval_cases`
List eval cases within a set.

Parameters:
- `id` (path, required): string / uuid - Eval set ID
- `limit` (query): integer / int64 - Max eval cases to return (default: 50, max: 200)
- `offset` (query): integer / int64 - Pagination offset

Responses:
- `200` Eval cases listed (application/json: DataResponse_Vec_CloudEvalCase)
- `404` Eval set not found

### GET /publishers/seren-cloud/eval-sets/{id}/cases/{case_id}

Operation ID: `seren_cloud_get_eval_case`
Operation page: `/api/operations/seren_cloud_get_eval_case`
Get a single eval case.

Parameters:
- `id` (path, required): string / uuid - Eval set ID
- `case_id` (path, required): string / uuid - Eval case ID

Responses:
- `200` Eval case details (application/json: DataResponse_CloudEvalCase)
- `404` Eval case not found

### POST /publishers/seren-cloud/eval-sets/{id}/cases/from-run/{run_id}

Operation ID: `seren_cloud_promote_run_to_eval_case`
Operation page: `/api/operations/seren_cloud_promote_run_to_eval_case`
Promote a terminal run into a durable eval case.

Parameters:
- `id` (path, required): string / uuid - Eval set ID
- `run_id` (path, required): string / uuid - Source run event ID

Request body (required):
- `application/json`: PromoteRunToCloudEvalCaseRequest

Responses:
- `201` Eval case created (application/json: DataResponse_CloudEvalCase)
- `400` Bad request
- `404` Eval set or run not found

### GET /publishers/seren-cloud/eval-sets/{id}/runs

Operation ID: `seren_cloud_eval_runs`
Operation page: `/api/operations/seren_cloud_eval_runs`
List eval runs within a set.

Parameters:
- `id` (path, required): string / uuid - Eval set ID
- `limit` (query): integer / int64 - Max eval runs to return (default: 50, max: 200)
- `offset` (query): integer / int64 - Pagination offset

Responses:
- `200` Eval runs listed (application/json: DataResponse_Vec_CloudEvalRun)
- `404` Eval set not found

### POST /publishers/seren-cloud/eval-sets/{id}/runs

Operation ID: `seren_cloud_run_eval_set`
Operation page: `/api/operations/seren_cloud_run_eval_set`
Execute an eval set against a deployment.

Parameters:
- `id` (path, required): string / uuid - Eval set ID

Request body (required):
- `application/json`: CreateCloudEvalRunRequest

Responses:
- `202` Eval run accepted (application/json: DataResponse_CloudEvalRun)
- `400` Bad request
- `404` Eval set or deployment not found

### GET /publishers/seren-cloud/eval-sets/{id}/runs/{run_id}

Operation ID: `seren_cloud_get_eval_run`
Operation page: `/api/operations/seren_cloud_get_eval_run`
Get a single eval run.

Parameters:
- `id` (path, required): string / uuid - Eval set ID
- `run_id` (path, required): string / uuid - Eval run ID

Responses:
- `200` Eval run details (application/json: DataResponse_CloudEvalRun)
- `404` Eval run not found

### GET /publishers/seren-cloud/eval-sets/{id}/runs/{run_id}/results

Operation ID: `seren_cloud_eval_run_results`
Operation page: `/api/operations/seren_cloud_eval_run_results`
List case results for an eval run.

Parameters:
- `id` (path, required): string / uuid - Eval set ID
- `run_id` (path, required): string / uuid - Eval run ID
- `limit` (query): integer / int64 - Max case results to return (default: 50, max: 200)
- `offset` (query): integer / int64 - Pagination offset

Responses:
- `200` Eval case results listed (application/json: DataResponse_Vec_CloudEvalCaseResult)
- `404` Eval run not found

### GET /publishers/seren-cloud/eval-sets/{id}/runs/{run_id}/results/{case_id}

Operation ID: `seren_cloud_get_eval_case_result`
Operation page: `/api/operations/seren_cloud_get_eval_case_result`
Get a single case result from an eval run.

Parameters:
- `id` (path, required): string / uuid - Eval set ID
- `run_id` (path, required): string / uuid - Eval run ID
- `case_id` (path, required): string / uuid - Eval case ID

Responses:
- `200` Eval case result details (application/json: DataResponse_CloudEvalCaseResult)
- `404` Eval case result not found

### GET /publishers/seren-cloud/inbox/approvals

Operation ID: `seren_cloud_approval_inbox_list`
Operation page: `/api/operations/seren_cloud_approval_inbox_list`
List every awaiting approval the operator owns across all approval kinds.

Returns `ToolCall` entries (derived from `awaiting_approval` runs) and
`BlockedEgress` entries (from `blocked_egress_inbox_entries`) merged into
a single timeline ordered by `created_at DESC`. Pagination is cursor-only:
the response includes `next_cursor` when more entries are available, and
the caller passes it back in `?cursor=`.

Parameters:
- `limit` (query): integer / int64 - Max entries per page (default: 50, max: 100)
- `cursor` (query): string - Opaque cursor from a previous response. Cursors expire after 24h; reject malformed or expired cursors with 400.

Responses:
- `200` Approval inbox entries (application/json: DataResponse_ApprovalInboxListResponse)
- `400` Malformed limit or cursor
- `401` Unauthorized

### POST /publishers/seren-cloud/inbox/approvals/{entry_id}/decide

Operation ID: `seren_cloud_approval_inbox_decide`
Operation page: `/api/operations/seren_cloud_approval_inbox_decide`
Record an operator approve/deny decision for a single inbox entry.

Tool-call entries record an audit row and rely on the existing run-resume
flow to emit the `approval_decision` event. Blocked-egress entries flip
the row's `decision_state` so the runtime wait long-poll releases or
drops the corresponding request on its next tick. Re-deciding an
already-terminal blocked-egress row returns the current state instead of
409 so the agent runtime's at-least-once retries are idempotent.

Parameters:
- `entry_id` (path, required): string - Inbox-scoped entry id (e.g. tool:<run>:<call_id>)

Request body (required):
- `application/json`: ApprovalInboxDecisionRequest

Responses:
- `200` Decision recorded (application/json: DataResponse_ApprovalInboxDecisionResponse)
- `400` Malformed body
- `401` Unauthorized
- `403` Forbidden
- `404` Inbox entry not found
- `409` Entry no longer pending

### GET /publishers/seren-cloud/pending_approvals

Operation ID: `seren_cloud_pending_approvals`
Operation page: `/api/operations/seren_cloud_pending_approvals`
List awaiting-approval runs across all deployments for the organization.

Parameters:
- `limit` (query): integer / int64 - Max runs to return (default: 50, max: 100)
- `offset` (query): integer / int64 - Pagination offset (default: 0)
- `compute_backend` (query): string - Filter by compute backend (aws_container, cloudflare_worker, daytona)
- `source` (query): string - Filter by run source (api, cli, scheduler, ui, system, unknown)
- `has_artifacts` (query): boolean - Filter runs by artifact existence
- `started_after` (query): string - Filter runs started at/after RFC3339 timestamp
- `started_before` (query): string - Filter runs started at/before RFC3339 timestamp
- `q` (query): string - Case-insensitive search across execution_id, status, source, run_name, output, metadata

Responses:
- `200` Awaiting-approval runs listed (application/json: DataResponse_Vec_CloudPendingApprovalRun)
- `401` Unauthorized

### GET /publishers/seren-cloud/runs

Operation ID: `seren_cloud_runs`
Operation page: `/api/operations/seren_cloud_runs`
List all runs across all deployments for the organization.

Parameters:
- `limit` (query): integer / int64 - Max runs to return (default: 50, max: 100)
- `offset` (query): integer / int64 - Pagination offset (default: 0)
- `conversation_id` (query): string - Filter runs by exact conversation ID
- `status` (query): string - Repeat or comma-separate statuses: queued, running, awaiting_approval, completed, failed, cancelled, timeout, blocked, error
- `compute_backend` (query): string - Filter by compute backend (aws_container, cloudflare_worker, daytona)
- `source` (query): string - Filter by run source (api, cli, scheduler, ui, system, unknown)
- `has_artifacts` (query): boolean - Filter runs by artifact existence
- `started_after` (query): string - Filter runs started at/after RFC3339 timestamp
- `started_before` (query): string - Filter runs started at/before RFC3339 timestamp
- `q` (query): string - Case-insensitive search across execution_id, status, source, run_name, output, metadata

Responses:
- `200` All runs listed (application/json: DataResponse_Vec_CloudDeploymentRunEvent)
- `401` Unauthorized

### GET /publishers/seren-cloud/runs/{run_id}

Operation ID: `seren_cloud_run_detail`
Operation page: `/api/operations/seren_cloud_run_detail`
Get a single run event by ID (cross-agent).

Parameters:
- `run_id` (path, required): string / uuid - Run event ID

Responses:
- `200` Run event details (application/json: DataResponse_CloudDeploymentRunEvent)
- `404` Not found

### GET /publishers/seren-cloud/runs/{run_id}/artifacts

Operation ID: `seren_cloud_run_artifacts`
Operation page: `/api/operations/seren_cloud_run_artifacts`
List artifacts emitted by a run event.

Parameters:
- `run_id` (path, required): string / uuid - Run event ID
- `limit` (query): integer / int64 - Max artifacts to return (default: 50, max: 200)
- `offset` (query): integer / int64 - Pagination offset (default: 0)

Responses:
- `200` Run artifacts listed (application/json: DataResponse_Vec_CloudDeploymentRunArtifact)
- `404` Not found

### GET /publishers/seren-cloud/runs/{run_id}/audit

Operation ID: `seren_cloud_run_audit`
Operation page: `/api/operations/seren_cloud_run_audit`
List tamper-evident audit entries scoped to a run.

Parameters:
- `run_id` (path, required): string / uuid - Run event ID
- `limit` (query): integer / int64 - Max audit entries to return (default: 50, max: 200)
- `offset` (query): integer / int64 - Pagination offset
- `action` (query): string - Filter by exact audit action
- `q` (query): string - Case-insensitive search across action, actor, and details

Responses:
- `200` Run audit entries listed (application/json: DataResponse_Vec_AuditEntry)
- `404` Run event not found

### POST /publishers/seren-cloud/runs/{run_id}/cancel

Operation ID: `seren_cloud_run_cancel`
Operation page: `/api/operations/seren_cloud_run_cancel`
Cancel a queued/running run by ID.

Parameters:
- `run_id` (path, required): string / uuid - Run event ID

Responses:
- `200` Run cancellation requested (application/json: DataResponse_CloudDeploymentRunEvent)
- `404` Not found

### GET /publishers/seren-cloud/runs/{run_id}/compare/{compare_run_id}

Operation ID: `seren_cloud_run_compare`
Operation page: `/api/operations/seren_cloud_run_compare`
Compare two run replay/eval captures by ID (cross-agent).

Parameters:
- `run_id` (path, required): string / uuid - Baseline run event ID
- `compare_run_id` (path, required): string / uuid - Candidate run event ID

Responses:
- `200` Replay comparison summary (application/json: DataResponse_CloudRunReplayComparison)
- `404` Not found

### GET /publishers/seren-cloud/runs/{run_id}/evals

Operation ID: `seren_cloud_run_evals`
Operation page: `/api/operations/seren_cloud_run_evals`
List eval records linked to a run event.

Parameters:
- `run_id` (path, required): string / uuid - Run event ID

Responses:
- `200` Eval records linked to the run (application/json: DataResponse_CloudRunEvalsResponse)
- `404` Not found

### GET /publishers/seren-cloud/runs/{run_id}/events

Operation ID: `seren_cloud_run_events`
Operation page: `/api/operations/seren_cloud_run_events`
List structured output events emitted by a run event.

Parameters:
- `run_id` (path, required): string / uuid - Run event ID
- `limit` (query): integer / int64 - Max events to return (default: 100, max: 500)
- `offset` (query): integer / int64 - Pagination offset (default: 0)
- `kind` (query): string - Filter by event kind (text, thinking, tool_call_started, tool_call_completed, tool_audit, workflow, error, unknown)
- `item_id` (query): string - Filter by tool/output item ID
- `q` (query): string - Case-insensitive search across event type, kind, item ID, and payload

Responses:
- `200` Run output events listed (application/json: DataResponse_Vec_CloudRunOutputEventEnvelope)
- `404` Not found

### GET /publishers/seren-cloud/runs/{run_id}/pending_approvals

Operation ID: `seren_cloud_run_pending_approvals`
Operation page: `/api/operations/seren_cloud_run_pending_approvals`
List current pending approvals for a run event.

Parameters:
- `run_id` (path, required): string / uuid - Run event ID

Responses:
- `200` Current pending approvals for the run (application/json: DataResponse_CloudRunPendingApprovalsResponse)
- `404` Not found

### POST /publishers/seren-cloud/runs/{run_id}/resume

Operation ID: `seren_cloud_run_resume`
Operation page: `/api/operations/seren_cloud_run_resume`
Resume the exact managed run that owns a durable checkpoint.

Parameters:
- `run_id` (path, required): string / uuid - Run event ID

Request body:
- `application/json`: null | CloudDeploymentRunResumeRequest

Responses:
- `200` Run resumed and recorded (application/json: DataResponse_CloudDeploymentRunEvent)
- `400` Malformed resume request or runtime rejected the request before execution
- `404` Not found
- `409` Run does not require durable resume
- `503` Deployment could not be woken for resume

### GET /publishers/seren-cloud/runs/{run_id}/state

Operation ID: `seren_cloud_run_state`
Operation page: `/api/operations/seren_cloud_run_state`
Get the current operational state for a run event.

Parameters:
- `run_id` (path, required): string / uuid - Run event ID

Responses:
- `200` Current run state (application/json: DataResponse_CloudRunLiveState)
- `404` Not found

### GET /publishers/seren-cloud/runs/{run_id}/stream

Operation ID: `seren_cloud_run_stream`
Operation page: `/api/operations/seren_cloud_run_stream`
Stream a run's events as a sequenced, resumable Server-Sent Events log.

Replays run events from the client's cursor (Last-Event-ID = highest sequence already seen), emits `run.state` and `replay_complete` control frames, then tails live events. Each `run.event` frame's `id` is its monotonic sequence number, so an EventSource resumes from the last received id after a disconnect. Multiple subscribers per run are allowed.

Parameters:
- `run_id` (path, required): string / uuid - Run event ID
- `Last-Event-ID` (header): string | null - Highest event sequence number already received; replay resumes after it.

Responses:
- `200` SSE stream of sequenced run events (text/event-stream: unspecified)
- `404` Not found

### GET /publishers/seren-cloud/storage/buckets

Operation ID: `seren_cloud_list_storage_buckets`
Operation page: `/api/operations/seren_cloud_list_storage_buckets`
List organization storage buckets that can be attached to a managed agent.

Responses:
- `200` Organization storage buckets (application/json: DataResponse_Vec_ManagedStorageBucket)
- `401` Unauthorized
- `403` Forbidden
- `502` Storage is temporarily unavailable

## seren-db

### GET /publishers/seren-db/projects

Operation ID: `seren_db_list_projects`
Operation page: `/api/operations/seren_db_list_projects`
List all projects in the organization.

Responses:
- `200` Projects listed (application/json: PaginatedProjectResponse)
- `401` Unauthorized

### POST /publishers/seren-db/projects

Operation ID: `seren_db_create_project`
Operation page: `/api/operations/seren_db_create_project`
Create a new SerenDB project.

Request body (required):
- `application/json`: CreateProjectRequest

Responses:
- `201` Project created (application/json: ProjectCreatedResponse)
- `400` Bad request
- `401` Unauthorized

### DELETE /publishers/seren-db/projects/{id}

Operation ID: `seren_db_delete_project`
Operation page: `/api/operations/seren_db_delete_project`
Delete a project.

Parameters:
- `id` (path, required): string / uuid - Project ID

Responses:
- `200` Project deleted (application/json: DataResponse_Value)
- `404` Not found

### GET /publishers/seren-db/projects/{id}

Operation ID: `seren_db_get_project`
Operation page: `/api/operations/seren_db_get_project`
Get a project by ID.

Parameters:
- `id` (path, required): string / uuid - Project ID

Responses:
- `200` Project retrieved (application/json: ProjectResponse)
- `404` Not found

### PATCH /publishers/seren-db/projects/{id}

Operation ID: `seren_db_update_project`
Operation page: `/api/operations/seren_db_update_project`
Update a project.

Parameters:
- `id` (path, required): string / uuid - Project ID

Request body (required):
- `application/json`: UpdateProjectRequest

Responses:
- `200` Project updated (application/json: ProjectResponse)
- `404` Not found

### GET /publishers/seren-db/projects/{id}/branch-protection

Operation ID: `seren_db_list_branch_protection_rules`
Operation page: `/api/operations/seren_db_list_branch_protection_rules`
List branch protection rules for a project.

Parameters:
- `id` (path, required): string / uuid - Project ID

Responses:
- `200` Branch protection rules listed (application/json: DataResponse_Vec_BranchProtection)
- `404` Not found

### GET /publishers/seren-db/projects/{id}/branches

Operation ID: `seren_db_list_branches`
Operation page: `/api/operations/seren_db_list_branches`
List all branches in a project.

Parameters:
- `id` (path, required): string / uuid - Project ID

Responses:
- `200` Branches listed (application/json: BranchesResponse)

### POST /publishers/seren-db/projects/{id}/branches

Operation ID: `seren_db_create_branch`
Operation page: `/api/operations/seren_db_create_branch`
Create a new branch in a project.

Parameters:
- `id` (path, required): string / uuid - Project ID

Request body (required):
- `application/json`: CreateBranchRequest

Responses:
- `201` Branch created (application/json: BranchCreationResultResponse)
- `400` Bad request

### DELETE /publishers/seren-db/projects/{id}/branches/{bid}

Operation ID: `seren_db_delete_branch`
Operation page: `/api/operations/seren_db_delete_branch`
Delete a branch.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID

Responses:
- `200` Branch deleted (application/json: DataResponse_Value)
- `404` Not found

### GET /publishers/seren-db/projects/{id}/branches/{bid}

Operation ID: `seren_db_get_branch`
Operation page: `/api/operations/seren_db_get_branch`
Get a specific branch.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID

Responses:
- `200` Branch retrieved (application/json: BranchResponse)
- `404` Not found

### PATCH /publishers/seren-db/projects/{id}/branches/{bid}

Operation ID: `seren_db_rename_branch`
Operation page: `/api/operations/seren_db_rename_branch`
Rename a branch.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID

Request body (required):
- `application/json`: RenameBranchRequest

Responses:
- `200` Branch renamed (application/json: BranchResponse)
- `404` Not found

### PATCH /publishers/seren-db/projects/{id}/branches/{bid}/archived

Operation ID: `seren_db_set_branch_archived`
Operation page: `/api/operations/seren_db_set_branch_archived`
Set a branch archived state.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID

Request body (required):
- `application/json`: SetBranchArchivedRequest

Responses:
- `200` Branch archived state updated (application/json: DataResponse_Value)
- `404` Not found

### GET /publishers/seren-db/projects/{id}/branches/{bid}/connection-string

Operation ID: `seren_db_get_connection_string`
Operation page: `/api/operations/seren_db_get_connection_string`
Get a branch connection string.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID
- `pooled` (query): boolean - Use pooled connection if true
- `role` (query): string - Optional role name override
- `database` (query): string - Optional database name override

Responses:
- `200` Connection string retrieved (application/json: DataResponse_ConnectionString)
- `404` Not found

### GET /publishers/seren-db/projects/{id}/branches/{bid}/databases

Operation ID: `seren_db_list_databases`
Operation page: `/api/operations/seren_db_list_databases`
List all databases on a branch.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID

Responses:
- `200` Databases listed (application/json: DatabasesWithOwnerResponse)

### POST /publishers/seren-db/projects/{id}/branches/{bid}/databases

Operation ID: `seren_db_create_database`
Operation page: `/api/operations/seren_db_create_database`
Create a new database on a branch.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID

Request body (required):
- `application/json`: CreateDatabaseRequest

Responses:
- `201` Database created (application/json: DatabaseCreatedResponse)
- `400` Bad request

### DELETE /publishers/seren-db/projects/{id}/branches/{bid}/databases/{did}

Operation ID: `seren_db_delete_database`
Operation page: `/api/operations/seren_db_delete_database`
Delete a database.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID
- `did` (path, required): string / uuid - Database ID

Responses:
- `200` Database deleted (application/json: DataResponse_Value)
- `404` Not found

### GET /publishers/seren-db/projects/{id}/branches/{bid}/databases/{did}

Operation ID: `seren_db_get_database`
Operation page: `/api/operations/seren_db_get_database`
Get a specific database.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID
- `did` (path, required): string / uuid - Database ID

Responses:
- `200` Database retrieved (application/json: DatabaseWithOwnerResponse)
- `404` Not found

### PUT /publishers/seren-db/projects/{id}/branches/{bid}/databases/{did}

Operation ID: `seren_db_update_database`
Operation page: `/api/operations/seren_db_update_database`
Update a database (change owner).

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID
- `did` (path, required): string / uuid - Database ID

Request body (required):
- `application/json`: UpdateDatabaseRequest

Responses:
- `200` Database updated (application/json: DatabaseWithOwnerResponse)
- `404` Not found

### GET /publishers/seren-db/projects/{id}/branches/{bid}/details

Operation ID: `seren_db_get_branch_details`
Operation page: `/api/operations/seren_db_get_branch_details`
Get branch details.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID

Responses:
- `200` Branch details retrieved (application/json: DataResponse_BranchDetail)
- `404` Not found

### GET /publishers/seren-db/projects/{id}/branches/{bid}/endpoints

Operation ID: `seren_db_list_endpoints`
Operation page: `/api/operations/seren_db_list_endpoints`
List all endpoints on a branch.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID

Responses:
- `200` Endpoints listed (application/json: DataResponse_Vec_EndpointResponse)

### POST /publishers/seren-db/projects/{id}/branches/{bid}/endpoints

Operation ID: `seren_db_create_endpoint`
Operation page: `/api/operations/seren_db_create_endpoint`
Create a new compute endpoint on a branch.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID

Request body (required):
- `application/json`: CreateEndpointRequest

Responses:
- `201` Endpoint created (application/json: EndpointCreatedResponse)
- `400` Bad request

### DELETE /publishers/seren-db/projects/{id}/branches/{bid}/endpoints/{eid}

Operation ID: `seren_db_delete_endpoint`
Operation page: `/api/operations/seren_db_delete_endpoint`
Delete an endpoint.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID
- `eid` (path, required): string / uuid - Endpoint ID

Responses:
- `200` Endpoint deleted (application/json: DataResponse_Value)
- `404` Not found

### PATCH /publishers/seren-db/projects/{id}/branches/{bid}/endpoints/{eid}

Operation ID: `seren_db_update_endpoint`
Operation page: `/api/operations/seren_db_update_endpoint`
Update an endpoint's settings.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID
- `eid` (path, required): string / uuid - Endpoint ID

Request body (required):
- `application/json`: UpdateEndpointRequest

Responses:
- `200` Endpoint updated (application/json: DataResponse_EndpointResponse)
- `404` Not found

### GET /publishers/seren-db/projects/{id}/branches/{bid}/endpoints/{eid}/health

Operation ID: `seren_db_get_endpoint_health`
Operation page: `/api/operations/seren_db_get_endpoint_health`
Get endpoint health.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID
- `eid` (path, required): string / uuid - Endpoint ID

Responses:
- `200` Endpoint health retrieved (application/json: DataResponse_Value)
- `404` Not found

### GET /publishers/seren-db/projects/{id}/branches/{bid}/endpoints/{eid}/metrics

Operation ID: `seren_db_get_endpoint_metrics`
Operation page: `/api/operations/seren_db_get_endpoint_metrics`
Get endpoint metrics.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID
- `eid` (path, required): string / uuid - Endpoint ID

Responses:
- `200` Endpoint metrics retrieved (application/json: DataResponse_Value)
- `404` Not found

### POST /publishers/seren-db/projects/{id}/branches/{bid}/endpoints/{eid}/start

Operation ID: `seren_db_start_endpoint`
Operation page: `/api/operations/seren_db_start_endpoint`
Start a suspended endpoint.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID
- `eid` (path, required): string / uuid - Endpoint ID

Responses:
- `200` Endpoint started (application/json: EndpointStatusInfoResponse)
- `404` Not found

### GET /publishers/seren-db/projects/{id}/branches/{bid}/endpoints/{eid}/status

Operation ID: `seren_db_get_endpoint_status`
Operation page: `/api/operations/seren_db_get_endpoint_status`
Get endpoint status.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID
- `eid` (path, required): string / uuid - Endpoint ID

Responses:
- `200` Endpoint status (application/json: EndpointStatusInfoResponse)
- `404` Not found

### POST /publishers/seren-db/projects/{id}/branches/{bid}/endpoints/{eid}/stop

Operation ID: `seren_db_stop_endpoint`
Operation page: `/api/operations/seren_db_stop_endpoint`
Stop (suspend) an endpoint.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID
- `eid` (path, required): string / uuid - Endpoint ID

Responses:
- `200` Endpoint stopped (application/json: EndpointStatusInfoResponse)
- `404` Not found

### PATCH /publishers/seren-db/projects/{id}/branches/{bid}/expiration

Operation ID: `seren_db_set_branch_expiration`
Operation page: `/api/operations/seren_db_set_branch_expiration`
Set branch expiration.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID

Request body (required):
- `application/json`: SetBranchExpirationRequest

Responses:
- `200` Branch expiration set (application/json: DataResponse_Value)
- `404` Not found

### GET /publishers/seren-db/projects/{id}/branches/{bid}/lsn_by_timestamp

Operation ID: `seren_db_get_lsn_by_timestamp`
Operation page: `/api/operations/seren_db_get_lsn_by_timestamp`
Get LSN by timestamp for a branch.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID
- `timestamp` (query, required): string - Timestamp in ISO-8601 format

Responses:
- `200` LSN retrieved (application/json: DataResponse_LsnByTimestamp)
- `404` Not found

### DELETE /publishers/seren-db/projects/{id}/branches/{bid}/protection

Operation ID: `seren_db_delete_branch_protection`
Operation page: `/api/operations/seren_db_delete_branch_protection`
Delete branch protection rule for a branch.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID

Responses:
- `204` Branch protection rule deleted
- `404` Not found

### GET /publishers/seren-db/projects/{id}/branches/{bid}/protection

Operation ID: `seren_db_get_branch_protection`
Operation page: `/api/operations/seren_db_get_branch_protection`
Get branch protection rule for a branch.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID

Responses:
- `200` Branch protection rule retrieved (application/json: DataResponse_BranchProtection)
- `404` Not found

### PATCH /publishers/seren-db/projects/{id}/branches/{bid}/protection

Operation ID: `seren_db_update_branch_protection`
Operation page: `/api/operations/seren_db_update_branch_protection`
Update branch protection rule for a branch.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID

Request body (required):
- `application/json`: UpdateBranchProtectionRequest

Responses:
- `200` Branch protection rule updated (application/json: DataResponse_BranchProtection)
- `404` Not found

### POST /publishers/seren-db/projects/{id}/branches/{bid}/protection

Operation ID: `seren_db_create_branch_protection`
Operation page: `/api/operations/seren_db_create_branch_protection`
Create branch protection rule for a branch.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID

Request body (required):
- `application/json`: CreateBranchProtectionRequest

Responses:
- `201` Branch protection rule created (application/json: DataResponse_BranchProtection)
- `404` Not found

### GET /publishers/seren-db/projects/{id}/branches/{bid}/publications

Operation ID: `seren_db_list_publications`
Operation page: `/api/operations/seren_db_list_publications`
List publications for a branch.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID

Responses:
- `200` Publications listed (application/json: DataResponse_Vec_PublicationInfo)
- `404` Not found

### POST /publishers/seren-db/projects/{id}/branches/{bid}/publications

Operation ID: `seren_db_create_publication`
Operation page: `/api/operations/seren_db_create_publication`
Create a publication for a branch.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID

Request body (required):
- `application/json`: CreatePublicationRequest

Responses:
- `201` Publication created (application/json: DataResponse_PublicationInfo)
- `404` Not found

### DELETE /publishers/seren-db/projects/{id}/branches/{bid}/publications/{publication_id}

Operation ID: `seren_db_delete_publication`
Operation page: `/api/operations/seren_db_delete_publication`
Delete a publication from a branch.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID
- `publication_id` (path, required): string / uuid - Publication ID

Responses:
- `204` Publication deleted
- `404` Not found

### PATCH /publishers/seren-db/projects/{id}/branches/{bid}/publications/{publication_id}

Operation ID: `seren_db_update_publication`
Operation page: `/api/operations/seren_db_update_publication`
Update a publication for a branch.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID
- `publication_id` (path, required): string / uuid - Publication ID

Request body (required):
- `application/json`: UpdatePublicationRequest

Responses:
- `200` Publication updated (application/json: DataResponse_PublicationInfo)
- `404` Not found

### GET /publishers/seren-db/projects/{id}/branches/{bid}/replication-slots

Operation ID: `seren_db_list_replication_slots`
Operation page: `/api/operations/seren_db_list_replication_slots`
List replication slots for a branch.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID

Responses:
- `200` Replication slots listed (application/json: DataResponse_Vec_ReplicationSlotInfo)
- `404` Not found

### POST /publishers/seren-db/projects/{id}/branches/{bid}/replication-slots

Operation ID: `seren_db_create_replication_slot`
Operation page: `/api/operations/seren_db_create_replication_slot`
Create a replication slot for a branch.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID

Request body (required):
- `application/json`: CreateReplicationSlotRequest

Responses:
- `201` Replication slot created (application/json: DataResponse_ReplicationSlotInfo)
- `404` Not found

### DELETE /publishers/seren-db/projects/{id}/branches/{bid}/replication-slots/{slot_id}

Operation ID: `seren_db_delete_replication_slot`
Operation page: `/api/operations/seren_db_delete_replication_slot`
Delete a replication slot from a branch.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID
- `slot_id` (path, required): string / uuid - Replication slot ID

Responses:
- `204` Replication slot deleted
- `404` Not found

### POST /publishers/seren-db/projects/{id}/branches/{bid}/reset

Operation ID: `seren_db_reset_branch`
Operation page: `/api/operations/seren_db_reset_branch`
Reset a branch.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID

Request body (required):
- `application/json`: ResetBranchRequest

Responses:
- `200` Branch reset (application/json: BranchResponse)
- `404` Not found

### POST /publishers/seren-db/projects/{id}/branches/{bid}/restore

Operation ID: `seren_db_restore_branch`
Operation page: `/api/operations/seren_db_restore_branch`
Restore a branch.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID

Request body (required):
- `application/json`: RestoreBranchRequest

Responses:
- `200` Branch restored (application/json: DataResponse_BranchRestored)
- `404` Not found

### GET /publishers/seren-db/projects/{id}/branches/{bid}/roles

Operation ID: `seren_db_list_roles`
Operation page: `/api/operations/seren_db_list_roles`
List all roles on a branch.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID

Responses:
- `200` Roles listed (application/json: RoleInfosResponse)

### POST /publishers/seren-db/projects/{id}/branches/{bid}/roles

Operation ID: `seren_db_create_role`
Operation page: `/api/operations/seren_db_create_role`
Create a new role on a branch.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID

Request body (required):
- `application/json`: CreateDbRoleRequest

Responses:
- `201` Role created (application/json: RoleCreatedResponse)
- `400` Bad request

### DELETE /publishers/seren-db/projects/{id}/branches/{bid}/roles/{rid}

Operation ID: `seren_db_delete_role`
Operation page: `/api/operations/seren_db_delete_role`
Delete a role from a branch.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID
- `rid` (path, required): string / uuid - Role ID

Responses:
- `200` Role deleted (application/json: DataResponse_Value)
- `404` Not found

### POST /publishers/seren-db/projects/{id}/branches/{bid}/roles/{rid}/reset_password

Operation ID: `seren_db_reset_role_password`
Operation page: `/api/operations/seren_db_reset_role_password`
Reset a role's password.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID
- `rid` (path, required): string / uuid - Role ID

Responses:
- `200` Password reset (application/json: RolePasswordResetResponse)
- `404` Not found

### GET /publishers/seren-db/projects/{id}/branches/{bid}/roles/{role_name}/reveal_password

Operation ID: `seren_db_reveal_role_password`
Operation page: `/api/operations/seren_db_reveal_role_password`
Reveal a role password by role name.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID
- `role_name` (path, required): string - Role name

Responses:
- `200` Role password revealed (application/json: RolePasswordResetResponse)
- `404` Not found

### POST /publishers/seren-db/projects/{id}/branches/{bid}/set_as_default

Operation ID: `seren_db_set_default_branch_alias`
Operation page: `/api/operations/seren_db_set_default_branch_alias`
Set a branch as default using set_as_default alias.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID

Responses:
- `200` Branch set as default (application/json: DataResponse_Value)
- `404` Not found

### POST /publishers/seren-db/projects/{id}/branches/{bid}/set-default

Operation ID: `seren_db_set_default_branch`
Operation page: `/api/operations/seren_db_set_default_branch`
Set a branch as the default for its project.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID

Responses:
- `200` Branch set as default (application/json: DataResponse_Value)
- `404` Not found

### GET /publishers/seren-db/projects/{id}/branches/{bid}/timestamp_by_lsn

Operation ID: `seren_db_get_timestamp_by_lsn`
Operation page: `/api/operations/seren_db_get_timestamp_by_lsn`
Get timestamp by LSN for a branch.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `bid` (path, required): string / uuid - Branch ID
- `lsn` (query, required): string - Log sequence number

Responses:
- `200` Timestamp retrieved (application/json: DataResponse_TimestampByLsn)
- `404` Not found

### GET /publishers/seren-db/projects/{id}/branches/count

Operation ID: `seren_db_get_branch_count`
Operation page: `/api/operations/seren_db_get_branch_count`
Get branch count for a project.

Parameters:
- `id` (path, required): string / uuid - Project ID

Responses:
- `200` Branch count retrieved (application/json: DataResponse_Value)
- `404` Not found

### GET /publishers/seren-db/projects/{id}/connection_uri

Operation ID: `seren_db_connection_uri`
Operation page: `/api/operations/seren_db_connection_uri`
Get connection URI for a project.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `branch_id` (query): string / uuid - Optional branch ID
- `endpoint_id` (query): string / uuid - Optional endpoint ID
- `database_name` (query): string - Optional database name
- `role_name` (query): string - Optional role name
- `pooled` (query): boolean - Use pooled connection if true

Responses:
- `200` Connection URI retrieved (application/json: ProjectConnectionUriDataResponse)
- `404` Not found

### GET /publishers/seren-db/projects/{id}/consumption

Operation ID: `seren_db_get_project_consumption`
Operation page: `/api/operations/seren_db_get_project_consumption`
Get consumption for a project.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `start_date` (query): string - Start date (YYYY-MM-DD)
- `end_date` (query): string - End date (YYYY-MM-DD)

Responses:
- `200` Consumption retrieved (application/json: DataResponse_ProjectConsumption)
- `404` Not found

### GET /publishers/seren-db/projects/{id}/databases

Operation ID: `seren_db_list_project_databases`
Operation page: `/api/operations/seren_db_list_project_databases`
List all databases for a project.

Parameters:
- `id` (path, required): string / uuid - Project ID

Responses:
- `200` Project databases listed (application/json: DataResponse_Value)
- `404` Not found

### GET /publishers/seren-db/projects/{id}/endpoints

Operation ID: `seren_db_list_project_endpoints`
Operation page: `/api/operations/seren_db_list_project_endpoints`
List all endpoints for a project.

Parameters:
- `id` (path, required): string / uuid - Project ID

Responses:
- `200` Project endpoints listed (application/json: DataResponse_Value)
- `404` Not found

### DELETE /publishers/seren-db/projects/{id}/endpoints/{eid}

Operation ID: `seren_db_delete_project_endpoint`
Operation page: `/api/operations/seren_db_delete_project_endpoint`
Delete a project endpoint.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `eid` (path, required): string / uuid - Endpoint ID

Responses:
- `200` Project endpoint deleted (application/json: DataResponse_Value)
- `404` Not found

### PATCH /publishers/seren-db/projects/{id}/endpoints/{eid}

Operation ID: `seren_db_update_project_endpoint`
Operation page: `/api/operations/seren_db_update_project_endpoint`
Update a project endpoint.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `eid` (path, required): string / uuid - Endpoint ID

Request body (required):
- `application/json`: UpdateEndpointRequest

Responses:
- `200` Project endpoint updated (application/json: DataResponse_Value)
- `404` Not found

### POST /publishers/seren-db/projects/{id}/endpoints/{eid}/restart

Operation ID: `seren_db_restart_endpoint`
Operation page: `/api/operations/seren_db_restart_endpoint`
Restart an endpoint by project and endpoint ID.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `eid` (path, required): string / uuid - Endpoint ID

Responses:
- `200` Endpoint restarted (application/json: EndpointStatusInfoResponse)
- `404` Not found

### POST /publishers/seren-db/projects/{id}/endpoints/{eid}/start

Operation ID: `seren_db_start_project_endpoint`
Operation page: `/api/operations/seren_db_start_project_endpoint`
Start a project endpoint.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `eid` (path, required): string / uuid - Endpoint ID

Responses:
- `200` Project endpoint started (application/json: DataResponse_Value)
- `404` Not found

### POST /publishers/seren-db/projects/{id}/endpoints/{eid}/suspend

Operation ID: `seren_db_suspend_project_endpoint`
Operation page: `/api/operations/seren_db_suspend_project_endpoint`
Suspend a project endpoint.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `eid` (path, required): string / uuid - Endpoint ID

Responses:
- `200` Project endpoint suspended (application/json: DataResponse_Value)
- `404` Not found

### GET /publishers/seren-db/projects/{id}/ip-allow

Operation ID: `seren_db_list_ip_allow_list`
Operation page: `/api/operations/seren_db_list_ip_allow_list`
List project IP allow list entries.

Parameters:
- `id` (path, required): string / uuid - Project ID

Responses:
- `200` IP allow list listed (application/json: DataResponse_Vec_IpAllowList)
- `404` Not found

### POST /publishers/seren-db/projects/{id}/ip-allow

Operation ID: `seren_db_add_ip_allow_list`
Operation page: `/api/operations/seren_db_add_ip_allow_list`
Add an IP allow list entry.

Parameters:
- `id` (path, required): string / uuid - Project ID

Request body (required):
- `application/json`: AddIpAllowListRequest

Responses:
- `201` IP allow list entry added (application/json: DataResponse_IpAllowList)
- `404` Not found

### DELETE /publishers/seren-db/projects/{id}/ip-allow/{ip_id}

Operation ID: `seren_db_remove_ip_allow_list`
Operation page: `/api/operations/seren_db_remove_ip_allow_list`
Remove an IP allow list entry.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `ip_id` (path, required): string / uuid - IP allow list entry ID

Responses:
- `204` IP allow list entry removed
- `404` Not found

### PUT /publishers/seren-db/projects/{id}/ip-allow/reset

Operation ID: `seren_db_reset_ip_allow_list`
Operation page: `/api/operations/seren_db_reset_ip_allow_list`
Replace the project IP allow list.

Parameters:
- `id` (path, required): string / uuid - Project ID

Request body (required):
- `application/json`: ResetIpAllowListRequest

Responses:
- `200` IP allow list reset (application/json: DataResponse_Vec_IpAllowList)
- `404` Not found

### GET /publishers/seren-db/projects/{id}/operations

Operation ID: `seren_db_list_operations`
Operation page: `/api/operations/seren_db_list_operations`
List operations for a project.

Parameters:
- `id` (path, required): string / uuid - Project ID

Responses:
- `200` Operations listed (application/json: DataResponse_Value)
- `404` Not found

### GET /publishers/seren-db/projects/{id}/operations/{operation_id}

Operation ID: `seren_db_get_operation`
Operation page: `/api/operations/seren_db_get_operation`
Get a specific operation for a project.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `operation_id` (path, required): string / uuid - Operation ID

Responses:
- `200` Operation retrieved (application/json: DataResponse_Value)
- `404` Not found

### GET /publishers/seren-db/projects/{id}/replication

Operation ID: `seren_db_get_replication_settings`
Operation page: `/api/operations/seren_db_get_replication_settings`
Get logical replication settings for a project.

Parameters:
- `id` (path, required): string / uuid - Project ID

Responses:
- `200` Replication settings retrieved (application/json: DataResponse_LogicalReplicationSettings)
- `404` Not found

### PATCH /publishers/seren-db/projects/{id}/replication

Operation ID: `seren_db_update_replication_settings`
Operation page: `/api/operations/seren_db_update_replication_settings`
Update logical replication settings for a project.

Parameters:
- `id` (path, required): string / uuid - Project ID

Request body (required):
- `application/json`: UpdateLogicalReplicationRequest

Responses:
- `200` Replication settings updated (application/json: DataResponse_LogicalReplicationSettings)
- `404` Not found

### GET /publishers/seren-db/projects/{id}/size

Operation ID: `seren_db_get_project_size`
Operation page: `/api/operations/seren_db_get_project_size`
Get project size.

Parameters:
- `id` (path, required): string / uuid - Project ID

Responses:
- `200` Project size retrieved (application/json: DataResponse_ProjectSize)
- `404` Not found

### GET /publishers/seren-db/projects/{id}/vpc_endpoints

Operation ID: `seren_db_list_project_vpc_endpoints_alias`
Operation page: `/api/operations/seren_db_list_project_vpc_endpoints_alias`
List project VPC endpoint assignments (underscore alias).

Parameters:
- `id` (path, required): string / uuid - Project ID

Responses:
- `200` VPC endpoint assignments listed (application/json: DataResponse_Value)
- `404` Not found

### DELETE /publishers/seren-db/projects/{id}/vpc_endpoints/{vpc_endpoint_id}

Operation ID: `seren_db_remove_project_vpc_endpoint_by_vpc_id`
Operation page: `/api/operations/seren_db_remove_project_vpc_endpoint_by_vpc_id`
Remove a project VPC endpoint assignment by endpoint id (underscore alias).

Parameters:
- `id` (path, required): string / uuid - Project ID
- `vpc_endpoint_id` (path, required): string / uuid - Organization VPC endpoint ID

Responses:
- `204` VPC endpoint assignment removed
- `404` Not found

### POST /publishers/seren-db/projects/{id}/vpc_endpoints/{vpc_endpoint_id}

Operation ID: `seren_db_assign_project_vpc_endpoint_by_id`
Operation page: `/api/operations/seren_db_assign_project_vpc_endpoint_by_id`
Assign a VPC endpoint to a project by endpoint id (underscore alias).

Parameters:
- `id` (path, required): string / uuid - Project ID
- `vpc_endpoint_id` (path, required): string / uuid - Organization VPC endpoint ID

Responses:
- `201` VPC endpoint assignment created (application/json: DataResponse_Value)
- `404` Not found

### GET /publishers/seren-db/projects/{id}/vpc-endpoints

Operation ID: `seren_db_list_project_vpc_endpoints`
Operation page: `/api/operations/seren_db_list_project_vpc_endpoints`
List project VPC endpoint assignments.

Parameters:
- `id` (path, required): string / uuid - Project ID

Responses:
- `200` VPC endpoint assignments listed (application/json: DataResponse_Value)
- `404` Not found

### POST /publishers/seren-db/projects/{id}/vpc-endpoints

Operation ID: `seren_db_assign_project_vpc_endpoint`
Operation page: `/api/operations/seren_db_assign_project_vpc_endpoint`
Assign a VPC endpoint to a project.

Parameters:
- `id` (path, required): string / uuid - Project ID

Request body (required):
- `application/json`: AssignProjectVpcEndpointRequest

Responses:
- `201` VPC endpoint assignment created (application/json: DataResponse_Value)
- `404` Not found

### DELETE /publishers/seren-db/projects/{id}/vpc-endpoints/{assignment_id}

Operation ID: `seren_db_remove_project_vpc_endpoint`
Operation page: `/api/operations/seren_db_remove_project_vpc_endpoint`
Remove a project VPC endpoint assignment.

Parameters:
- `id` (path, required): string / uuid - Project ID
- `assignment_id` (path, required): string / uuid - Assignment ID

Responses:
- `204` VPC endpoint assignment removed
- `404` Not found

### POST /publishers/seren-db/query

Operation ID: `seren_db_query`
Operation page: `/api/operations/seren_db_query`
Execute a SQL query against a SerenDB database.

Request body (required):
- `application/json`: QueryRequest

Responses:
- `200` Query executed (application/json: DataResponse_QueryResult)
- `400` Bad request / query error
- `401` Unauthorized

## Sessions

### GET /sessions

Operation ID: `list_sessions`
Operation page: `/api/operations/list_sessions`
List all active sessions for the current user

Responses:
- `200` Sessions retrieved successfully (application/json: DataResponse_Vec_Session)
- `401` Unauthorized

### DELETE /sessions/{session_id}

Operation ID: `revoke_session`
Operation page: `/api/operations/revoke_session`
Revoke a specific session

Parameters:
- `session_id` (path, required): string / uuid - Session ID to revoke

Responses:
- `200` Session revoked successfully (application/json: DataResponse_SessionsRevoked)
- `401` Unauthorized
- `404` Session not found

### POST /sessions/{session_id}/revoke-others

Operation ID: `revoke_other_sessions`
Operation page: `/api/operations/revoke_other_sessions`
Revoke all sessions except a specified one

Parameters:
- `session_id` (path, required): string / uuid - Session ID to keep (current session)

Responses:
- `200` Other sessions revoked successfully (application/json: DataResponse_SessionsRevoked)
- `401` Unauthorized
- `404` Session not found or doesn't belong to user

### POST /sessions/revoke-all

Operation ID: `revoke_all_sessions`
Operation page: `/api/operations/revoke_all_sessions`
Revoke all sessions (logout everywhere)

Responses:
- `200` All sessions revoked successfully (application/json: DataResponse_SessionsRevoked)
- `401` Unauthorized

## shares

### GET /publishers/seren-notes/notes/{note_id}/shares

Operation ID: `list_shares`
Operation page: `/api/operations/list_shares`
List shares for a note

Parameters:
- `note_id` (path, required): string / uuid - Note ID

Responses:
- `200` List of shares (application/json: DataResponse_Vec_NoteShare)
- `401` Unauthorized

### GET /publishers/seren-notes/share/{token}

Operation ID: `get_public_shared_note`
Operation page: `/api/operations/get_public_shared_note`
Get a publicly shared note by cryptographic share token

This endpoint does not require authentication. The token contains an embedded
organization_id (cryptographically signed) which is used to route to the correct
tenant database via serencore's service JWT API. The token is verified before use.

Parameters:
- `token` (path, required): string - Cryptographic share token

Responses:
- `200` Shared note found (application/json: DataResponse_SharedNoteResponse)
- `400` Invalid token format or signature
- `403` Share does not allow anonymous access
- `404` Share not found, expired, or not public

### POST /publishers/seren-notes/shares

Operation ID: `create_share`
Operation page: `/api/operations/create_share`
Create a share for a note

Request body (required):
- `application/json`: CreateShareApiRequest

Responses:
- `201` Share created (application/json: DataResponse_NoteShare)
- `400` Invalid request
- `401` Unauthorized
- `404` Note not found

### DELETE /publishers/seren-notes/shares/{share_id}

Operation ID: `delete_share`
Operation page: `/api/operations/delete_share`
Delete (revoke) a share

Parameters:
- `share_id` (path, required): string / uuid - Share ID

Responses:
- `204` Share deleted
- `401` Unauthorized
- `404` Share not found

### GET /publishers/seren-notes/shares/{share_id}

Operation ID: `get_share`
Operation page: `/api/operations/get_share`
Get a share by ID

Parameters:
- `share_id` (path, required): string / uuid - Share ID

Responses:
- `200` Share found (application/json: DataResponse_NoteShare)
- `401` Unauthorized
- `404` Share not found

### PATCH /publishers/seren-notes/shares/{share_id}

Operation ID: `update_share`
Operation page: `/api/operations/update_share`
Update a share

Parameters:
- `share_id` (path, required): string / uuid - Share ID

Request body (required):
- `application/json`: UpdateShareApiRequest

Responses:
- `200` Share updated (application/json: DataResponse_NoteShare)
- `401` Unauthorized
- `404` Share not found

### GET /publishers/seren-notes/shares/token/{token}

Operation ID: `get_share_by_token`
Operation page: `/api/operations/get_share_by_token`
Get a share by token (for public access)

Parameters:
- `token` (path, required): string - Share token

Responses:
- `200` Share found (application/json: DataResponse_NoteShare)
- `404` Share not found or expired

## Shares

### POST /publishers/seren-passwords/shares

Operation ID: `share_create`
Operation page: `/api/operations/share_create`
Create a live item share. If recipient key material is supplied the share
is immediately active; otherwise the returned signed token lets the
recipient claim it later.

Request body (required):
- `application/json`: CreateShareRequest

Responses:
- `200` Created live share (application/json: DataResponseLiveShareCreated)
- `400` Malformed request or share tokens unavailable
- `401` Caller is not authenticated
- `403` Caller does not have write access to the vault
- `404` Vault or item not found
- `422` Request body failed validation

### GET /publishers/seren-passwords/shares/{share_id}

Operation ID: `share_get`
Operation page: `/api/operations/share_get`
Read a live shared item through the recipient-local pointer.

Parameters:
- `share_id` (path, required): string / uuid - Share id

Responses:
- `200` Shared encrypted item plus wrapped item key (application/json: DataResponseSharedItemView)
- `401` Caller is not authenticated
- `404` Share not found, revoked, or not addressed to the caller
- `429` Shared-item read rate limit exceeded

### POST /publishers/seren-passwords/shares/{share_id}/complete

Operation ID: `share_complete`
Operation page: `/api/operations/share_complete`
Complete a recipient-claimed email share by adding the sender-wrapped
item content key.

Parameters:
- `share_id` (path, required): string / uuid - Share id

Request body (required):
- `application/json`: CompleteLiveShareRequest

Responses:
- `200` Completed live share (application/json: DataResponseLiveShareView)
- `400` Malformed request
- `401` Caller is not authenticated
- `403` Agent callers cannot complete shares
- `404` Share not found or not ready
- `422` Request body failed validation
- `429` Shared-item read rate limit exceeded

### POST /publishers/seren-passwords/shares/{share_id}/revoke

Operation ID: `share_revoke`
Operation page: `/api/operations/share_revoke`
Revoke a live share. The recipient-local pointer may remain until the
recipient next syncs, but live reads re-check the owner DB and fail.

Parameters:
- `share_id` (path, required): string / uuid - Share id

Responses:
- `200` Revoked live share (application/json: DataResponseLiveShareView)
- `401` Caller is not authenticated
- `404` Share not found or caller cannot revoke it
- `429` Shared-item read rate limit exceeded

### POST /publishers/seren-passwords/shares/claim

Operation ID: `share_claim`
Operation page: `/api/operations/share_claim`
Claim a live share token into the caller's current password DB.

Request body (required):
- `application/json`: ClaimLiveShareRequest

Responses:
- `200` Claimed live share (application/json: DataResponseLiveShareView)
- `400` Malformed token or request
- `401` Caller is not authenticated
- `403` Agents may not claim shares
- `404` Share not found or not claimable
- `422` Request body failed validation
- `429` Shared-item read rate limit exceeded

### GET /publishers/seren-passwords/shares/outbound

Operation ID: `share_list_outbound`
Operation page: `/api/operations/share_list_outbound`
List outbound shares rooted in the caller's current organization.

Parameters:
- `vault_id` (query): string | null / uuid

Responses:
- `200` Outbound live shares (application/json: DataResponseLiveShareViewList)
- `401` Caller is not authenticated
- `403` Agent callers cannot list outbound shares
- `429` Shared-item read rate limit exceeded

### GET /publishers/seren-passwords/shares/received

Operation ID: `share_list_received`
Operation page: `/api/operations/share_list_received`
List live shares claimed by the caller in the current password database.

Responses:
- `200` Received live shares (application/json: DataResponseReceivedShareViewList)
- `401` Caller is not authenticated
- `403` Agent callers cannot read human received-share inboxes
- `429` Shared-item read rate limit exceeded

### POST /publishers/seren-passwords/shares/recipients/lookup

Operation ID: `share_recipient_lookup`
Operation page: `/api/operations/share_recipient_lookup`

Request body (required):
- `application/json`: ShareRecipientLookupRequest

Responses:
- `200` Verified recipient public key lookup (application/json: DataResponseShareRecipientLookup)
- `400` Malformed request or invalid email
- `401` Caller is not authenticated
- `403` Agents cannot look up share recipients
- `422` Request body failed validation
- `429` Shared-item read rate limit exceeded

## skills

### GET /publishers/seren-skills

Operation ID: `publisher_root`
Operation page: `/api/operations/publisher_root`

Responses:
- `200` Publisher metadata (application/json: DataResponse_Value)

### GET /publishers/seren-skills/admin/skills/orphan-folders

Operation ID: `list_orphan_folders`
Operation page: `/api/operations/list_orphan_folders`
Operator inventory of canonical-repo paths the gateway has no
claim on.

Authorization: any caller with `X-Seren-User-Role: admin` (platform
admin set by Seren Core's `ADMIN_USER_IDS`). The endpoint is
**read-only** and does not return per-org data  every orphan is by
definition a path the gateway has lost track of, so scoping it to one
organization would defeat the visibility purpose. Unauthorized callers
receive 403.

On success returns:

```json
{
  "head_commit_sha": "...",
  "head_tree_sha": "...",
  "orphan_folders": [
    {
      "folder_slug": "org-deadbeef",
      "skill_folder_name": "grid-trader",
      "paths": ["org-deadbeef/grid-trader/SKILL.md", "..."]
    }
  ]
}
```

Failure modes:

- 403 if the caller lacks `X-Seren-User-Role=admin`.
- 400 if GitHub publishing is not configured for this deployment.
- 500 if GitHub returned a truncated tree listing (we cannot
  trust a partial view for an inventory pass  same posture as
  `derive_orphan_paths` in `github_status`).

Responses:
- `200` Operator orphan-folders inventory (application/json: DataResponse_OrphanFoldersResponse)
- `403` Caller lacks platform admin role

### GET /publishers/seren-skills/git-identity

Operation ID: `get_author_identity`
Operation page: `/api/operations/get_author_identity`

Responses:
- `200` Git author identity (application/json: DataResponse_AuthorIdentity)

### PUT /publishers/seren-skills/git-identity

Operation ID: `upsert_author_identity`
Operation page: `/api/operations/upsert_author_identity`

Request body (required):
- `application/json`: UpsertAuthorIdentityRequest

Responses:
- `200` Upserted Git author identity (application/json: DataResponse_AuthorIdentity)

### GET /publishers/seren-skills/organizations/{org_id}/folder

Operation ID: `get_org_folder`
Operation page: `/api/operations/get_org_folder`

Parameters:
- `org_id` (path, required): string / uuid - Organization ID

Responses:
- `200` Organization folder (application/json: DataResponse_Value)

### PATCH /publishers/seren-skills/organizations/{org_id}/folder

Operation ID: `update_org_folder`
Operation page: `/api/operations/update_org_folder`

Parameters:
- `org_id` (path, required): string / uuid - Organization ID

Request body (required):
- `application/json`: UpsertOrgFolderRequest

Responses:
- `200` Organization folder (application/json: DataResponse_Value)

### POST /publishers/seren-skills/organizations/{org_id}/folder

Operation ID: `create_org_folder`
Operation page: `/api/operations/create_org_folder`

Parameters:
- `org_id` (path, required): string / uuid - Organization ID

Request body (required):
- `application/json`: UpsertOrgFolderRequest

Responses:
- `200` Organization folder (application/json: DataResponse_Value)

### PUT /publishers/seren-skills/organizations/{org_id}/folder

Operation ID: `replace_org_folder`
Operation page: `/api/operations/replace_org_folder`

Parameters:
- `org_id` (path, required): string / uuid - Organization ID

Request body (required):
- `application/json`: UpsertOrgFolderRequest

Responses:
- `200` Organization folder (application/json: DataResponse_Value)

### POST /publishers/seren-skills/organizations/{org_id}/folder/transfer

Operation ID: `transfer_org_folder`
Operation page: `/api/operations/transfer_org_folder`

Parameters:
- `org_id` (path, required): string / uuid - Organization ID

Request body (required):
- `application/json`: TransferOrgFolderRequest

Responses:
- `200` Organization folder (application/json: DataResponse_Value)
- `403` Caller is not org-admin, personal-owner of {org_id}, or platform admin
- `404` Slug is not held by any folder row
- `409` Slug is held by a real organization, not a placeholder

### GET /publishers/seren-skills/skill.md

Operation ID: `skill_md`
Operation page: `/api/operations/skill_md`

Responses:
- `200` Publisher skill definition (text/markdown: unspecified)

### GET /publishers/seren-skills/skills

Operation ID: `list_skills`
Operation page: `/api/operations/list_skills`

Parameters:
- `q` (query): string | null
- `visibility` (query): null | SkillVisibility
- `mine` (query): boolean | null
- `sort` (query): null | ListSkillsSort
- `limit` (query): integer | null / int64
- `offset` (query): integer | null / int64

Responses:
- `200` Skills (application/json: DataResponse_Vec_SkillSummary)

### POST /publishers/seren-skills/skills

Operation ID: `create_skill`
Operation page: `/api/operations/create_skill`

Request body (required):
- `application/json`: CreateSkillRequest

Responses:
- `200` Created skill (application/json: DataResponse_SkillDetail)

### DELETE /publishers/seren-skills/skills/{slug}

Operation ID: `delete_skill`
Operation page: `/api/operations/delete_skill`

Parameters:
- `slug` (path, required): string - Skill slug

Responses:
- `200` Soft-deleted skill (application/json: DataResponse_Value)

### GET /publishers/seren-skills/skills/{slug}

Operation ID: `get_skill`
Operation page: `/api/operations/get_skill`

Parameters:
- `slug` (path, required): string - Skill slug

Responses:
- `200` Skill detail (application/json: DataResponse_SkillDetail)

### PATCH /publishers/seren-skills/skills/{slug}

Operation ID: `update_skill`
Operation page: `/api/operations/update_skill`

Parameters:
- `slug` (path, required): string - Skill slug

Request body (required):
- `application/json`: UpdateSkillRequest

Responses:
- `200` Updated skill (application/json: DataResponse_SkillDetail)

### GET /publishers/seren-skills/skills/{slug}/agent-grants

Operation ID: `list_agent_grants`
Operation page: `/api/operations/list_agent_grants`

Parameters:
- `slug` (path, required): string - Skill slug

Responses:
- `200` Managed agent grants for an organization-authorized skill (application/json: DataResponse_Vec_SkillAgentGrant)

### DELETE /publishers/seren-skills/skills/{slug}/agent-grants/{agent_identity_id}

Operation ID: `revoke_agent_grant`
Operation page: `/api/operations/revoke_agent_grant`

Parameters:
- `slug` (path, required): string - Skill slug
- `agent_identity_id` (path, required): string / uuid - Managed agent identity
- `expected_grant_generation` (query, required): integer / int64 - Generation observed by the caller before revocation.

Responses:
- `200` Managed agent skill grant revoked (application/json: DataResponse_bool)

### PUT /publishers/seren-skills/skills/{slug}/agent-grants/{agent_identity_id}

Operation ID: `upsert_agent_grant`
Operation page: `/api/operations/upsert_agent_grant`

Parameters:
- `slug` (path, required): string - Skill slug
- `agent_identity_id` (path, required): string / uuid - Managed agent identity

Request body (required):
- `application/json`: UpsertSkillAgentGrantRequest

Responses:
- `200` Created or updated managed agent skill grant (application/json: DataResponse_SkillAgentGrant)

### GET /publishers/seren-skills/skills/{slug}/collaborators

Operation ID: `list_collaborators`
Operation page: `/api/operations/list_collaborators`

Parameters:
- `slug` (path, required): string - Skill slug

Responses:
- `200` Skill collaborators (application/json: DataResponse_Vec_Collaborator)

### DELETE /publishers/seren-skills/skills/{slug}/collaborators/{user_id}

Operation ID: `delete_collaborator`
Operation page: `/api/operations/delete_collaborator`

Parameters:
- `slug` (path, required): string - Skill slug
- `user_id` (path, required): string / uuid - Collaborator user ID

Responses:
- `200` Deleted collaborator (application/json: DataResponse_Value)

### PUT /publishers/seren-skills/skills/{slug}/collaborators/{user_id}

Operation ID: `upsert_collaborator`
Operation page: `/api/operations/upsert_collaborator`

Parameters:
- `slug` (path, required): string - Skill slug
- `user_id` (path, required): string / uuid - Collaborator user ID

Request body (required):
- `application/json`: UpsertCollaboratorRequest

Responses:
- `200` Upserted collaborator (application/json: DataResponse_Collaborator)

### GET /publishers/seren-skills/skills/{slug}/download

Operation ID: `download_skill`
Operation page: `/api/operations/download_skill`

Parameters:
- `slug` (path, required): string - Skill slug

Responses:
- `200` Downloadable skill bundle (application/json: DataResponse_SkillBundle)

### GET /publishers/seren-skills/skills/{slug}/download/file

Operation ID: `download_skill_file`
Operation page: `/api/operations/download_skill_file`

Parameters:
- `slug` (path, required): string - Skill slug
- `path` (query, required): string - Bundle-relative file path from the manifest

Responses:
- `200` One bundle file body (application/json: DataResponse_SkillBundleFileDownload)

### GET /publishers/seren-skills/skills/{slug}/download/manifest

Operation ID: `download_skill_manifest`
Operation page: `/api/operations/download_skill_manifest`

Parameters:
- `slug` (path, required): string - Skill slug

Responses:
- `200` Bundle manifest without file bodies (application/json: DataResponse_SkillBundleManifest)

### GET /publishers/seren-skills/skills/{slug}/drafts/{draft_id}

Operation ID: `get_draft`
Operation page: `/api/operations/get_draft`

Parameters:
- `slug` (path, required): string - Skill slug
- `draft_id` (path, required): string / uuid - Draft ID

Responses:
- `200` Chat conflict draft (application/json: DataResponse_ChatDraftResponse)

### GET /publishers/seren-skills/skills/{slug}/drafts/{draft_id}/merge-state

Operation ID: `get_merge_state`
Operation page: `/api/operations/get_merge_state`

Parameters:
- `slug` (path, required): string - Skill slug
- `draft_id` (path, required): string / uuid - Draft ID

Responses:
- `200` Merge state (application/json: DataResponse_MergeStateResponse)

### POST /publishers/seren-skills/skills/{slug}/drafts/{draft_id}/resolve-conflict

Operation ID: `resolve_conflict`
Operation page: `/api/operations/resolve_conflict`

Parameters:
- `slug` (path, required): string - Skill slug
- `draft_id` (path, required): string / uuid - Draft ID

Request body (required):
- `application/json`: ResolveConflictRequest

Responses:
- `200` Resolved conflict version (application/json: DataResponse_CreateVersionResponse)

### GET /publishers/seren-skills/skills/{slug}/edit

Operation ID: `get_skill_edit_document`
Operation page: `/api/operations/get_skill_edit_document`

Parameters:
- `slug` (path, required): string - Skill slug

Responses:
- `200` Editor-facing document (application/json: DataResponse_SkillEditDocument)
- `403` Owner access required

### GET /publishers/seren-skills/skills/{slug}/files

Operation ID: `list_files`
Operation page: `/api/operations/list_files`
`GET /skills/{slug}/files` -- list every file in the current
version's bundle, plus a synthetic `SKILL.md` entry.

Parameters:
- `slug` (path, required): string - Skill slug

Responses:
- `200` Bundle file listing (application/json: DataResponse_Vec_FileListing)

### DELETE /publishers/seren-skills/skills/{slug}/files/{path}

Operation ID: `delete_file`
Operation page: `/api/operations/delete_file`
`DELETE /skills/{slug}/files/{path...}` -- drop one file.

Parameters:
- `slug` (path, required): string - Skill slug
- `path` (path, required): string - Bundle path; SKILL.md is rejected with 400

Request body (required):
- `application/json`: DeleteFileRequest

Responses:
- `200` Per-file delete result (application/json: DataResponse_FileEditResponse)

### GET /publishers/seren-skills/skills/{slug}/files/{path}

Operation ID: `get_file`
Operation page: `/api/operations/get_file`
`GET /skills/{slug}/files/{path...}` -- one file's bytes.

Parameters:
- `slug` (path, required): string - Skill slug
- `path` (path, required): string - Bundle path or 'SKILL.md'

Responses:
- `200` Single bundle file (application/json: DataResponse_GetFileResponse)

### PUT /publishers/seren-skills/skills/{slug}/files/{path}

Operation ID: `put_file`
Operation page: `/api/operations/put_file`
`PUT /skills/{slug}/files/{path...}` -- replace or add one file.

Parameters:
- `slug` (path, required): string - Skill slug
- `path` (path, required): string - Bundle path or 'SKILL.md'

Request body (required):
- `application/json`: PutFileRequest

Responses:
- `200` Per-file edit result (application/json: DataResponse_FileEditResponse)

### GET /publishers/seren-skills/skills/{slug}/github

Operation ID: `github_status`
Operation page: `/api/operations/github_status`

Parameters:
- `slug` (path, required): string - Skill slug

Responses:
- `200` GitHub publish ledger (application/json: DataResponse_Value)

### POST /publishers/seren-skills/skills/{slug}/github/reconcile-orphans

Operation ID: `reconcile_orphans`
Operation page: `/api/operations/reconcile_orphans`
`POST /skills/{slug}/github/reconcile-orphans` -- ops endpoint
that mechanically removes canonical-repo paths the gateway no
longer claims for this skill. Issue #22 acceptance:

- Owner, org-admin, or platform-admin authz (same
  `ensure_can_operate_skill_catalog` pattern as
  `/github/sync-from-main` and `/github/retry`).
- `confirm: true` is required. `false` or missing returns 409.
- The handler re-derives the **live** orphan-path set against the
  canonical-repo HEAD and returns 409 if it does not match the
  `expected_orphan_paths` payload (optimistic concurrency mirrors
  `expected_current_version_id`).
- On match (and `dry_run: false`): stages one signed commit on
  the canonical branch deleting every path. Author/committer is
  the forward-publish bot pair so reverse-sync skips the commit
  via `is_forward_publish_commit`.
- On `dry_run: true`: skips the commit and returns the planned
  shape (paths + parent commit SHA + audit row id) without
  touching GitHub.
- Records a `skill_orphan_reconciliations` audit row in both
  modes (issue #22 acceptance criterion + migration 011).

Parameters:
- `slug` (path, required): string - Skill slug

Request body (required):
- `application/json`: ReconcileOrphansRequest

Responses:
- `200` Reconcile result (application/json: DataResponse_Value)
- `409` Mismatch or unconfirmed request (application/json: object)

### POST /publishers/seren-skills/skills/{slug}/github/retry

Operation ID: `retry_github_publish`
Operation page: `/api/operations/retry_github_publish`

Parameters:
- `slug` (path, required): string - Skill slug

Responses:
- `200` GitHub publish retry queued (application/json: DataResponse_Value)

### POST /publishers/seren-skills/skills/{slug}/github/sync-from-main

Operation ID: `sync_from_main`
Operation page: `/api/operations/sync_from_main`
`POST /skills/{slug}/github/sync-from-main` -- ops endpoint that
re-fetches the canonical GitHub bundle at HEAD and reconciles it
into a new gateway version. No-op when the resulting
`content_hash_bundle` matches the current version. Requires owner,
org-admin, or `X-Seren-User-Role=admin`.

Parameters:
- `slug` (path, required): string - Skill slug

Responses:
- `200` GitHub sync-from-main result (application/json: DataResponse_Value)

### POST /publishers/seren-skills/skills/{slug}/purchase

Operation ID: `purchase_skill`
Operation page: `/api/operations/purchase_skill`

Parameters:
- `slug` (path, required): string - Skill slug

Responses:
- `200` Purchase result (application/json: DataResponse_PurchaseResponse)
- `402` Insufficient balance

### PUT /publishers/seren-skills/skills/{slug}/sponsor

Operation ID: `update_sponsor`
Operation page: `/api/operations/update_sponsor`

Parameters:
- `slug` (path, required): string - Skill slug

Request body (required):
- `application/json`: UpdateSponsorRequest

Responses:
- `200` Updated sponsor settings (application/json: DataResponse_SkillDetail)

### GET /publishers/seren-skills/skills/{slug}/update-requests

Operation ID: `list_update_requests`
Operation page: `/api/operations/list_update_requests`

Parameters:
- `slug` (path, required): string - Skill slug

Responses:
- `200` Update requests (application/json: DataResponse_Vec_UpdateRequest)

### POST /publishers/seren-skills/skills/{slug}/update-requests

Operation ID: `create_update_request`
Operation page: `/api/operations/create_update_request`

Parameters:
- `slug` (path, required): string - Skill slug

Request body (required):
- `application/json`: CreateUpdateRequest

Responses:
- `200` Created update request (application/json: DataResponse_UpdateRequest)

### GET /publishers/seren-skills/skills/{slug}/versions

Operation ID: `list_versions`
Operation page: `/api/operations/list_versions`

Parameters:
- `slug` (path, required): string - Skill slug

Responses:
- `200` Skill versions (application/json: DataResponse_Vec_SkillVersion)

### POST /publishers/seren-skills/skills/{slug}/versions

Operation ID: `create_version`
Operation page: `/api/operations/create_version`

Parameters:
- `slug` (path, required): string - Skill slug

Request body (required):
- `application/json`: CreateVersionRequest

Responses:
- `200` Created skill version or conflict draft (application/json: DataResponse_CreateVersionResponse)

### GET /publishers/seren-skills/skills/{slug}/versions/{version}/manifest

Operation ID: `get_version_manifest`
Operation page: `/api/operations/get_version_manifest`

Parameters:
- `slug` (path, required): string - Skill slug
- `version` (path, required): string - Version string

Responses:
- `200` Version manifest (application/json: DataResponse_Value)

### GET /publishers/seren-skills/update-requests/{request_id}

Operation ID: `get_update_request`
Operation page: `/api/operations/get_update_request`

Parameters:
- `request_id` (path, required): string / uuid - Update request ID

Responses:
- `200` Update request detail (application/json: DataResponse_UpdateRequestDetail)

### POST /publishers/seren-skills/update-requests/{request_id}/accept

Operation ID: `accept_update_request`
Operation page: `/api/operations/accept_update_request`

Parameters:
- `request_id` (path, required): string / uuid - Update request ID

Request body (required):
- `application/json`: AcceptUpdateRequestRequest

Responses:
- `200` Accepted update request (application/json: DataResponse_UpdateRequest)

### GET /publishers/seren-skills/update-requests/{request_id}/comments

Operation ID: `list_update_request_comments`
Operation page: `/api/operations/list_update_request_comments`

Parameters:
- `request_id` (path, required): string / uuid - Update request ID

Responses:
- `200` Update request comments (application/json: DataResponse_Vec_UpdateRequestComment)

### POST /publishers/seren-skills/update-requests/{request_id}/comments

Operation ID: `create_update_request_comment`
Operation page: `/api/operations/create_update_request_comment`

Parameters:
- `request_id` (path, required): string / uuid - Update request ID

Request body (required):
- `application/json`: CreateCommentRequest

Responses:
- `200` Created comment (application/json: DataResponse_Value)

### GET /publishers/seren-skills/update-requests/{request_id}/diff

Operation ID: `get_update_request_diff`
Operation page: `/api/operations/get_update_request_diff`

Parameters:
- `request_id` (path, required): string / uuid - Update request ID

Responses:
- `200` Update request diff payload (application/json: DataResponse_UpdateRequestDiff)

### POST /publishers/seren-skills/update-requests/{request_id}/reject

Operation ID: `reject_update_request`
Operation page: `/api/operations/reject_update_request`

Parameters:
- `request_id` (path, required): string / uuid - Update request ID

Responses:
- `200` Rejected update request (application/json: DataResponse_UpdateRequest)

### GET /publishers/seren-skills/usage

Operation ID: `list_usage_events`
Operation page: `/api/operations/list_usage_events`

Parameters:
- `limit` (query): integer | null / int64
- `offset` (query): integer | null / int64

Responses:
- `200` Usage events (application/json: DataResponse_Vec_UsageEvent)

### GET /publishers/seren-skills/usage/summary

Operation ID: `usage_summary`
Operation page: `/api/operations/usage_summary`

Responses:
- `200` Current-month usage totals (application/json: DataResponse_UsageSummaryResponse)

## Sync

### GET /publishers/seren-passwords/sync

Operation ID: `sync_get`
Operation page: `/api/operations/sync_get`
Aggregate read used by clients on cold start: identities, vaults,
memberships, item overviews, and the server's clock. Item bodies
(content ciphertexts) are intentionally excluded; clients fetch them
on demand via `GET /vaults/{vault_id}/items/{item_id}` or `/resolve`.

Responses:
- `200` Aggregate sync payload. Item entries are summaries only; content ciphertexts are not included and must be fetched on demand. (application/json: DataResponseSync)
- `401` Caller is not authenticated
- `404` Caller has no active account identity

## tags

### DELETE /publishers/seren-notes/notes/{note_id}/tags

Operation ID: `remove_tags`
Operation page: `/api/operations/remove_tags`
Remove tags from a note

Parameters:
- `note_id` (path, required): string / uuid - Note ID

Request body (required):
- `application/json`: RemoveTagsRequest

Responses:
- `200` Tags removed (application/json: DataResponse_NoteResponse)
- `401` Unauthorized
- `404` Note not found

### POST /publishers/seren-notes/notes/{note_id}/tags

Operation ID: `add_tags`
Operation page: `/api/operations/add_tags`
Add tags to a note

Parameters:
- `note_id` (path, required): string / uuid - Note ID

Request body (required):
- `application/json`: AddTagsRequest

Responses:
- `200` Tags added (application/json: DataResponse_NoteResponse)
- `401` Unauthorized
- `404` Note not found

### GET /publishers/seren-notes/notes/tags

Operation ID: `list_tags`
Operation page: `/api/operations/list_tags`
List all tags

Responses:
- `200` List of tags (application/json: DataResponse_Vec_String)
- `401` Unauthorized

## templates

### GET /organizations/{organization_id}/templates/analytics/{publisher_id}

Operation ID: `get_publisher_template_analytics`
Operation page: `/api/operations/get_publisher_template_analytics`
Get template analytics for a specific publisher

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `publisher_id` (path, required): string / uuid - Publisher ID

Responses:
- `200` Analytics retrieved successfully (application/json: DataResponse_PublisherAnalytics)
- `401` Unauthorized
- `403` Not authorized
- `404` Publisher not found
- `500` Internal server error

### GET /templates

Operation ID: `list_templates`
Operation page: `/api/operations/list_templates`
List available templates in the catalog

Parameters:
- `verified_only` (query): boolean - Filter to verified templates only
- `language` (query): string - Filter by language (python, typescript, javascript)
- `min_price` (query): integer / int64 - Minimum price in atomic units
- `max_price` (query): integer / int64 - Maximum price in atomic units
- `search` (query): string - Search in name and description
- `sort_by` (query): TemplateSortBy - Sort order (popularity, price_asc, price_desc, newest, oldest)
- `limit` (query): integer / int64 - Maximum number of templates to return (default: 50)
- `offset` (query): integer / int64 - Offset for pagination (default: 0)

Responses:
- `200` Templates retrieved successfully (application/json: DataResponse_Vec_AgentTemplateSummary)
- `500` Internal server error

### GET /templates/{slug}

Operation ID: `get_template`
Operation page: `/api/operations/get_template`
Get template details by slug

Parameters:
- `slug` (path, required): string - Template slug

Responses:
- `200` Template retrieved successfully (application/json: DataResponse_CreateTemplateResponse)
- `404` Template not found
- `500` Internal server error

### POST /templates/{slug}/invoke

Operation ID: `invoke_template`
Operation page: `/api/operations/invoke_template`
Invoke an agent template.

Supports two modes:
- **Bearer auth present**: uses the authenticated user's SerenBucks balance.
- **No bearer auth**: uses x402 (requires `X-AGENT-WALLET` + payment headers).

Parameters:
- `slug` (path, required): string - Template slug

Request body (required):
- `application/json`: InvokeTemplateRequest

Responses:
- `200` Template invoked successfully (application/json: DataResponse_InvokeTemplateResponse)
- `400` Invalid request
- `401` Authentication failed
- `402` Payment required
- `404` Template not found
- `500` Internal server error
- `503` Sandbox execution failed

### POST /templates/publish

Operation ID: `publish_template`
Operation page: `/api/operations/publish_template`
Publish a new agent template

Request body (required):
- `application/json`: CreateTemplateRequest

Responses:
- `201` Template published successfully (application/json: DataResponse_CreateTemplateResponse)
- `400` Invalid request
- `401` Authentication required
- `409` Template slug already exists
- `500` Internal server error

## Vaults

### GET /publishers/seren-passwords/vaults

Operation ID: `vault_list`
Operation page: `/api/operations/vault_list`
List vaults the caller is an active member of, each with the caller's
wrapped vault key inlined.

Responses:
- `200` Vaults visible to the caller (application/json: DataResponseVaultRecordList)
- `401` Caller is not authenticated
- `404` User has no active account identity

### POST /publishers/seren-passwords/vaults

Operation ID: `vault_create`
Operation page: `/api/operations/vault_create`
Create a new vault and seed an admin membership for the creator with the
supplied wrapped vault key.

Request body (required):
- `application/json`: CreateVaultRequest

Responses:
- `200` Newly created vault (application/json: DataResponseVaultRecord)
- `400` Body fails validation (e.g. org vault requires admin seed)
- `401` Caller is not authenticated
- `403` Only user identities may create vaults
- `422` Request body failed validation

### DELETE /publishers/seren-passwords/vaults/{vault_id}

Operation ID: `vault_archive`
Operation page: `/api/operations/vault_archive`
Soft-archive a vault. Requires admin membership.

Parameters:
- `vault_id` (path, required): string / uuid - Vault id

Responses:
- `200` Archived (application/json: DataResponseJsonValue)
- `401` Caller is not authenticated
- `403` Caller is not an admin of this vault
- `404` Vault not found

### GET /publishers/seren-passwords/vaults/{vault_id}

Operation ID: `vault_get`
Operation page: `/api/operations/vault_get`
Fetch a single vault by id (only visible to active members).

Parameters:
- `vault_id` (path, required): string / uuid - Vault id

Responses:
- `200` Vault record (application/json: DataResponseVaultRecord)
- `401` Caller is not authenticated
- `404` Vault not found or caller is not a member

### PATCH /publishers/seren-passwords/vaults/{vault_id}

Operation ID: `vault_update`
Operation page: `/api/operations/vault_update`
Update encrypted vault display metadata. Requires admin membership.

Parameters:
- `vault_id` (path, required): string / uuid - Vault id

Request body (required):
- `application/json`: VaultPatchRequest

Responses:
- `200` Updated (application/json: DataResponseJsonValue)
- `400` Body missing both name and description
- `401` Caller is not authenticated
- `403` Caller is not an admin of this vault
- `404` Vault not found
- `422` Request body failed validation

## VPC

### GET /organizations/{organization_id}/vpc-endpoints

Operation ID: `list_org_vpc_endpoints`
Operation page: `/api/operations/list_org_vpc_endpoints`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `region` (query): string | null - Filter endpoints by region

Responses:
- `200` List of VPC endpoints (application/json: DataResponse_Vec_OrganizationVpcEndpoint)
- `401` Unauthorized
- `404` Organization not found

### POST /organizations/{organization_id}/vpc-endpoints

Operation ID: `create_org_vpc_endpoint`
Operation page: `/api/operations/create_org_vpc_endpoint`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization

Request body (required):
- `application/json`: CreateOrganizationVpcEndpointRequest

Responses:
- `201` VPC endpoint recorded (application/json: DataResponse_OrganizationVpcEndpoint)
- `401` Unauthorized

### DELETE /organizations/{organization_id}/vpc-endpoints/{endpoint_id}

Operation ID: `delete_org_vpc_endpoint`
Operation page: `/api/operations/delete_org_vpc_endpoint`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `endpoint_id` (path, required): string / uuid - Organization VPC endpoint ID

Responses:
- `204` VPC endpoint removed
- `401` Unauthorized
- `404` VPC endpoint not found

### GET /organizations/{organization_id}/vpc-endpoints/{endpoint_id}

Operation ID: `get_org_vpc_endpoint`
Operation page: `/api/operations/get_org_vpc_endpoint`

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `endpoint_id` (path, required): string / uuid - Organization VPC endpoint ID

Responses:
- `200` VPC endpoint details (application/json: DataResponse_OrganizationVpcEndpoint)
- `401` Unauthorized
- `404` VPC endpoint not found

### GET /organizations/{organization_id}/vpc/region/{region_id}/vpc_endpoints

Operation ID: `list_org_vpc_endpoints_by_region`
Operation page: `/api/operations/list_org_vpc_endpoints_by_region`
List VPC endpoints for an organization filtered by region (alias path)

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `region_id` (path, required): string - Region

Responses:
- `200` List of VPC endpoints (application/json: DataResponse_Vec_OrganizationVpcEndpoint)
- `401` Unauthorized
- `404` Organization not found

### DELETE /organizations/{organization_id}/vpc/region/{region_id}/vpc_endpoints/{endpoint_id}

Operation ID: `delete_org_vpc_endpoint_by_region`
Operation page: `/api/operations/delete_org_vpc_endpoint_by_region`
Delete VPC endpoint with region in path (alias)

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `region_id` (path, required): string - Region
- `endpoint_id` (path, required): string / uuid - Organization VPC endpoint ID

Responses:
- `204` VPC endpoint removed
- `401` Unauthorized
- `404` VPC endpoint not found

### GET /organizations/{organization_id}/vpc/region/{region_id}/vpc_endpoints/{endpoint_id}

Operation ID: `get_org_vpc_endpoint_by_region`
Operation page: `/api/operations/get_org_vpc_endpoint_by_region`
Get VPC endpoint details with region in path (alias)

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `region_id` (path, required): string - Region
- `endpoint_id` (path, required): string / uuid - Organization VPC endpoint ID

Responses:
- `200` VPC endpoint details (application/json: DataResponse_OrganizationVpcEndpoint)
- `401` Unauthorized
- `404` VPC endpoint not found

### GET /organizations/{organization_id}/vpc/vpc_endpoints

Operation ID: `list_org_vpc_endpoints_alias`
Operation page: `/api/operations/list_org_vpc_endpoints_alias`
List VPC endpoints for an organization (alias path with underscores)

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization

Responses:
- `200` List of VPC endpoints (application/json: DataResponse_Vec_OrganizationVpcEndpoint)
- `401` Unauthorized
- `404` Organization not found

## webhooks

### POST /webhooks/stripe

Operation ID: `handle_stripe_webhook`
Operation page: `/api/operations/handle_stripe_webhook`
Handle Stripe webhook events

Responses:
- `200` Webhook processed
- `400` Invalid webhook signature
- `500` Internal server error

## Webhooks

### GET /organizations/{organization_id}/webhooks

Operation ID: `list_webhooks`
Operation page: `/api/operations/list_webhooks`
List webhooks for an organization

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization

Responses:
- `200` Webhooks retrieved successfully (application/json: DataResponse_Vec_WebhookInfo)
- `401` Unauthorized
- `403` Forbidden - not a member of this organization

### POST /organizations/{organization_id}/webhooks

Operation ID: `create_webhook`
Operation page: `/api/operations/create_webhook`
Create a webhook

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization

Request body (required):
- `application/json`: CreateWebhookRequest

Responses:
- `201` Webhook created successfully (application/json: DataResponse_WebhookCreated)
- `400` Invalid request
- `401` Unauthorized
- `403` Forbidden - not a member of this organization

### DELETE /organizations/{organization_id}/webhooks/{webhook_id}

Operation ID: `delete_webhook`
Operation page: `/api/operations/delete_webhook`
Delete a webhook

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `webhook_id` (path, required): string / uuid - Webhook ID

Responses:
- `204` Webhook deleted successfully
- `401` Unauthorized
- `403` Forbidden - not a member of this organization
- `404` Webhook not found

### GET /organizations/{organization_id}/webhooks/{webhook_id}

Operation ID: `get_webhook`
Operation page: `/api/operations/get_webhook`
Get a specific webhook

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `webhook_id` (path, required): string / uuid - Webhook ID

Responses:
- `200` Webhook retrieved successfully (application/json: DataResponse_WebhookInfo)
- `401` Unauthorized
- `403` Forbidden - not a member of this organization
- `404` Webhook not found

### PATCH /organizations/{organization_id}/webhooks/{webhook_id}

Operation ID: `update_webhook`
Operation page: `/api/operations/update_webhook`
Update a webhook

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `webhook_id` (path, required): string / uuid - Webhook ID

Request body (required):
- `application/json`: UpdateWebhookRequest

Responses:
- `200` Webhook updated successfully (application/json: DataResponse_WebhookInfo)
- `400` Invalid request
- `401` Unauthorized
- `403` Forbidden - not a member of this organization
- `404` Webhook not found

### GET /organizations/{organization_id}/webhooks/{webhook_id}/deliveries

Operation ID: `list_webhook_deliveries`
Operation page: `/api/operations/list_webhook_deliveries`
List recent deliveries for a webhook

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `webhook_id` (path, required): string / uuid - Webhook ID

Responses:
- `200` Deliveries retrieved successfully (application/json: DataResponse_Vec_WebhookDelivery)
- `401` Unauthorized
- `403` Forbidden - not a member of this organization
- `404` Webhook not found

### POST /organizations/{organization_id}/webhooks/{webhook_id}/rotate-secret

Operation ID: `rotate_webhook_secret`
Operation page: `/api/operations/rotate_webhook_secret`
Regenerate webhook secret

Parameters:
- `organization_id` (path, required): string / uuid - Organization ID or 'default' for authenticated user's default organization
- `webhook_id` (path, required): string / uuid - Webhook ID

Responses:
- `200` Secret rotated successfully (application/json: DataResponse_WebhookCreated)
- `401` Unauthorized
- `403` Forbidden - not a member of this organization
- `404` Webhook not found

### GET /webhooks/event-types

Operation ID: `list_event_types`
Operation page: `/api/operations/list_event_types`
List available event types

Responses:
- `200` Event types retrieved successfully (application/json: DataResponse_Vec_String)
- `401` Unauthorized

## Workspaces

### GET /publishers/seren-storage/buckets/{bucket_slug}/workspace-snapshots

Operation ID: `seren_storage_list_workspace_snapshots`
Operation page: `/api/operations/seren_storage_list_workspace_snapshots`

Parameters:
- `bucket_slug` (path, required): string - Storage bucket slug
- `deployment_id` (query, required): string / uuid
- `limit` (query): integer / int64

Responses:
- `200` Workspace snapshots retrieved (application/json: SerenStorageDataResponse_Vec_ObjectStorageWorkspaceSnapshot)

### POST /publishers/seren-storage/buckets/{bucket_slug}/workspace-snapshots

Operation ID: `seren_storage_create_workspace_snapshot`
Operation page: `/api/operations/seren_storage_create_workspace_snapshot`

Parameters:
- `bucket_slug` (path, required): string - Storage bucket slug

Request body (required):
- `application/json`: SerenStorageCreateObjectStorageWorkspaceSnapshotRequest

Responses:
- `201` Workspace snapshot registered (application/json: SerenStorageDataResponse_ObjectStorageWorkspaceSnapshot)

### GET /publishers/seren-storage/buckets/{bucket_slug}/workspace-snapshots/latest

Operation ID: `seren_storage_latest_workspace_snapshot`
Operation page: `/api/operations/seren_storage_latest_workspace_snapshot`

Parameters:
- `bucket_slug` (path, required): string - Storage bucket slug
- `deployment_id` (query, required): string / uuid

Responses:
- `200` Latest workspace snapshot download created (application/json: SerenStorageDataResponse_ObjectStorageWorkspaceSnapshotDownload)
- `404` Workspace snapshot not found (application/json: SerenStorageErrorBody)