# Agent Operations Record real agent activity in private workspaces, coordinate evidence reviews and evaluate versioned policies. Open https://www.rightshold.com/operations and unlock with your account API key. The console keeps the key in memory and clears private views when locked. It never stores your key in browser storage. Account creation and key management are available at https://www.rightshold.com/#account. ## Authentication and access Send your key in the Authorization header: Bearer $RIGHTSHOLD_API_KEY. Do not put keys in URLs. Operations routes are authenticated and return private account data. Each workspace has its own membership: owners and administrators manage the team, operators record activity, reviewers record review decisions, and viewers can inspect evidence. The API enforces the permission checks independently of the console. ## Start a workspace POST /v1/operations/workspaces with a JSON object containing name and optional description. GET the same path to list your workspaces. GET /v1/operations/workspaces/{workspace_id} returns the workspace, your membership and capabilities. Preserve revision values when changing configuration so concurrent edits can be detected. ## Record actual events POST /v1/operations/workspaces/{workspace_id}/streams with name and optional description and config. POST /v1/operations/workspaces/{workspace_id}/streams/{stream_id}/events with client_event_id and action_type. Optional fields include occurred_at, outcome, severity, summary, action_sha256 and tags. Use a stable client_event_id for retries; reusing it with different event contents is rejected. occurred_at describes the claimed action time and defaults to receipt time when omitted; the service records received_at separately. For a batch, POST to the stream's /events/batch path with mode set to atomic or partial, an events array and an optional idempotency_key. Atomic mode rejects the whole batch when an event fails validation. Partial mode returns an indexed result for each submitted event. Inspect those results before retrying. The console accepts only activity you supply; it creates no activity on your behalf. POST to the stream's /reconcile path with client_event_ids to determine which identifiers are recorded or missing. To recover after a lost acknowledgement, also send expected_events containing the exact original event bodies in the same order. Content comparison distinguishes recorded matches from conflicts; a matching identifier alone cannot establish that the contents match. Reconciliation sends no new events. Retrieve /chain to inspect the private stream chain. For durable delivery, download https://www.rightshold.com/sdks/rightshold_operations.py or https://www.rightshold.com/sdks/rightshold-operations.cjs. The clients persist an explicitly enabled local outbox, preserve event identifiers across retries, reconcile uncertain results and quarantine conflicting submissions for a recorded manual decision. Keep the outbox directory private and pass credentials separately. Sending occurs only when you invoke flush or reconcile; neither client starts a background sender. Inspect retained records and capacity before choosing an outbox size. Each batch and reconciliation accepts at most 100 events or identifiers. Events are limited to 32 KiB; ordinary operations JSON bodies to 1 MiB; online case verification to 4 MiB. Stream configuration may impose lower event and volume budgets. Read https://www.rightshold.com/v1/operations/spec for the contract and limits. ## Give an agent limited access Use your account API key to manage the workspace, then issue a separate stream-scoped token for deployed agents. POST /v1/operations/workspaces/{workspace_id}/credentials with stream_id, label, scopes, expires_in_days and daily_event_limit. Available scopes are ingest, reconcile, read and export. Select only what the agent needs. Credentials expire within 90 days, remain bound to the issuing account's workspace access and can be revoked immediately. The response contains a token beginning with rso_ exactly once. Transfer it directly to your agent's secret store. The console displays it transiently and copies it only when requested. GET the credentials collection to inspect metadata without revealing tokens; POST /credentials/{credential_id}/rotate to revoke the previous credential and receive a replacement token, or /revoke to stop its access. A scoped credential cannot manage accounts, memberships, policies or billing. Send this credential to POST /v1/operations/ingest with workspace_id, stream_id and the batch fields above. POST /v1/operations/reconcile accepts the same binding fields plus reconciliation fields. GET /v1/operations/credentials/self reports its grants and current usage. With the respective scopes, GET /v1/operations/records/{stream_id}/{event_id} reads an event and its /export path returns private evidence. Role or membership changes and workspace or stream archival revoke affected credentials permanently; restoring access requires a newly issued token. ## Explore and export GET a stream's /events path with limit, cursor, action_type, outcome, severity, tag, search, from and to filters. Keep filters unchanged when following next_cursor. GET /events/{event_id} for the event and /events/{event_id}/export for its signed evidence bundle. Keep downloaded exports private: they include the event details you opened. Sandbox events have no public ledger export. For offline verification, download https://www.rightshold.com/cli/verify-activity.cjs and obtain a trusted issuer key independently from https://www.rightshold.com/.well-known/rightshold-keys.json. Verify the export using the pinned key. The signed receipt and inclusion proof establish the issuer's commitment and inclusion, not execution of the claimed action or independent ledger finality. ## Review a casefile POST /v1/operations/workspaces/{workspace_id}/cases with title, optional description, severity, checklist and actual event_ids. Case severity is low, medium, high or critical. A checklist contains objects with id, label and optional min_events. GET /cases/{case_id} for current evidence, decisions and version. Append evidence with POST /events, append a note with POST /notes using body, and assign a current owner, administrator or reviewer with POST /assign. Changes use expected_version from the latest case response. POST /cases/{case_id}/decision with decision set to accepted, needs_information or rejected, a reason, selected event_ids and expected_version. Closing and reopening require a reason. Reviews record an accountable assessment; they do not rewrite the original events. POST /cases/{case_id}/export to obtain a signed manifest containing the selected evidence and case history. Verify the signature using a separately pinned issuer key. ## Evaluate policies and handle exceptions GET or POST /v1/operations/workspaces/{workspace_id}/policies to list or create policies. A policy requires name, stream_id and rules; supported checks include alert_on_failure, min_severity, allowed_action_types, require_action_sha256, max_arrival_delay_seconds, require_sequence_continuity, require_digest_chain, stale_after_seconds and a window object for volumes or failure rates. A window has seconds, from 60 to 86400, and at least one of min_events, max_events or max_failure_rate. Failure rates range from 0 to 1; min_samples controls when a rate check applies. Policy versions retain explicit rule configuration. POST /policies/{policy_id} with expected_version and changed fields to save a new version. Evaluate a policy against recorded activity through its /evaluate action. Inspect its /versions history before changing the rules and /evaluations for the recorded scan history. Follow returned cursors to continue longer histories. Evaluation creates a private exceptions queue and does not send external notifications. GET /v1/operations/workspaces/{workspace_id}/exceptions to inspect findings. POST /exceptions/{exception_id}/transition with expected_version, status, reason and optional assignee_tenant_id. Status is open, acknowledged or resolved. Assign only current members with review access. Evaluation results describe the evidence available at evaluation time. Review the workspace /health response for actual activity and backlog counts. ## Invite a team POST /v1/operations/workspaces/{workspace_id}/invites with the intended existing account's target_tenant_id, role and optional expires_in_hours. The invitation token is returned once. Share it privately; Rightshold does not send it. The invited account accepts through POST /v1/operations/invites/accept with token. Administrators can cancel pending invitations and change or remove memberships. Ownership transfer requires an active target member, and a workspace must retain an owner. GET /v1/operations/workspaces/{workspace_id}/audit for the private, append-only access and workflow history. Archive workspaces and streams when recording should stop; recorded evidence remains subject to the service's evidence rules.