---
title: "Create Agent"
method: POST
path: "/api/agents"
tags: ["agents"]
---

# Create Agent

`POST /api/agents`

## Request

- Base URL: `https://app.thinqos.com` (the document declares no server; this is the origin it was published from)
- URL: `https://app.thinqos.com/api/agents`
- Auth: none declared

Create a new agent owned by the current identity.

TOS-318: when ``body.tts_voice`` is omitted, the handler picks an
ElevenLabs voice via ``suggest_voice`` (4s hard timeout) and writes
it to ``identities.tts_voice`` before returning. On any failure path
it writes ``PLATFORM_FALLBACK_VOICE_ID`` instead. The agent is NEVER
persisted with a NULL voice.

## Headers

- `x-impersonate-identity-id` string, nullable

## Request body

- AgentCreateBody
  - `wallet_source` 'creator' | 'own', nullable
  - `monthly_limit_usd` union
    - number
    - string
  - `proxy_config` ProxyConfiguration
    - `protocol` 'mcp' | 'a2a', required
    - `instance_id` string, uuid, required
    - `tool_name` string, nullable
    - `agent_card_url` string, nullable
    - `message_parameter` string
    - `conversation_parameter` string, nullable
    - `stream_parameter` string, nullable
    - `response_text_field` string, nullable
    - `response_conversation_field` string, nullable
  - `display_name` string, required
  - `charter` CharterDoc
    - `kind` 'agent' | 'organization' | 'person' | 'platform', required: Agent create/update accepts only agent. Other kinds are reserved for their corresponding identity APIs.
    - `purpose` string, nullable
    - `accountabilities` AccountabilityDoc[]
      - `statement` string, required
      - `cadence` 'continuous' | 'daily' | 'on_request' | 'weekly', required: continuous: standing responsibility on every applicable interaction; on_request: only when requested; daily/weekly: that recurrence. This field does not create a schedule. Preserve the requested meaning; never substitute an arbitrary accepted cadence.
      - `measures` MeasureDoc[]
        - `name` string, required
        - `kind` 'attestation' | 'count' | 'latency' | 'outcome' | 'rate', required
        - `window_days` 7 | 28, required
        - `source` union, required: Exactly one real evidence source. manual:true means owner attestation, not automated monitoring.
          - object
            - `manual` unknown, required
          - object
            - `review` string, required
          - object
            - `score` string, required
          - object
            - `signal` string, required
        - `target` union: Required for every kind except attestation.
          - number
          - string
        - `direction` 'at_least' | 'at_most'
      - `item_key` string, nullable
      - `applies_when` 'always' | 'delegate_only': delegate_only is valid only for a person charter.
    - `authority` AuthorityDoc[]
      - `decision_kind` 'send_message' | 'external_write' | 'spend' | 'contact_new_party' | 'change_own_config' | 'schedule_work' | 'delegate', required
      - `rung` 'understand' | 'recommend' | 'prepare' | 'act', required
      - `label` string, nullable
    - `boundaries` BoundaryDoc[]
      - `kind` 'action' | 'channel' | 'contact' | 'data' | 'decision' | 'spend' | 'time', required
      - `statement` string, required
      - `binding` union: A real supported control and its parameters, or null for wording only. Controls: spend_cap (usd_per_day >= 0), tool_policy (nonempty deny tool names or deny_connections UUIDs), reach (nonempty deny_folders UUIDs), approval (effect_class and mode pause/always_refuse), budget (positive max_tool_iterations or max_turn_seconds). The platform marker is reserved and unavailable to agent charters.
        - object
          - `control` 'spend_cap', required
          - `usd_per_day` number, required
        - unknown
        - unknown
        - object
          - `control` 'reach', required
          - `deny_folders` string[], required
        - object
          - `control` 'approval', required
          - `effect_class` 'metadata' | 'read' | 'draft' | 'low_impact_write' | 'external_communication' | 'material_write' | 'destructive' | 'privileged' | 'unknown', required
          - `mode` 'always_refuse' | 'pause', required
        - unknown
        - unknown
      - `enforcement` string, nullable: Descriptive text only; enforcement is derived from the actual supported binding.
      - `machine_form` object, nullable: A value machine form also requires claim_key on the boundary.
        - `kind` 'approval' | 'pattern' | 'scope' | 'spend' | 'value', required
      - `claim_key` string, nullable
    - `delegate_purpose` string, nullable
  - `charter_inherited_boundaries_reviewed` boolean
  - `charter_activate` boolean
  - `description` string, nullable
  - `tagline` string, nullable
  - `visual_brand_guidelines` string, nullable
  - `visual_brand_logo_url` string, nullable
  - `system_prompt` string, nullable: Mind Constitution: who the identity is. Distilled into identity, role, expertise, and trait beliefs in its Mind; instructions written here do NOT reach the model. Put rules in operating_instructions.
  - `operating_instructions` string, nullable: Operating Instructions: rules injected verbatim into every turn this identity answers. Empty string clears them.
  - `config` object
  - `status` 'active' | 'archived'
  - `connection_policy` 'off' | 'request' | 'auto', nullable
  - `tts_voice` string, nullable
  - `tts_voice_backup` string, nullable
  - `browser_automation_enabled` boolean
  - `web_browse_enabled` boolean
  - `communication_profile` CommunicationProfile
    - `preset` 'adaptive' | 'clear_direct' | 'warm_expressive' | 'formal_precise'
    - `schema_version` 1
    - `overrides` object
  - `reply_workflow` 'manual' | 'draft' | 'send'
  - `unreviewed_information_scope` 'limited' | 'full'
  - `learning_scope` 'private' | 'discretion' | 'open': TOS-6036: what an agent carries from one person it serves to the next. Owner-only, agent-level, stored at ``identity_config.config.learning_scope``. Distinct from :class:`UnreviewedInformationScope`, which only widens READ access for auto-sent replies and says nothing about what a teach WRITE is scoped to. * ``private`` keeps every learned item partitioned to the person who said it (the pre-TOS-6036 behaviour). * ``discretion`` (default) shares items classified ``about_work`` with everyone the agent serves and keeps ``about_person`` items private. * ``open`` shares everything the agent learns with everyone it serves.
  - `self_improvement_policy` 'off' | 'review' | 'minor'
  - `home_library_id` string, uuid, nullable
  - `verification_artifact` boolean

## Response `201`

Successful Response

- AgentResponse
  - `can_receive_chat` boolean
  - `funding_selection` object, nullable
  - `id` string, uuid, required
  - `display_name` string, required
  - `avatar_url` string, nullable, required
  - `description` string, nullable, required
  - `tagline` string, nullable
  - `visual_brand_guidelines` string, nullable
  - `visual_brand_logo_url` string, nullable
  - `system_prompt` string, nullable, required
  - `operating_instructions` string, nullable
  - `charter_creation` object, nullable
  - `can_edit_charter` boolean, nullable: Owner-only advisory for this detail request's charter edit authority. Missing/null is unknown; writes still recheck authority and charter version.
  - `config` object, required
  - `status` 'active' | 'archived', required
  - `connection_policy` 'off' | 'request' | 'auto', required
  - `owners` AgentOwnerResponse[], required
    - `owner_identity_id` string, uuid, required
    - `granted_at` string, required
    - `granted_by` string, uuid, nullable, required
    - `revoked_at` string, nullable, required
    - `revoked_by` string, uuid, nullable, required
    - `source` 'folder_admin' | 'controller'
  - `owned_by_caller` boolean
  - `relationship` 'myself' | 'built' | 'hired' | 'connected' | 'public'
  - `listing` ListingConsentResponse: TOS-3663 / TOS-5058: the owner's remaining Marketplace listing consent. ``available`` and ``disclosed`` were removed: whether an identity is listed, and whether its profile shows once listed, both derive from ``Identity.connection_policy`` (``off`` = not listed; otherwise listed with its profile shown). Stored at ``identity_config.config["listing"]``; a missing key reads as False.
    - `priced` boolean
  - `registration_ids` string[]
  - `tts_voice` string, nullable
  - `tts_voice_backup` string, nullable
  - `browser_automation_enabled` boolean
  - `web_browse_enabled` boolean
  - `communication_profile` CommunicationProfile
    - `preset` 'adaptive' | 'clear_direct' | 'warm_expressive' | 'formal_precise'
    - `schema_version` 1
    - `overrides` object
  - `reply_workflow` 'manual' | 'draft' | 'send'
  - `unreviewed_information_scope` 'limited' | 'full'
  - `learning_scope` 'private' | 'discretion' | 'open': TOS-6036: what an agent carries from one person it serves to the next. Owner-only, agent-level, stored at ``identity_config.config.learning_scope``. Distinct from :class:`UnreviewedInformationScope`, which only widens READ access for auto-sent replies and says nothing about what a teach WRITE is scoped to. * ``private`` keeps every learned item partitioned to the person who said it (the pre-TOS-6036 behaviour). * ``discretion`` (default) shares items classified ``about_work`` with everyone the agent serves and keeps ``about_person`` items private. * ``open`` shares everything the agent learns with everyone it serves.
  - `self_improvement_policy` 'off' | 'review' | 'minor'
  - `default_mode` 'human' | 'agent_augmented' | 'agent'
  - `self_improvement_mode` 'manual' | 'augmented' | 'autonomous'
  - `is_global` boolean
  - `kind` 'person' | 'agent'
  - `agent_key` string, nullable
  - `deleted_at` string, nullable
  - `archetype` string, nullable
  - `tags` string[]
  - `classification_source` string, nullable
  - `classified_at` string, nullable
  - `model_bundle` IdentityModelBundleResponse
    - `template_id` string, uuid, required
    - `template_name` string, required
    - `provider_family` string, required
    - `template_version` integer, required
    - `template_version_id` string, uuid, nullable
  - `home_library_id` string, uuid, nullable
  - `address` string, nullable
  - `home_domain_label` string, nullable
  - `ownership_source` 'home_folder' | 'controllers'
  - `home_folder` AgentHomeFolderResponse: The folder an agent lives in, named for the viewer who may see it (TOS-7857).
    - `id` string, uuid, required
    - `name` string, nullable, required
    - `is_private` boolean, required
  - `disclose_capabilities` boolean
  - `disclose_reputation` boolean
  - `warnings` string[]

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/thinqos/apis/thinqos-api.md) · [All operations](https://skmtc.dev/thinqos/apis/thinqos-api/llms.txt) · [OpenAPI document](https://skmtc.dev/thinqos/apis/thinqos-api/revisions/ce2c2ce318b1?raw)