> ## Documentation Index > Fetch the complete documentation index at: https://veryfront.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Rename Agent > Renames an agent to a new identifier. The rename rejects while the target identifier is occupied, while colocated capability files (such as agents/{agent_id}/SKILL.md) would be stranded under the old identifier, or while schedules or channel bindings still reference the agent. When the agent has a generated avatar, the avatar is first copied to the new identity and the renamed agent references the copy. The previous avatar upload and storage object are left in place because preview branches and immutable releases can still reference them; their cleanup is asynchronous, handled by the reference-aware avatar garbage collector once nothing references them anymore. Agent labels follow the renamed identifier. ## OpenAPI ````yaml https://api.veryfront.com/openapi.json post /projects/{project_reference}/agents/{agent_id}/rename openapi: 3.1.0 info: title: Veryfront REST API version: 1.0.0 summary: Domain-first REST reference for the maintained Veryfront HTTP API surface. description: >- Project-first HTTP API for Veryfront project resources. Root account/platform endpoints that still appear in this reference are transitional compatibility surfaces unless the canonical inventory marks them otherwise. ## Start here - **Interactive REST reference:** [/docs](/docs) - **Raw OpenAPI document:** [/openapi.json](/openapi.json) - **Canonical inventory:** `docs/api-surface-inventory.md` in this repository - **GraphQL endpoint:** [/graphql](/graphql) - **MCP playground:** [/mcp/playground](/mcp/playground) ## Authentication Use one of these request headers: - `Authorization: Bearer ` - `Authorization: Bearer vf__` - `X-API-Key: vf__` JWTs must use the Bearer token contract. API keys work in either the Bearer header or `X-API-Key`. ## Discovery model Veryfront is one platform with multiple access modes: - **REST** for resource-oriented and operational HTTP workflows - **GraphQL** for connected app-facing data and typed mutations - **MCP** for tool-style automation and agent workflows For the fastest path through the platform, start with the project-scoped domain groups. Transitional account/platform groups are retained for compatibility and follow the removal register in the canonical inventory. contact: name: Veryfront API Support url: https://veryfront.com/docs email: support@veryfront.com servers: - url: https://api.veryfront.com description: Current request origin - url: http://localhost:4000 description: Local development security: - bearerAuth: [] - apiKeyAuth: [] tags: - name: Projects description: Core project operations - name: Account description: >- Transitional account-level users and settings retained for dashboard compatibility - name: Project Users description: Project members and invites - name: Members description: Project members and invites - name: Files description: Main branch files - name: Branch Files description: Files on branches - name: Environment Files description: Files in environments - name: Release Files description: Files in releases - name: Uploads description: File uploads and assets - name: Branches description: Content branches for previews - name: Releases description: Published file snapshots - name: Deployments description: Connect releases to environments - name: Environments description: Deployment targets and variables - name: Environment Variables description: Project environment variable management - name: Domains description: Custom domains for environments - name: Project Servers description: Project-scoped dedicated server instances - name: Root Servers description: >- Transitional root dedicated-server administration retained for compatibility - name: Tasks description: Project tasks - name: Evals description: Project eval definitions and eval run projections - name: Workflows description: Project workflows - name: Workflow Runs description: Workflow run history and status - name: Schedules description: Recurring project automation schedules - name: Webhooks description: Webhook-triggered automation entry points - name: Skills description: Project skills - name: Prompts description: Project prompts - name: Tools description: Project tools - name: Resources description: Project-defined resource documents and source-backed resource definitions - name: Sandboxes description: Ephemeral sandbox execution environments - name: Search description: Text and vector search - name: Knowledge description: Knowledge manifest lookup across project knowledge files - name: Chunks description: File chunks for search indexing - name: Embeddings description: Vector embeddings - name: RAG Documents description: Project retrieval-augmented knowledge documents - name: Style Artifacts description: Project style artifact state and build outputs - name: Dependencies description: >- npm dependency resolution, exact-version pinning, and signed runtime artifact registry contracts - name: External Storage description: Transitional connected cloud-provider file operations - name: Project Cache description: Project-scoped distributed cache operations - name: User Cache description: Transitional user cache helpers retained for compatibility - name: API Keys description: >- Transitional user/account API key management; prefer project-scoped keys for public integrations - name: User description: Transitional current-user profile endpoint for first-party clients - name: Favorites description: Transitional user favorites for first-party dashboard clients - name: Subscriptions description: Transitional account billing and subscription workflows - name: Credits description: Transitional account credit balance, purchase, and insufficiency flows - name: Usage description: >- Project/account usage limits and warnings; account-level usage is transitional - name: Gates description: Transitional plan and feature gate checks for first-party clients - name: Channels description: Project channel integrations and delivery settings - name: Agents description: Project agents - name: Agent Templates description: >- Public template catalog of addable agents assembled from curated template projects - name: Agent Workers description: Internal/transitional agent worker leases and sessions - name: Agent Runtimes description: Registered push-based agent runtime services and runtime target health - name: Project Integrations description: Project-scoped integration catalog and configuration - name: Integrations description: Transitional external integration catalog for first-party clients - name: Connections description: Viewer-visible project and project-user integration connections - name: Integration Tools description: >- Transitional dynamic integration tool listing, invocation, and connection state - name: OAuth description: >- Transitional OAuth integration flows for first-party and connected-app clients - name: Templates description: Transitional starter-template discovery used during project creation - name: AI description: >- Transitional platform AI gateway/model helpers; project AI assets use project-scoped routes - name: Images description: Generated images and image assets - name: Conversations description: Transitional conversation/run-control HTTP surface for first-party clients - name: Runs description: Transitional hosted run-control endpoints for conversation execution - name: MCP description: >- MCP catalog/playground helpers; primary MCP traffic uses the streamable MCP handler - name: Logs description: Project log queries via Loki - name: Metrics description: Project metric queries via a Prometheus-compatible backend - name: Traces description: Project trace queries via Grafana Tempo - name: Errors description: Internal/public error type catalog (RFC 9457) - name: Authentication description: Transitional auth token, login, logout, magic-link, and JWKS flows externalDocs: description: Interactive REST reference url: https://api.veryfront.com/docs paths: /projects/{project_reference}/agents/{agent_id}/rename: post: tags: - Agents summary: Rename Agent description: >- Renames an agent to a new identifier. The rename rejects while the target identifier is occupied, while colocated capability files (such as agents/{agent_id}/SKILL.md) would be stranded under the old identifier, or while schedules or channel bindings still reference the agent. When the agent has a generated avatar, the avatar is first copied to the new identity and the renamed agent references the copy. The previous avatar upload and storage object are left in place because preview branches and immutable releases can still reference them; their cleanup is asynchronous, handled by the reference-aware avatar garbage collector once nothing references them anymore. Agent labels follow the renamed identifier. operationId: renameAgent parameters: - $ref: '#/components/parameters/ProjectReference' - schema: type: string description: Current agent identifier required: true name: agent_id in: path - schema: type: string required: false name: source_target_kind in: query - schema: type: - string - 'null' format: uuid required: false name: target_branch_id in: query requestBody: content: application/json: schema: type: object properties: new_agent_id: type: string minLength: 1 maxLength: 128 pattern: ^[a-zA-Z0-9_-]+$ description: New agent identifier. Must not be occupied by another agent. required: - new_agent_id responses: '200': description: Agent renamed content: application/json: schema: $ref: '#/components/schemas/ProjectAgent' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/SourcePrimitiveErrorEnvelope' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/SourcePrimitiveErrorEnvelope' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/SourcePrimitiveErrorEnvelope' components: parameters: ProjectReference: schema: $ref: '#/components/schemas/ProjectReference' required: true description: Project slug, UUID, or domain that identifies the project. name: project_reference in: path schemas: ProjectAgent: type: object properties: id: type: string name: type: string description: type: - string - 'null' model: type: - string - 'null' system_prompt: type: - string - 'null' thinking: type: object properties: enabled: type: boolean budget_tokens: type: number exclusiveMinimum: 0 required: - enabled additionalProperties: false temperature: type: - number - 'null' minimum: 0 maximum: 2 max_steps: type: - integer - 'null' exclusiveMinimum: 0 allowed_models: type: array items: type: string skill_ids: type: array items: type: string skill_selection: type: object properties: kind: type: string enum: - omitted - explicit skill_ids: type: array items: type: string required: - kind - skill_ids all_tools_enabled: type: boolean tool_ids: type: array items: type: string provider_tool_ids: type: array items: type: string suggestions: type: array items: anyOf: - type: string minLength: 1 - type: object properties: title: type: string minLength: 1 prompt: type: string minLength: 1 required: - title - prompt additionalProperties: false avatar: type: - object - 'null' properties: seed: type: string minLength: 1 maxLength: 128 description: The seed associated with this record. archetype: type: string enum: - upright - slumped - alert - profile - leaning - crouched - tall - spread - happy - sad - angry - surprised - sleepy - curious description: The archetype associated with this record. texture: type: string pattern: ^(?:[0-9]|none)$ description: The texture associated with this record. color: type: string pattern: ^#[0-9a-fA-F]{6}$ description: The color associated with this record. shape: type: string enum: - snircle - circle - square description: The shape associated with this record. matrix: type: string pattern: ^[012]{16}$ description: The matrix associated with this record. description: Structured config details associated with this record. avatar_url: type: - string - 'null' format: uri description: >- Absolute URL for this agent avatar. Null when no custom avatar has been set. security_enabled: type: - boolean - 'null' description: Whether the agent default security guardrails are enabled. source_path: type: string source: type: string edit_mode: type: string enum: - structured - source_only source_only_reasons: type: array items: type: string required: - id - name - description - model - system_prompt - temperature - max_steps - allowed_models - skill_ids - skill_selection - all_tools_enabled - tool_ids - provider_tool_ids - security_enabled - source_path - source - edit_mode - source_only_reasons SourcePrimitiveErrorEnvelope: type: object properties: type: type: string title: type: string status: type: number detail: type: string error: type: string message: type: string edit_mode: type: string enum: - structured - source_only source_only_reasons: type: array items: type: string source_path: type: string ProjectReference: type: string securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT or API Key description: >- Use a JWT bearer token or a Veryfront API key in the Authorization header. apiKeyAuth: type: apiKey in: header name: X-API-Key description: Alternative API key header for vf__ tokens. ````