> ## 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. # Edit an agent from instructions > Start an async natural-language edit for a personal agent. ## OpenAPI ````yaml /developer-api/developer-v1.openapi.yaml post /v1/agents/{agent_id}/edits openapi: 3.1.0 info: title: CREAO Developer API version: 1.0.0 description: | Create, update, and run personal CREAO agents from your backend 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: [] tags: - name: Agents description: Create, update, and edit personal agents for the authenticated account. - name: Runs description: Create, stream, fetch, and list Developer API runs. paths: /v1/agents/{agent_id}/edits: post: tags: - Agents summary: Edit an agent from instructions description: | Start an async natural-language edit for a personal CREAO agent. CREAO reads the current agent files, applies the requested changes through the same `modify-agentapp` workflow used by the main app, and persists a new agent version when the run succeeds. Use this endpoint when the caller wants to describe changes rather than send replacement fields. operationId: createAgentEdit parameters: - name: agent_id in: path required: true description: Personal CREAO agent to edit. schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAgentEditRequest' examples: addValuationSensitivity: summary: Add stock valuation analysis value: instructions: >- Add a valuation sensitivity table for the selected ticker and include a short note on downside risk. release_note: Add valuation sensitivity section. responses: '202': description: Agent edit accepted. content: application/json: schema: $ref: '#/components/schemas/AgentEdit' examples: queued: value: run_id: 11111111-1111-4111-8111-111111111111 agent_id: 00000000-0000-4000-8000-000000000000 status: queued created_at: '2026-07-03T10:00:00.000Z' started_at: null completed_at: null '400': $ref: '#/components/responses/InvalidInput' '401': $ref: '#/components/responses/AuthenticationRequired' '402': $ref: '#/components/responses/InsufficientCredits' '403': $ref: '#/components/responses/AccountBlocked' '404': description: >- Agent not found for this account or not editable through Developer API. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: agentNotFound: value: error: AGENT_NOT_FOUND '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/ServiceUnavailable' components: schemas: CreateAgentEditRequest: type: object additionalProperties: false required: - instructions properties: instructions: type: string minLength: 1 maxLength: 65536 description: Natural-language description of the changes to make to the agent. release_note: oneOf: - type: string maxLength: 2000 - type: 'null' description: >- Optional caller-provided release note for the persisted agent update. AgentEdit: type: object required: - run_id - agent_id - status properties: run_id: type: string format: uuid description: Backing Developer API run ID for polling/debugging. agent_id: type: string format: uuid status: $ref: '#/components/schemas/AgentEditStatus' result: type: object additionalProperties: true description: Terminal edit result when the edit succeeds. usage: $ref: '#/components/schemas/Usage' error: $ref: '#/components/schemas/RunError' created_at: type: string format: date-time started_at: oneOf: - type: string format: date-time - type: 'null' completed_at: oneOf: - type: string format: date-time - type: 'null' 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. AgentEditStatus: type: string enum: - queued - running - succeeded - failed - cancelled Usage: type: object required: - credits properties: credits: type: number description: Credits attributed to this Developer API run. RunError: type: object required: - code properties: code: type: string description: Stable machine-readable failure code. responses: InvalidInput: description: Invalid request shape, invalid UUID, or unsupported status filter. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidInput: value: error: INVALID_INPUT AuthenticationRequired: description: Missing, malformed, revoked, or unknown Account API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingKey: value: error: AUTHENTICATION_REQUIRED InsufficientCredits: description: Account does not have enough credits to start the run. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: insufficientCredits: value: error: INSUFFICIENT_CREDITS available: 0 required: 1000 AccountBlocked: description: Account is blocked from starting new runs. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: accountBlocked: value: error: ACCOUNT_BLOCKED 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 ````