> ## 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. # Add a workspace secret (the value is never returned) ## OpenAPI ````yaml https://api.sempera.org/openapi.json post /v1/secrets 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/secrets: post: tags: - Developer settings summary: Add a workspace secret (the value is never returned) operationId: createSecret parameters: [] requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string value: type: string type: type: string enum: - static - refresh refresh: type: object properties: url: type: string method: type: string enum: - GET - POST headers: type: object body: type: string interval_minutes: type: integer minimum: 1 maximum: 1440 json_path: type: string responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/WorkspaceSecret' '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: - tools:write components: schemas: WorkspaceSecret: type: object required: - id - object - name - key - type - status - reference - id_reference - has_value - archived - created_by - updated_by - created_at - updated_at - refresh properties: id: type: string object: const: secret name: type: string key: type: string type: enum: - Static - Refresh status: enum: - Active - Paused reference: type: string id_reference: type: string has_value: type: boolean archived: type: boolean created_by: type: - string - 'null' updated_by: type: - string - 'null' created_at: type: - string - 'null' updated_at: type: - string - 'null' refresh: type: - object - 'null' description: Refresh configuration without credentials or request body. properties: url: type: - string - 'null' method: type: - string - 'null' header_names: type: array items: type: string interval_minutes: type: - integer - 'null' json_path: type: - string - 'null' last_refreshed_at: type: - string - 'null' last_attempt_at: type: - string - 'null' last_error: type: - string - 'null' 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 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.