> ## Documentation Index > Fetch the complete documentation index at: https://docs.sempera.org/llms.txt > Use this file to discover all available pages before exploring further. # Run a turn's situation against the step's current and a candidate instruction (nothing is saved) ## OpenAPI ````yaml https://api.sempera.org/openapi.json post /v1/testbed/runs openapi: 3.1.0 info: title: Sempera API version: 1.0.0 description: >- The Sempera API: agents, versions, sessions, calls, phone numbers, tools, integrations, knowledge, tests, evals, workspaces, API keys and webhooks, under one hostname. Read /llms.txt for the guide map. contact: name: Sempera url: https://sempera.org email: hello@sempera.org servers: - url: https://api.sempera.org security: [] tags: - name: Dialing pools description: Owned caller ID pools and side-effect-free selection previews. - name: Messaging description: >- Channel setup and stored conversations; transport activation remains gated. - name: Memory description: Workspace-scoped agent memory configuration and records. - name: Phone description: >- The personal phone plan: previewed, approved calls and texts on one number. - name: Batches description: Consent-bound outbound call batches and their recorded attempts. - name: SMS description: Workspace text conversations, guarded sends and human handoff. - name: Assistant description: >- Owner-session text Assistant settings, mobile linking and the owner's own thread. - name: Experiments description: Observed comparisons between published versions of an agent. - name: Meta description: The API's own front door. - name: Authentication description: Credential classes and scopes. - name: Agents description: 'The core product object: draft, preview, publish, versions.' - name: Sessions description: Channel-neutral conversations, and minting Web voice sessions. - name: Calls description: Phone calls (telephony lifecycle). - name: Phone numbers description: Number-to-agent binding. - name: Tools description: Workspace-level capabilities an agent attaches. - name: Integrations description: Provider connections. - name: Compatibility description: Observed read-only compatibility facades over Sempera canonical stores. - name: Snippets description: >- Versioned workspace code a code tool pins; published versions never change. - name: Knowledge description: Documents an agent answers from. - name: Personas description: Compiled agent identity, one persona per agent. - name: Tests description: Scripted scenarios before deployment. - name: Evals description: Judging completed conversations. - name: Alerts description: An organization's metric alert rules and each rule's trigger log. - name: Workspaces description: The tenant boundary. - name: Credits description: >- A workspace's credit balance and history, read only. Credits pay for building, never for live calls. - name: Automations description: >- Triggers: an event Sempera emits, conditions on it, and one action (a signed webhook or an owner email). - name: Platform description: Deployment identity and capacity, for CI and certification. - name: Organizations description: The membership and billing umbrella. - name: API keys description: Minting and revoking credentials. - name: Webhooks description: Sempera-signed outbound events. - name: Connected clients description: >- Every outside client connected to a workspace, whichever way it signed in, with scopes, last use and revocation. - name: MCP description: >- The MCP endpoint, per-client setup answers, and the revocable connections an owner gives outside AI clients. - name: Models description: Sempera's customer-eligible model catalog. - name: Prompts description: Stored prompts a workspace saves and reuses. - name: Scenarios description: >- An agent's scenarios (situations): create, archive, restore, copy and history. - name: Widgets description: Website widgets, web chat threads and custom components. - name: Citation schemas description: >- The outcome fields frozen with each published version, and how well they are captured. - name: Developer settings description: Developer-facing workspace settings. - name: Contacts description: Workspace contact grouping, resolution and the shared contact schema. - name: Voices description: >- The workspace voice collection: saved cleared voices, desk ratings, team sharing and professional clone preparation. paths: /v1/testbed/runs: post: tags: - Tests summary: >- Run a turn's situation against the step's current and a candidate instruction (nothing is saved) operationId: runTestbed parameters: - name: Idempotency-Key in: header required: false schema: type: string maxLength: 255 description: >- Replays the stored answer for a retry of the same request; 409 for a different request under the same key. responses: '202': description: Accepted content: application/json: schema: $ref: '#/components/schemas/TestbedRun' '400': description: Validation failed content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Authentication required or invalid credential content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Insufficient scope or role content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not found (or not in your scope) content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate limited (Retry-After) content: application/json: schema: $ref: '#/components/schemas/Error' security: - apiKey: - tests:write components: schemas: TestbedRun: type: object required: - id - object - agent_id - client - by - state - step - current_prompt - candidate_prompt - version_number - started_at - finished_at - detail - evidence_class - situations - summary - proposal properties: id: type: string object: const: testbed_run agent_id: type: string client: type: string by: type: string state: enum: - queued - running - completed - failed - interrupted step: type: string current_prompt: type: string candidate_prompt: type: - string - 'null' version_number: type: - integer - 'null' started_at: type: string finished_at: type: - string - 'null' detail: type: - string - 'null' evidence_class: const: TESTBED situations: type: array items: type: object required: - key - conversation_id - turn properties: key: type: string conversation_id: type: string turn: type: integer situation: $ref: '#/components/schemas/StandardSituation' redacted: type: boolean original: $ref: '#/components/schemas/TestbedOriginal' result: $ref: '#/components/schemas/TestbedComparison' scrubbed: type: string description: >- When call text expires, replaces situation, redacted, original and result. summary: type: - object - 'null' required: - situations - effects - reply_changed - route_changed - candidate_keeps_original_route - current_keeps_original_route properties: situations: type: integer effects: type: object additionalProperties: type: integer reply_changed: type: integer route_changed: type: integer candidate_keeps_original_route: type: integer current_keeps_original_route: type: integer proposal: type: - object - 'null' required: - applied - step - before - after - diff - change_request - note properties: applied: const: false step: type: string before: type: string after: type: string diff: type: string note: type: string change_request: type: - object - 'null' required: - intent - proposed_patch properties: intent: const: update_prompt_wording proposed_patch: type: object required: - spec - path - value properties: spec: const: agent.yaml path: type: array items: type: string value: type: string Error: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: string enum: - AGENT_ENV_UNPINNED - CALL_RL_PLAN_ALLOWANCE - CALL_RL_PLAN_CONCURRENCY - CALL_RL_PLAN_DAILY - CALL_RL_PLAN_DAILY_MINUTES - CALL_RL_PLAN_HOURLY - PHONE_AGENT_UNPINNED - PHONE_APPROVAL_EXPIRED - PHONE_APPROVAL_INVALID - PHONE_APPROVAL_REQUIRED - PHONE_COST_UNKNOWN - PHONE_DESTINATION_BLOCKED - PHONE_FUNDING_NOT_LIVE - PHONE_NUMBER_MISSING - PHONE_OUTSIDE_HOURS - PHONE_PLAN_INACTIVE - PHONE_RECIPIENT_OPTED_OUT - SMS_RL_PLAN_ALLOWANCE - SMS_RL_PLAN_DAILY - SMS_RL_PLAN_HOURLY - authentication_required - capability_unavailable - conflict - credits_exhausted - credits_unavailable - csrf_failed - forbidden - gone - idempotency_key_reused - insufficient_scope - internal_error - invalid_credential - method_not_allowed - not_found - owner_setup_required - payload_too_large - provider_failed - provider_timeout - rate_limited - service_unavailable - validation_failed - workspace_suspended message: type: string request_id: type: string field: type: string scope: type: string reason: type: string additionalProperties: true StandardSituation: type: object required: - script properties: script: type: array items: type: string caller_phone: type: string seed: type: object required: - history - collected properties: history: type: array items: type: object required: - caller - say properties: caller: type: string say: type: string collected: type: object additionalProperties: type: string TestbedOriginal: type: object required: - say - routed_to - captured properties: say: type: string routed_to: type: - string - 'null' captured: type: array items: type: string TestbedComparison: type: - object - 'null' required: - original - current - candidate - effect - reply_changed - route_changed - current_keeps_original_route - candidate_keeps_original_route properties: original: $ref: '#/components/schemas/TestbedOriginal' current: $ref: '#/components/schemas/TestbedSide' candidate: $ref: '#/components/schemas/TestbedSide' effect: enum: - not_run - error - unjudged - unchanged_pass - improved - regressed - unchanged_fail reply_changed: type: boolean route_changed: type: boolean current_keeps_original_route: type: - boolean - 'null' candidate_keeps_original_route: type: - boolean - 'null' TestbedSide: type: - object - 'null' required: - said - routed_to - captured - outcome - failed_because - error properties: said: type: string routed_to: type: - string - 'null' captured: type: array items: type: string outcome: type: - string - 'null' failed_because: type: - string - 'null' error: type: - string - 'null' securitySchemes: apiKey: type: http scheme: bearer bearerFormat: sempera_sk_... description: >- A workspace API key, sent as Authorization: Bearer sempera_sk_... Each operation names the one scope it needs. Scopes, key kinds and roles are in the Authentication guide. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.