> ## Documentation Index > Fetch the complete documentation index at: https://docs.creao.ai/llms.txt > Use this file to discover all available pages before exploring further. # Replace an agent > Replace a personal CREAO agent with a zip bundle and save it as a new version. ## OpenAPI ````yaml /developer-api/developer-v1.openapi.yaml put /v1/agents/{agent_id} openapi: 3.1.0 info: title: CREAO CLI version: 1.0.0 description: | Create, update, and run personal CREAO agents from your backend through CREAO CLI with Account API keys. The `/v1` API uses stable `agent_id`, `conversation_id`, and `run_id` identifiers and is served from `developer.creao.ai`. servers: - url: https://developer.creao.ai description: Production security: - bearerAuth: [] - apiKeyQuery: [] tags: - name: Agents description: >- Create, list, get, update, and edit personal agents for the authenticated account. - name: Agent Memory description: >- Read, overwrite, and clear long-term memory (playbooks) for a personal agent. - name: Agent Files description: List, download, and delete files in a personal agent's skill file space. - name: Product Profile description: Once-per-account Super Agent persona and brand context. - name: Agent Runs description: >- Create, stream, fetch, and list runs for created personal agents. Super Agent rows are excluded. `usage.models` is present only for Super Agent–allowlisted accounts. - name: Super Agent description: >- Chat with CREAO Super Agent from your backend. Same public NDJSON render protocol as Agent Runs. Requires an allowlisted account. `usage.models` is present only for Super Agent–allowlisted accounts. - name: Account description: Read the calling account's platform-wallet balance and CREAO CLI spend. - name: Workspaces description: Create and list personal workspaces, and add or remove personal agents. - name: Workspace Files description: Upload, list, download, and delete files in a personal workspace. - name: Secrets description: Add, update, and list account secret keys. Values are write-only. - name: Skills description: Install, list, and enable account-level Agent Brain skills. - name: Rooms description: >- Read team rooms, post messages as the key's owner, and stream room events. The key acts as its owner. paths: /v1/agents/{agent_id}: put: tags: - Agents summary: Replace an agent and save a version description: > Replace a personal CREAO agent's whole content with a zip bundle and save it as a new version in the same request. Runs, share links, downloads and the version history all see the same content afterwards. The zip has the same layout as on [Create an agent](/developer-api/agents/create-agent): `SKILL.md` and `config.yaml` at the root, an optional `dashboard.json`, and mounted files under `files/`. Files the zip leaves out are deleted from the agent. The `version` in `config.yaml` must be greater than every version the agent has saved, compared number by number (`0.1` counts as `0.1.0`); [Get an agent](/developer-api/agents/get-agent) returns the current one in `latest_version`. Team, shared, deleted, or foreign agents return `AGENT_NOT_FOUND`. operationId: replaceAgent parameters: - name: agent_id in: path required: true description: Personal CREAO agent to replace. schema: type: string format: uuid requestBody: required: true content: multipart/form-data: schema: $ref: '#/components/schemas/AgentBundleUpload' responses: '200': description: Agent replaced and saved as a new version. content: application/json: schema: $ref: '#/components/schemas/Agent' '400': description: | The bundle is not valid. `INVALID_BUNDLE` for a missing `SKILL.md` or `config.yaml`, invalid YAML, a missing `name`, an entry outside `files/`, or a bad `dashboard.json`; `INVALID_AGENT_VERSION` when `version` is not three numbers such as `"1.2.0"`; `INVALID_AGENT_FILE_PATH` for a path with a `..` segment or longer than 512 characters; `AGENT_FILE_LIMIT_REACHED` for more than 50 files. `reason` says what to fix. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingSkill: value: error: INVALID_BUNDLE reason: bundle must contain SKILL.md at its root badVersion: value: error: INVALID_AGENT_VERSION reason: >- config.yaml version must be three numbers like "1.0.0" (got 1); quote it if YAML reads it as a number '401': $ref: '#/components/responses/AuthenticationRequired' '402': description: | `INSUFFICIENT_CREDITS` when the account has no credits left, or `TEAM_STORAGE_QUOTA_EXCEEDED` when the new files do not fit the plan's storage. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': $ref: '#/components/responses/AccountBlocked' '404': description: Agent not found for this account or not writable through CREAO CLI. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: agentNotFound: value: error: AGENT_NOT_FOUND '409': description: | Nothing was changed. `AGENT_VERSION_NOT_INCREASED`: the bundle's `version` is not greater than the agent's latest saved version, returned in `latest_version`. `AGENT_SAVE_IN_PROGRESS`: another save of this agent is still running; send the bundle again when it finishes. `AGENT_FILES_CHANGED`: the agent's files changed while the bundle was being saved, for example from the CREAO app; send it again. `AGENT_FILE_PATH_TAKEN`: a file the agent produced already uses one of the bundle's paths; rename it in the bundle. `reason` says which. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: versionNotIncreased: value: error: AGENT_VERSION_NOT_INCREASED reason: >- config.yaml version 1.2.0 must be greater than the latest saved version 1.2.0 latest_version: 1.2.0 '413': description: >- The zip is larger than 100 MB, or one file in it is larger than 20 MB. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: fileTooLarge: value: error: FILE_TOO_LARGE '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/ServiceUnavailable' components: schemas: AgentBundleUpload: type: object required: - bundle properties: bundle: type: string format: binary description: | The whole agent as a zip of at most 100 MB: - `SKILL.md` at the root (required, at most 256 KB). - `config.yaml` at the root (required, at most 128 KB) with `name`, `version` (three numbers such as `"1.2.0"`; quote it so YAML keeps it as text) and an optional `description`. - `dashboard.json` at the root (optional, at most 512 KB). - Mounted files under `files/`, kept at the same relative path in runs. Each file can be up to 20 MB, and an agent holds at most 50 files including `SKILL.md`. `manifest.json` and `files/SKILL.md`, which downloaded bundles carry, are ignored. release_note: type: string maxLength: 2000 description: Optional note saved with the version. Agent: type: object required: - agent_id - name - description - version - status - write_autonomy - default_model_id - default_thinking_level - created_at - updated_at properties: agent_id: type: string format: uuid description: Personal CREAO agent ID. name: type: string description: oneOf: - type: string - type: 'null' version: type: string status: type: string description: Current agent status. Created agents return `active`. write_autonomy: $ref: '#/components/schemas/WriteAutonomy' default_model_id: oneOf: - type: string - type: 'null' description: >- Model the agent runs with when a run omits `model`. `null` means CREAO chooses the model automatically. default_thinking_level: oneOf: - $ref: '#/components/schemas/ThinkingLevel' - type: 'null' description: >- Thinking level saved for `default_model_id`. `null` means the model's own default. created_at: type: string format: date-time updated_at: type: string format: date-time skill_content: oneOf: - type: string - type: 'null' description: >- Full SKILL.md. Present on GET-by-id and PATCH. Omitted from list responses. config_content: oneOf: - type: string - type: 'null' description: >- Raw config YAML. Present on GET-by-id and PATCH. Omitted from list responses. config: oneOf: - type: object additionalProperties: true - type: 'null' description: >- Parsed config object. Present on GET-by-id and PATCH. Omitted from list responses. dashboard_template: oneOf: - $ref: '#/components/schemas/DashboardTemplate' - type: 'null' description: >- Dashboard template. Present on GET-by-id and PATCH. Omitted from list responses. latest_version: oneOf: - $ref: '#/components/schemas/AgentLatestVersion' - type: 'null' description: >- The agent's highest saved version, the floor for the next Replace an agent. Present on GET-by-id, create from a bundle and replace; `null` until the agent has a saved version. files: type: array items: $ref: '#/components/schemas/AgentFileEntry' description: >- The agent's file space, up to 50 files. Present on GET-by-id only. Omitted from list and PATCH responses. ErrorResponse: type: object additionalProperties: true required: - error properties: error: type: string description: Stable machine-readable error code. message: type: string description: Debug message. Do not rely on this field in production clients. available: type: number description: Available credits, when returned for credit errors. required: type: number description: Required credits, when returned for credit errors. retryAfterSeconds: type: integer description: Retry delay, when returned for hourly cap errors. reason: type: string description: >- A readable explanation on `400` and `409` room and agent bundle errors. Do not branch on it. latest_version: type: string description: The agent's latest saved version, on `AGENT_VERSION_NOT_INCREASED`. candidates: type: array description: >- Members a `ROOM_MENTION_AMBIGUOUS` name matches. Resend with one of their ids in `mentions` to pick it. items: type: object properties: member_id: type: string format: uuid kind: type: string enum: - user - agent name: oneOf: - type: string - type: 'null' WriteAutonomy: type: string enum: - full_auto - approval_required - blocked description: >- External write autonomy for guarded connector actions (write and delete actions in connected services). full_auto performs them immediately. A run started through /v1 cannot collect an approval, so on those runs approval_required and blocked both leave the action unperformed; the run still completes and the agent is told why. In the browser app, approval_required waits for your approval. Reads always run. ThinkingLevel: type: string enum: - low - medium - high - xhigh - max description: >- How much the model reasons before answering. Higher levels can improve hard tasks at the cost of latency and credits. DashboardTemplate: type: object additionalProperties: true description: >- JSON-render dashboard template. Serialized JSON must be 512 KB or smaller. AgentLatestVersion: type: object required: - version_id - version - created_at properties: version_id: type: string format: uuid version: type: string description: >- The highest version the agent has saved. A replace must send a greater one. created_at: type: string format: date-time AgentFileEntry: allOf: - $ref: '#/components/schemas/AgentFileDownload' - type: object required: - content properties: content: oneOf: - type: string - type: 'null' description: | UTF-8 text of the file when the request passed `include=file_content` and the file is a text or code file up to 256 KB that fits the 2 MB response budget. Otherwise null; use `download_url`. AgentFileDownload: allOf: - $ref: '#/components/schemas/AgentFile' - type: object required: - download_url - download_url_expires_at properties: download_url: type: string format: uri description: Presigned download URL (expires in 1 hour). download_url_expires_at: type: string format: date-time AgentFile: type: object required: - id - name - mime_type - size_bytes - sha256 - created_at properties: id: type: string format: uuid name: type: string mime_type: type: string size_bytes: oneOf: - type: integer - type: 'null' sha256: oneOf: - type: string - type: 'null' created_at: type: string format: date-time responses: AuthenticationRequired: description: Missing, malformed, revoked, or unknown Account API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingKey: value: error: AUTHENTICATION_REQUIRED AccountBlocked: description: >- Account is blocked from starting new runs, or the selected model is blocked by plan or entitlement access. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: accountBlocked: value: error: ACCOUNT_BLOCKED modelNotAllowed: value: error: MODEL_NOT_ALLOWED RateLimited: description: Account-level or IP-level rate limit exceeded. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rateLimited: value: error: RATE_LIMITED ServiceUnavailable: description: Agent execution service was unavailable before the run was accepted. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unavailable: value: error: SERVICE_UNAVAILABLE securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: cr_sk description: Account API key from Developer Console. Keys start with `cr_sk_`. x-default: cr_sk_your_key_here apiKeyQuery: type: apiKey in: query name: creao-api-key description: | Account API key passed as a query parameter, for platforms that cannot set a custom Authorization header. The bearerAuth header takes precedence when both are present. x-default: cr_sk_your_key_here ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.